Receives a message 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 ReceiveMessage
Action mns:ReceiveMessage
Resource acs:mns:$region:$accountid:/queues/$queueName/messages

Description

You can call this operation to receive a message from a queue. After a message is received, the message changes to the Inactive state. The message remains in the Inactive state within the period that is specified by the VisibilityTimeout parameter of the queue. For more information about the VisibilityTimeout parameter, see CreateQueue.

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

Request

A request consists of the following parts:

  • Request line

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

  • Operation-specific URI parameters
    Parameter Type Required Example Description
    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 for the ReceiveMessage operation and no message is available in the queue, the request waits for the specified period. If you do not specify the waitseconds parameter, the system uses the PollingWaitSeconds parameter that is specified for the queue. For more information, see CreateQueue.
    • We recommend that you reduce the number of concurrent long polling requests. 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, MNS 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 avoid 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 body and parameters of the message 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 a test message 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 next 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.
    Priority Integer 8 The priority of the message.

Examples

Sample requests

GET  /queues/$queueName/messages 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"?>
<Message xmlns="http://mns.aliyuncs.com/doc/v1/">
    <MessageId>5F290C926D472878-2-14D9529A8FA-20000****</MessageId>
    <ReceiptHandle>1-ODU4OTkzNDU5My0xNDMyNzI3ODI3LTItOA==</ReceiptHandle>
    <MessageBodyMD5>C5DD56A39F5F7BB8B3337C6D11B6****</MessageBodyMD5>
    <MessageBody>This is a test message</MessageBody>
    <EnqueueTime>1250700979248</EnqueueTime>
    <NextVisibleTime>1250700799348</NextVisibleTime>
    <FirstDequeueTime>1250700779318</FirstDequeueTime >
    <DequeueCount>1</DequeueCount >
    <Priority>8</Priority>
</Message>

Error codes

Error code Error message HTTP status code Description
QueueNotExist The queue name you provided is not exist. 404 The error message returned because the specified queue does not exist. Create a queue.
MessageNotExist Message not exist. 404 The error message returned because no visible message exists in the queue.