GET on MessageQueue

Description

The GET on MessageQueue action does one of the following:

Gets one or more messages from the specified queue
Gets the visibility timeout for the specified queue (see Visibility Timeout for more information about this setting)

Retrieving a Message from the Queue

To retrieve one or more messages from the queue, you must append "/front" to the queue URL (see the example below).

The message body and message ID of each message is returned. Messages returned by this action stay in the queue until you delete them. However, once a message is returned to a GET on MessageQueue request, it is not returned on subsequent GET on MessageQueue requests for the duration of the optional VisibilityTimeout. If you do not specify a VisibilityTimeout in the request, the overall visibility timeout for the queue is used for the returned messages. A default visibility timeout of 30 seconds is set when you create the queue, and you can also set the visibility timeout for the queue by using PUT on MessageQueue. See Visibility Timeout for more information.

	Tip
	To view a message regardless of its visibility timeout state, use GET on Message.

	Note
Due to the distributed nature of the queue, a weighted random set of machines is sampled when you retrieve the messages. Therefore, 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 call, or even none on a particular call. You can always peek on any specific message in the queue by using GET on Message.

Note

Due to the distributed nature of the queue, a weighted random set of machines is sampled when you retrieve the messages. Therefore, 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 call, or even none on a particular call. You can always peek on any specific message in the queue by using GET on Message.

Getting the Visibility Timeout for the Queue

To get the visibility timeout, don't append "/front" to the queue URL.

Request Parameters

The following table lists the special request parameters the action uses (in addition to the common request headers listed in Common REST Headers).

Name Description Required

Name	Description	Required
`NumberOfMessages`	Maximum number of messages to return. If there are fewer messages in the queue than `NumberOfMessages`, the maximum number of messages returned is the current number of messages in the queue. Not necessarily all the messages in the queue are returned. Type: Integer from 1 to 256 Default: `1`	No
`VisibilityTimeout`	The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a GET on MessageQueue request. See Visibility Timeout for more information. Type: Integer from 0 to 86400 (maximum 24 hours) Default: The visibility timeout for the queue	No

NumberOfMessages

Maximum number of messages to return. If there are fewer messages in the queue than NumberOfMessages, the maximum number of messages returned is the current number of messages in the queue.

Not necessarily all the messages in the queue are returned.

Type: Integer from 1 to 256

Default: 1

VisibilityTimeout

The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a GET on MessageQueue request. See Visibility Timeout for more information.

Type: Integer from 0 to 86400 (maximum 24 hours)

Default: The visibility timeout for the queue

Response Elements

The following table lists the response elements the action returns (in addition to the common response elements listed in The Structure of a Response).

Name	Description
`Message`	An element containing information about the message. See the example below. This element is returned only if you're using the action to receive messages. Ancestor: `ReceiveMessageResponse` Child: `MessageId`, `MessageBody`
`MessageBody`	The message's contents. Type: String Ancestor: `Message`
`MessageId`	The message's system-assigned ID. Type: String Ancestor: `Message`
`VisibilityTimeout`	An element containing the queue's visibility timeout setting. This element is returned only if you're using the action to get the queue's visibility timeout. Type: Integer Ancestor: `GetVisibilityTimeoutResponse`

Special Errors

The following table lists the special errors the action returns (in addition to the common errors listed in Common Errors).

Error	Description	HTTP Status Code
ReadCountOutOfRange	The value for `NumberOfMessages` is not valid (must be from 1 to 256).	400

Examples

The following examples show how to retrieve messages from a queue and how to get the visibility timeout for the queue.

	Important
	When specifying a queue when using the REST API, make sure to omit `http://queue.amazon.aws.com` from the queue URL and provide only what's left (`/A29E9WXPHGOG29/queue1` in the following examples).

Retrieving Messages

The following example retrieves up to two messages from the queue, and sets the visibility timeout for those messages to 35 seconds. Note the presence of "/front" after the queue URL.

GET /A29E9WXPHGOG29/queue1/front?VisibilityTimeout=35&NumberOfMessages=2 HTTP/1.1
Host: queue.amazonaws.com
Authorization: [AWS authentication string]
AWS-Version: 2007-05-01
Content-Type: text/plain
Date: Mon, 21 May 2007 21:12:00 GMT

See ReceiveMessage for sample response information.

Getting the Visibility Timeout

The following example request gets the visibility timeout setting for the queue. Note the absence of the "/front" after the queue URL.

GET /A29E9WXPHGOG29/queue1/ HTTP/1.1
Host: queue.amazonaws.com
Authorization: [AWS authentication string]
AWS-Version: 2007-05-01
Content-Type: text/plain
Date: Wed, 21 May 2007 21:12:00 GMT

The following example shows the response.

<GetVisibilityTimeoutResponse>
    <VisibilityTimeout>
      35
    </VisibilityTimeout>
    <ResponseStatus>
      <StatusCode>Success</StatusCode>
      <RequestId>cb919c0a-9bce-4afe-9b48-9bdf2412bb67</RequestId>
    </ResponseStatus>
</GetVisibilityTimeoutResponse>