Print this pageEmail this pageGo to the ForumsView the PDFShare this page on TwitterShare this page on FacebookBookmark this page on DeliciousSubmit this page to RedditSubmit this page to DiggDid this page help you?  Yes  No   Tell us about it...

ReceiveMessage

Description

The ReceiveMessage action retrieves one or more messages from the specified queue. For each message returned, the response includes the following:

  • Message body

  • MD5 digest of the message body (for information about MD5, go to http://faqs.org/rfcs/rfc1321.html)

  • Message ID you received when you sent the message to the queue

  • Receipt handle

The receipt handle is the identifier you must provide when deleting the message (for more information, see Queue and Message Identifiers in the Amazon SQS Developer Guide).

[Note]Note

Due to the distributed nature of the queue, a weighted random set of machines is sampled on a ReceiveMessage call. That means only the messages on the sampled machines are returned. If the number of messages in the queue is small (less than 1000), it is likely you will get fewer messages than you requested per ReceiveMessage call. If the number of messages in the queue is extremely small, you might not receive any messages in a particular ReceiveMessage response; in which case you should repeat the request.

You can provide the VisibilityTimeout parameter in your request, which will be applied to the messages that SQS returns in the response. If you do not include the parameter, the overall visibility timeout for the queue is used for the returned messages. For more information, see Visibility Timeout in the Amazon SQS Developer Guide.

[Note]Note

Some API operations take lists of parameters. These lists are specified using the param.n notation. Values of n are integers starting from 1. For example, a parameter list with two elements looks like this:

&Attribute.1=this
&Attribute.2=that

Request Parameters

The following table lists the special request parameters the ReceiveMessage action uses in addition to the common request parameters all actions use (for more information, see Common Query Parameters).

NameDescriptionRequired

AttributeName.n

The attribute you want to get.

  • All—returns all values.

  • SenderId—returns the AWS account number (or the IP address, if anonymous access is allowed) of the sender.

  • SentTimestamp—returns the time when the message was sent (epoch time in milliseconds).

  • ApproximateReceiveCount—returns the number of times a message has been received but not deleted.

  • ApproximateFirstReceiveTimestamp—returns the time when the message was first received (epoch time in milliseconds).

Type: String

Valid values: All | SenderId | SentTimestamp | ApproximateReceiveCount | ApproximateFirstReceiveTimestamp

Default: None

No

MaxNumberOfMessages

Maximum number of messages to return. SQS never returns more messages than this value but might return fewer.

Not necessarily all the messages in the queue are returned (for more information, see the preceding note about machine sampling).

Type: Integer from 1 to 10

Default: 1

No

VisibilityTimeout

The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request.

Type: Integer

Constraints: 0 to 43200 (maximum 12 hours)

Default: The visibility timeout for the queue

No

Response Elements

The following table lists the response elements the ReceiveMessage action returns in addition to the common response elements all actions return (for more information, see Responses section in the Amazon SQS Developer Guide.

NameDescription

Message

An element containing the information about the message.

Ancestor: ReceiveMessageResult

Children:

  • Body—The message's contents (not URL encoded)

  • MD5OfBody—An MD5 digest of the non-URL-encoded message body string

  • MessageId—The message's SQS-assigned ID

  • ReceiptHandle—A string associated with a specific instance of receiving the message

  • Attribute—SenderId, SentTimestamp, ApproximateReceiveCount, and/or ApproximateFirstReceiveTimestamp. The SentTimestamp and ApproximateFirstReceiveTimestamp are each returned as an integer representing the epoch time in milliseconds.

Special Errors

The following table lists the special errors the ReceiveMessage action returns in addition to the common errors all actions return (for more information, see Common Errors).

ErrorDescriptionHTTP Status Code

ReadCountOutOfRange

The value for MaxNumberOfMessages is not valid (must be from 1 to 10).

400

Examples

The following example Query request receives messages from the specified queue.

Sample Request

http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/
?Action=ReceiveMessage
&MaxNumberOfMessages=5
&VisibilityTimeout=15
&AttributeName=All;
&Version=2009-02-01
&SignatureMethod=HmacSHA256
&Expires=2009-04-18T22%3A52%3A43PST
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&SignatureVersion=2
&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE

Sample Response

<ReceiveMessageResponse>
  <ReceiveMessageResult>
    <Message>
      <MessageId>
        5fea7756-0ea4-451a-a703-a558b933e274
      </MessageId>
      <ReceiptHandle>
        MbZj6wDWli+JvwwJaBV+3dcjk2YW2vA3+STFFljTM8tJJg6HRG6PYSasuWXPJB+Cw
        Lj1FjgXUv1uSj1gUPAWV66FU/WeR4mq2OKpEGYWbnLmpRCJVAyeMjeU5ZBdtcQ+QE
        auMZc8ZRv37sIW2iJKq3M9MFx1YvV11A2x/KSbkJ0=
      </ReceiptHandle>
      <MD5OfBody>
        fafb00f5732ab283681e124bf8747ed1
      </MD5OfBody>
      <Body>This is a test message</Body>
      <Attribute>
        <Name>SenderId</Name>
        <Value>195004372649</Value>
      </Attribute>
      <Attribute>
        <Name>SentTimestamp</Name>
        <Value>1238099229000</Value>
      </Attribute>
      <Attribute>
        <Name>ApproximateReceiveCount</Name>
        <Value>5</Value>
      </Attribute>
      <Attribute>
        <Name>ApproximateFirstReceiveTimestamp</Name>
        <Value>1250700979248</Value>
      </Attribute>
    </Message>
  </ReceiveMessageResult>
  <ResponseMetadata>
    <RequestId>
      b6633655-283d-45b4-aee4-4e84e0ae6afa
    </RequestId>
  </ResponseMetadata>
</ReceiveMessageResponse>

Related Actions