Use BatchReceiveMessage to receive multiple messages from a queue - Simple Message Queue (formerly MNS)

Receives up to 16 messages from a queue in a single call.

After the messages are received, they enter the Inactive state for the duration of the queue's VisibilityTimeout. Delete the messages within this window after you process them. Otherwise, the messages return to the Active state and become available for redelivery.

Authorization

By default, only Alibaba Cloud accounts can call this operation. Grant RAM users the required permissions before they call this operation. For details, see Permission policies and examples.

Property	Value
API	BatchReceiveMessage
Action	mns:BatchReceiveMessage
Resource	acs:mns:$region:$accountid:/queues/$queueName/messages

How it works

Send a GET request with the numOfMessages parameter to receive messages from a queue.
The returned messages immediately enter the Inactive state and are hidden from other consumers.
Process each message, then call DeleteMessage with the message's ReceiptHandle before NextVisibleTime.
If you do not delete a message within the VisibilityTimeout period, it returns to the Active state and can be consumed again.

The VisibilityTimeout is configured at the queue level through CreateQueue.

Request

Request line

GET /queues/$queueName/messages?numOfMessages=16&waitseconds=10 HTTP/1.1

URI parameters

Parameter	Type	Required	Example	Description
numOfMessages	Integer	Yes	10	Maximum number of messages to receive.
waitseconds	Integer	No	0	Long polling wait time, in seconds. When no message is available, the request holds until a message arrives or the wait time elapses. Defaults to the queue's `PollingWaitSeconds` if omitted. See CreateQueue.

Long polling behavior

When waitseconds is set (or the queue's PollingWaitSeconds default applies), the request holds open until a message arrives or the wait time elapses. Messages written to the queue during this period are delivered immediately. For background on the two polling modes, see Short polling and long polling.

Note

SMQ limits concurrent long polling requests based on request count, wait duration, and client IP addresses. When this limit is exceeded, SMQ returns 404 MessageNotExist immediately instead of holding the request. To avoid unnecessary charges, reduce concurrent long polling requests and use an appropriate wait duration. To raise the limit, submit a ticket.

Request headers

No operation-specific headers.

Request body

None.

Response

HTTP status code

HTTP/1.1 200 OK

Response headers

No operation-specific headers.

Response body

The response body is XML. Each <Message> element within <Messages> contains these fields:

Parameter	Type	Example	Description
MessageId	String	5F290C926D472878-2-14D9529A8FA-20000\\\\	Unique message identifier within the queue.
ReceiptHandle	String	1-ODU4OTkzNDU5My0xNDMyNzI3ODI3LTItOA==	Handle for deleting or modifying the message while Inactive. Valid until `NextVisibleTime`.
MessageBody	String	This is test message 1.	Message content.
MessageBodyMD5	String	C5DD56A39F5F7BB8B3337C6D11B6\\\\	MD5 hash of the message body.
EnqueueTime	Long	1250700979248	Time the message was sent to the queue. UNIX timestamp in milliseconds.
NextVisibleTime	Long	1250700799348	Time the message becomes visible again. UNIX timestamp in milliseconds.
FirstDequeueTime	Long	1250700779318	Time the message was first consumed. UNIX timestamp in milliseconds.
DequeueCount	Integer	1	Total number of times the message has been consumed.

Examples

Sample request

GET /queues/$queueName/messages?numOfMessages=16 HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 28 May 2012 22:32:00 GMT
x-mns-version: 2015-06-06
Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXA****

Sample response

HTTP/1.1 200 OK
Content-Type: text/xml;charset=utf-8
Content-Length: 500
x-mns-request-id: 512B2A634403E52B1956****
x-mns-version: 2015-06-06

<?xml version="1.0" encoding="UTF-8"?>
<Messages xmlns="http://mns.aliyuncs.com/doc/v1/">
  <Message>
    <MessageId>5F290C926D472878-2-14D9529A8FA-20000****</MessageId>
    <ReceiptHandle>1-ODU4OTkzNDU5My0xNDMyNzI3ODI3LTItOA==</ReceiptHandle>
    <MessageBodyMD5>C5DD56A39F5F7BB8B3337C6D11B6****</MessageBodyMD5>
    <MessageBody>This is test message 1.</MessageBody>
    <EnqueueTime>1250700979248</EnqueueTime>
    <NextVisibleTime>1250700799348</NextVisibleTime>
    <FirstDequeueTime>1250700779318</FirstDequeueTime>
    <DequeueCount>1</DequeueCount>
    <Priority>8</Priority>
  </Message>
  <Message>
    <ReceiptHandle>1-ODU4OTkzNDU5My0xNDMyNzI3MjQwLTEtOA==</ReceiptHandle>
    <MessageBodyMD5>C5DD56A39F5F7BB8B3337C6D11B6****</MessageBodyMD5>
    <MessageBody>This is test message 2.</MessageBody>
    <EnqueueTime>1250700979252</EnqueueTime>
    <NextVisibleTime>1250700799350</NextVisibleTime>
    <FirstDequeueTime>1250700779330</FirstDequeueTime>
    <DequeueCount>1</DequeueCount>
    <Priority>8</Priority>
  </Message>
</Messages>

Error codes

Error code	Error message	HTTP status code	Description
QueueNotExist	The queue name you provided is not exist.	404	The specified queue does not exist. Create the queue first.
MessageNotExist	Message not exist.	404	No visible messages in the queue. This also occurs when the concurrent long polling limit is exceeded.