BatchReceiveMessage - Simple Message Queue (formerly MNS)

Receives multiple messages from a queue.

Authorization

By default, only Alibaba Cloud accounts can call this operation. RAM users can call this operation only after these RAM users are granted related permissions. The following table describes the authorization information of this operation. For more information, see Permission policies and examples.

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

Description

You can call this operation to receive a maximum of 16 messages from a queue. After the messages are received, the messages enter the Inactive state. The messages remain Inactive within the period that is specified by the VisibilityTimeout parameter. For more information, see CreateQueue.

During the period that is specified by the VisibilityTimeout parameter, you must call the DeleteMessage operation to delete the messages after you consume the messages. Otherwise, the messages change to the Active state and can be consumed again.

Request

A request consists of the following parts:

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

Operation-specific URI parameters

Parameter	Type	Required	Example	Description
numOfMessages	Integer	Yes	10	The maximum number of messages that can be received.
waitseconds	Integer	No	0	The maximum period for which the request waits if no message is available in the queue. Unit: seconds.

Note

If you specify the waitseconds parameter when you call the BatchReceiveMessage operation, the request holds for the specified period. If no message is available during the specified period, the long-polling request times out. The messages that are written to the queue during this period will be pushed to the users. If you do not specify the waitseconds parameter when you call the BatchReceiveMessage operation, the PollingWaitSeconds parameter that is specified for the queue is used by default. For more information, see CreateQueue.
We recommend that you reduce the number of concurrent long polling requests and specify an appropriate waiting period. For more information, see Short polling and long polling. Simple Message Queue (SMQ, formerly MNS) determines the maximum number of concurrent long polling requests based on the number of requests, the waiting period of requests, and the number of IP addresses. If the limit is exceeded, SMQ does not hold the request and returns the 404MessageNotExist error. In this case, you are charged based on the number of requests. To extend the limit and prevent unnecessary costs, submit a ticket.

Operation-specific request headers
None.
Request Body
None.

Response

A response consists of the following parts:

HTTP Status Code
HTTP/1.1 200 OK
Operation-specific response headers
None.

Response Body

The response body is in the XML format. The bodies and parameters of multiple messages are returned.

Parameter	Type	Example	Description
MessageId	String	5F290C926D472878-2-14D9529A8FA-20000****	The ID of the message. The message ID is unique in the queue.
ReceiptHandle	String	1-ODU4OTkzNDU5My0xNDMyNzI3ODI3LTItOA==	The receipt handle that was generated after the message was consumed. You can use the receipt handle of the message to modify or delete the message that is in the Inactive state. The receipt handle is valid before the time that is specified by the NextVisibleTime parameter.
MessageBody	String	This is test message 1.	The body of the message.
MessageBodyMD5	String	C5DD56A39F5F7BB8B3337C6D11B6****	The MD5 hash of the message body.
EnqueueTime	Long	1250700979248	The time when the message was sent to the queue. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
NextVisibleTime	Long	1250700799348	The time when the message can be consumed. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
FirstDequeueTime	Long	1250700779318	The first time when the message was consumed. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
DequeueCount	Integer	1	The total number of times for which the message was consumed.

Examples

Sample requests

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 success responses

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. You must create a queue.
MessageNotExist	Message not exist.	404	No visible message exists in the queue.