All Products
Search
Document Center

CreateQueue

Last Updated: Jul 23, 2019

Basic information

Name Value
API CreateQueue
RAM authorized action mns:CreateQueue
Resource acs:mns:$region:$accountid:/queues/$queueName

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