AWS Documentation » Amazon Simple Queue Service » API Reference Guide » Actions » ReceiveMessage	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

ReceiveMessage

Description

The ReceiveMessage action retrieves one or more messages from the specified queue. Long poll support is enabled by using the WaitTimeSeconds parameter. For more information, see Amazon SQS Long Poll.

Short poll is the default behavior where a weighted random set of machines is sampled on a ReceiveMessage call. This 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.

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.

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

Going forward, new attributes might be added. If you are writing code that calls this action, we recommend that you structure your code so that it can handle new attributes gracefully.

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.

Name	Description	Required
`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
`WaitTimeSeconds`	Long poll support (integer from 1 to 20) - the duration (in seconds) that the `ReceiveMessage` action call will wait until a message is in the queue to include in the response, as opposed to returning an empty response if a message is not yet available. If you do not specify `WaitTimeSeconds` in the request, the queue attribute `ReceiveMessageWaitTimeSeconds` is used to determine how long to wait. Type: Integer from 0 to 20 (seconds) Default: The `ReceiveMessageWaitTimeSeconds` of 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.

Name Description

Name	Description
`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`. `SentTimestamp` and `ApproximateFirstReceiveTimestamp` are each returned as an integer representing the epoch time in milliseconds.

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. 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.

Error	Description	HTTP 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=AKIAIOSFODNN7EXAMPLE
&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>

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...