Queue related operations

Last Updated: Apr 01, 2017

CreateQueue

Description

This interface is used to create a new message queue.

The message queue name should be no more than 256 characters, and constituted by letters, digits, or hyphens (-), while the first character must be a letter.

Request

A request mainly includes the following parts:

  • Request line

PUT /queues/$queueName HTTP/1.1

  • Special Request Header

None. See “Public Request Headers”.

  • Request Body

Request Body, which contains all the optional attributes of the created queue, is in XML format.

Parameter Name Description Parameter Value
DelaySeconds It is measured in seconds. All messages sent to the queue can be consumed until the DelaySeconds expires. An integer between 0 and 604800 (7 days). The default value is 0
MaximumMessageSize Maximum body length of a message sent to the queue, measured in bytes. An integer between 1024 (1K) and 65536 (64K). The default value is 65536 (64K).
MessageRetentionPeriod Maximum lifetime of the message in the queue, measured in seconds. After the time specified by this parameter expires, the message will be deleted no matter whether it has been consumed or not. An integer between 60 (1 minute) and 1296000 (15 days). The default value is 345600 (4 days)
VisibilityTimeout Duration in which a message stays in Inactive status after it is consumed from the queue. Measured in seconds. An integer between 1 and 43200 (12 hours). The default value is 30 (seconds)
PollingWaitSeconds It is the maximum time that a ReceiveMessage request could be waiting for any incoming messages, while there are no message in the queue. Measured in seconds. An integer between 0 and 30 seconds. The default value is 0 (seconds)

Note:

Once PollingWaitSeconds is set for a queue, all (Batch)ReceiveMessage requests on this queue will enter PollingWait status when there is no message in the queue. If no message is received during the entire PollingWaitSeconds period, MessageNotExist will be returned. If any new message enters the queue during the PollingWaitSeconds period, the corresponding ReceiveMessage request will be woken up and the response is returned.

Response

The returned message includes 3 parts: returned status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 201 Created

    Different message queues with same name are not allowed for the same owner. If the queue name in the CreateQueueRequest exists in the created queues of current user, 2 difference ErrorCodes may be returned: 204(No Content) is returned when attributes of the existing queue are same as attributes in the CreateQueueRequest, which means the queue exists; Otherwise, error 409 (Conflict) is returned.

  • Special Response Header

Parameter Name Description
Location The created QueueURL is returned, in the following format:http://$AccountId.mns.<Region>.aliyuncs.com/queues/$queueName
  • Response Body

    None

Special Error

Error Code Error Message Status Code
QueueAlreadyExist The queue you want to create is already exist. 409
InvalidArgument The value of Element should between MIN and MAX seconds/bytes. 400

Request example:

  1. PUT /queues/$queueName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Wed, 08 Mar 2012 12:00:00 GMT
  4. x-mns-version: 2015-06-06
  5. Authorization:MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
  6. <?xml version=”1.0 enconding=”UTF-8”?>
  7. <Queue xmlns=”http://mns.aliyuncs.com/doc/v1/”>
  8. <VisibilityTimeout>60</VisibilityTimeout>
  9. <MaximumMessageSize>65536</MaximumMessageSize>
  10. <MessageRetentionPeriod>1209600</MessageRetentionPeriod>
  11. </Queue>

Return example:

  1. HTTP/1.1 201 Created
  2. x-mns-request-id:512B2A634403E52B1956133E
  3. x-mns-version: 2015-06-06
  4. Location: http://$AccountId.mns.cn-hangzhou.aliyuncs.com/queues/$queueName

SetQueueAttributes

Description

This interface is used to modify attributes of a message queue.

Request

A request mainly includes the following parts:

  • Request line

    PUT /queues/$queueName?metaoverride=true HTTP/1.1

  • URI parameter

    metaoverride=true: the attributes of the message queue will be modified.

  • Special Request Header

    None. See “Public Request Headers”.

  • Request Body

    Request Body, which contains all the optinonal attributes of the created queue,is in XML format.

Parameter Name Description Parameter Value
DelaySeconds It is measured in seconds. All messages sent to the queue can be consumed until the DelaySeconds expires. An integer between 0 and 604800 (7 days). The default value is 0
MaximumMessageSize Maximum body length of a message sent to the queue, measured in bytes. An integer between 1024 (1K) and 65536 (64K). The default value is 65536 (64K).
MessageRetentionPeriod Maximum lifetime of the message in the queue, measured in seconds. After the time specified by this parameter expires, the message will be deleted no matter whether it has been consumed or not. An integer between 60 (1 minute) and 1296000 (15 days). The default value is 345600 (4 days)
VisibilityTimeout Duration in which a message stays in Inactive status after it is consumed from the queue. Measured in seconds. An integer between 1 and 43200 (12 hours). The default value is 30 (seconds)
PollingWaitSeconds It is the maximum time that a ReceiveMessage request could be waiting for any incoming messages, while there are no message in the queue. Measured in seconds. An integer between 0 and 30 seconds. The default value is 0 (seconds)

Response

The returned message includes 3 parts: returned status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 204 No Content

  • Special Response Header

    None. See “Public Return Headers”

  • Response Body

    None.

Special Error

Error Code Error Message Status Code
InvalidArgument The value of Element should between MIN and MAX seconds/bytes. 400
QueueNotExist The queue name you provided is not exist. 404

Request example:

  1. PUT /queues/$queueName?Metaoverride=true HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Wed, 08 Mar 2012 12:00:00 GMT
  4. x-mns-version: 2015-06-06
  5. Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
  6. <?xml version="1.0" encoding="UTF-8" ?>
  7. <Queue xmlns=”http://mns.aliyuncs.com/doc/v1/”>
  8. <VisibilityTimeout >60</VisibilityTimeout>
  9. <MaximumMessageSize>1024</MaximumMessageSize>
  10. <MessageRetentionPeriod>120</MessageRetentionPeriod>
  11. <DelaySeconds>30</DelaySeconds>
  12. </Queue>

Return example:

  1. HTTP/1.1 204 No Content
  2. x-mns-request-id:512B2A634403E52B1956133E
  3. x-mns-version: 2015-06-06

GetQueueAttributes

Description

This interface is used to acquire the attributes of a created queue. Along with the attributes which are configured in the queue creation, the creation time of the queue, the last modification time of queue attributes, and the counts of various types of messages in the queue (approximate values) are returned.

Request

A request mainly includes the following parts.

  • Request line

    GET /queues/$queueName HTTP/1.1

  • Special Request Header

    None. See “Public Request Headers”.

  • Request Body

    None.

Response

The returned message includes 3 parts: returned status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 200OK

  • Special Response Header

    None. See “Public Return Headers”.

  • Response Body

    The return result is in XML format. The format is:<Queue>Attribute Element List</Queue>

The attribute element list includes:

Parameter Name Description
QueueName Queue name
CreateTime Creation time of the queue. It is seconds that have elapsed since 1970-1-1 0:00 till now
LastModifyTime Last modification time of the queue attributes. It is seconds that elapse since 1970-1-1 0:00 till now
DelaySeconds A delay time after which the message sent to the queue can be consumed, measured in seconds
MaximumMessageSize Maximum body length of a message sent to the queue, measured in bytes
MessageRetentionPeriod Maximum lifetime of the message in the queue, measured in seconds. After the time specified by this parameter expires, the message will be deleted no matter whether it has been consumed or not
PollingWaitSeconds It is the maximum time that a ReceiveMessage request could be waiting for any incoming messages, while there are no message in the queue. Measured in seconds.
Activemessages Total number of active messages in the queue, which is an approximate value
InactiveMessages Total number of inactive messages in the queue, which is an approximate value
DelayMessages Total number of delayed messages in the queue, which is an approximate value

Special Error

Error Code Error Message Status Code
QueueNotExist The queue name you provided is not exist. 404

Request example:

  1. GET /queues/$queueName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Wed, 08 Mar 2012 12:00:00 GMT
  4. x-mns-version: 2015-06-06
  5. Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

Return example:

  1. HTTP/1.1 200 OK
  2. Connection:close
  3. Content-Type=text/xml;charset=utf-8
  4. Content-Length:145
  5. x-mns-request-id:512B2A634403E52B1956133E
  6. x-mns-version: 2015-06-06
  7. <?xml version="1.0" encoding="UTF-8"?>
  8. <Queue xmlns=http://mns.aliyuncs.com/doc/v1/”>
  9. <QueueName>$queueName </QueueName ><!—The actual Queue Name is returned ->
  10. <CreateTime>1250700999</CreateTime >
  11. <LastModifyTime>1250700999</LastModifyTime>
  12. <VisibilityTimeout>60</VisibilityTimeout >
  13. <MaximumMessageSize>65536</MaximumMessageSize>
  14. <MessageRetentionPeriod>65536</MessageRetentionPeriod>
  15. <DelaySeconds>30</DelaySecond>
  16. <PollingWaitSeconds>0</PollingWaitSeconds>
  17. <InactiveMessages>0</InactiveMessages>
  18. <ActiveMessages>20</ActiveMessages>
  19. < DelayMessages >0</ DelayMessages>
  20. </Queue>

DeleteQueue

Description

This interface is used to delete a created message queue.

Note:

Be cautious when using this interface. Once the queue is deleted, all messages in the queue are deleted and cannot be recovered.

Request

A request mainly includes the following parts:

  • Request line

    DELETE /queues/$queueName HTTP/1.1

  • Special Request Header

    None. See “Public Request Headers”.

  • Request Body

    None.

Response

The returned message includes 3 parts: returned status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 204 No Content

  • Special Response Header

    None. See “Public Return Headers”.

  • Response Body

    None.

Special Error

This operation has no special errors and involves mainly permission verification errors and parameter setting errors. For details, refer to MNS error response codes.

Request example:

  1. DELETE /queues/$queueName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Wed, 08 Mar 2012 12:00:00 GMT
  4. x-mns-version: 2015-06-06
  5. Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

Return example:

  1. HTTP/1.1 204 NoContent
  2. x-mns-request-id: 512B2A634403E52B1956133E
  3. x-mns-version: 2015-06-06

ListQueue

Description

This interface is used to list the message queues under the AccountId. Data can be acquired by page. Only the QueueURL attribute is returned.

If necessary, use the GetQueueAttributes interface (see “GetQueueAttributes Interface”) to acquire more message queue attributes.

To acquire the list of specified message queues, specify the ‘x-mns-prefix’ parameter when calling this interface. All message queues with the specified prefix will be returned.

Tip: If the total number of message queues returned for this request exceeds the x-mns-ret-number value, the NextMarker indicating the start position of the next page could be found in the returned XML result, and could be assigned to the x-mns-marker parameter in the next request to fetch the next page.

Request

A request mainly includes the following parts:

  • Request line

    GET /queues HTTP/1.1

  • Special Request Header

Parameter Name Description Required?
x-mns-marker Start position of the next page, which is generally acquired from NextMarker returned in the previous page. Optional
x-mns-ret-number Maximum number of results returned for a single request, which can be an integer between 1 and 1000. The default value is 1000. Optional
x-mns-prefix Search for the queueNames starting with this prefix. Optional

For other request headers, see “Public Request Headers”.

  • Request Body

    None.

Response

The returned message includes 3 parts: returned status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 200 OK

  • Special Response Header

    None. See “Public Return Headers”.

  • Response Body

    The result in XML format is returned. The top-layer element Queues contains multiple Queue elements, and the Queue elements contain QueueURL elements. QueueURL indicates the URL address of the created queue.If the number of return results exceeds the x-mns-ret-number value, the element containing NextMarker indicates the start position of the next page.

Special Error

This operation has no special errors and involves mainly permission verification errors and parameter setting errors. For details, refer to MNS error response codes.

Request example:

  1. GET /queues HTTP/1.1
  2. x-mns-marker: xxxx
  3. x-mns-ret-number:2
  4. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  5. Date: Wed, 08 Mar 2012 12:00:00 GMT
  6. x-mns-version: 2015-06-06
  7. Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

Return example:

  1. HTTP/1.1 200OK
  2. x-mns-request-id:512B2A634403E52B1956133E
  3. x-mns-version: 2015-06-06
  4. <?xml version="1.0" encoding=”UTF-8 ?>
  5. <Queuesxmlns=”http://mns.aliyuncs.com/doc/v1/”>
  6. <Queue>
  7. < QueueURL>
  8. http:// $AccountId.mns.cn-hangzhou.aliyuncs.com/queues/queueName
  9. </ QueueURL>
  10. </Queue>
  11. <Queue>
  12. < QueueURL>
  13. http:// $AccountId.mns.cn-hangzhou.aliyuncs.com/queues/queueName1
  14. </ QueueURL>
  15. </Queue>
  16. <NextMarker> Base64 Encoded Result </NextMarker>
  17. </Queues>
Thank you! We've received your feedback.