The GET action on a MessageQueue endpoint does one of two things:
Retrieves one or more messages from the specified queue
or
Gets the visibility timeout for the specified queue (see SetVisibilityTimeout for more information about this setting)
To retrieve one or more messages from the queue, you must append the static message ID front to the queue URL (see the example below). Messages are retrieved from the front of the queue, and the message body and message ID of each message is returned. Messages returned by this action stay in the queue until deleted. However, once a message is returned to a GET request on a MessageQueue endpoint, it will not be returned on subsequent GET on MessageQueue requests until the duration of the optional VisibilityTimeout has passed. If you do not specify VisibilityTimeout in the request, the overall visibility timeout for the queue is used. 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.
Note: | To view a message without locking it, in other words, without affecting the visibility 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 will be returned. If the number of messages in the queue is small (less than 1000), it is likely you will get one or two messages per call. You can always peek on any specific message in the queue by using GET on Message, because Amazon SQS knows which machine the message lives on. |
To get the visibility timeout, you must not append the static message ID front to the queue URL.
GET requests on MessageQueue are validated on the following:
The specified queue must exist. The URL to the queue must have been returned by a POST or GET on QueueService request.
If you're retrieving messages, the optional NumberOfMessages you specify must be an integer from 1 to 256.
If you're retrieving messages, the optional VisibilityTimeout you specify must be an integer from 0 to 86400.
If successful, returns Success and either the message ID and message body of each available message (those not restricted by the visibility timeout setting). Or, the action returns Success and the visibility timeout (if that's how you're using the action). The action returns 400 (fail) and an error if unsuccessful.
| Name | Description | Type | Value |
|---|---|---|---|
NumberOfMessages | Specifies the maximum number of messages to return. If the number of messages in the queue is less than the value specified by NumberOfMessages, the maximum number of messages returned is the number of messages in the queue. Not necessarily all the messages in the queue will be returned. If no value is provided, the default value of 1 is used. | Optional. Use when retrieving messages from the queue. | An integer from 1 to 256. |
VisibilityTimeout | The duration, in seconds, that the returned messages are hidden from subsequent GET on MessageQueue requests after being retrieved. If no value is specified, the visibility timeout for the queue is used for the returned messages. See SetVisibilityTimeout for more information. | Optional. Use when retrieving messages from the queue. | Integer from 0 to 86400 seconds (maximum 24 hours) |
The following examples show how to retrieve messages from a queue and how to get the visibility timeout for the queue.
The following example request retrieves up to two messages from the queue, and sets the visibility timeout for those messages to 35 seconds. Note the presence of the front static message ID in the first line.
GET /QueueURL/front?VisibilityTimeout=35&NumberofMessages=2 HTTP/1.1 Host: queue.amazonaws.com Authorization: [AWS authentication string] AWS-Version: 2006-04-01 Content-Type: text/plain Date: Wed, 05 Apr 2006 21:12:00 GMT
See ReceiveMessage (Query) for sample response information.
The following example request gets the visibility timeout setting for the queue. Note the absence of the front static message ID in the first line.
GET /QueueURL/ HTTP/1.1 Host: queue.amazonaws.com Authorization: [AWS authentication string] AWS-Version: 2006-04-01 Content-Type: text/plain Date: Wed, 05 Apr 2006 21:12:00 GMT
See GetVisibilityTimeout (Query) for sample response information.