Creating a Queue
Last updated: 2019-07-05 12:19:46
1. API Description
This API (CreateQueue) is used to create a new queue under the user's account.
Domain for public network API request: cmq-queue-region.api.qcloud.com
Domain for private network API request: cmq-queue-region.api.tencentyun.com
Whenever (including during alpha test) any public network downstream traffic is generated from the use of a public network domain, a fee will be charged. Hence it is strongly recommended to use private network domains, in which traffic consumption is NOT charged.
- region should be replaced with a specific region: gz (Guangzhou), sh (Shanghai), or bj (Beijing). The region value in the common parameters should be consistent with the region value of the domain. If there is an inconsistency, the request will be sent to the region specified by the domain.
- Public network domain requests both support HTTP and HTTPS. Private network requests only support HTTP.
- Some of the input parameters are optional. If not specified, the default value will be taken.
- All the output parameters will be returned to the user when the request is successful; otherwise, at least code, message, and requestId will be returned.
2. Input Parameters
The following request parameter list only provides API request parameters. For other parameters, refer to Common Request Parameters.
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| queueName | Yes | String | Queue name. This is unique under the same account in one region. The queue name is a string of no more than 64 characters, which can contain letters, numbers, and hyphens (-) and must begin with a letter. |
| maxMsgHeapNum | No | Int | Maximum number of messages in the queue. The value range is 1,000,000 - 10,000,000 during beta test, and will be increased to 1,000,000 - 1,000,000,000 when officially launched. The default value is 10,000,000 during beta test, and 100,000,000 when officially launched. |
| pollingWaitSeconds | No | Int | Waiting time for messages to be received when using long-polling. The value ranges from 0 to 30 seconds. Default is 0. |
| visibilityTimeout | No | Int | Message visibility timeout. Value range is 1-43200 seconds (within 12 hours). Default is 30. |
| maxMsgSize | No | Int | Maximum message length. Value range is 1024-65536 Bytes (1-64 K). Default is 65536. |
| msgRetentionSeconds | No | Int | Message retention period. Value range is 60-1296000 seconds (1 min-15 days). Default value is 345600 (4 days). |
| rewindSeconds | No | Int | Indicate whether the feature of message rewind is enabled for the queue. Value range is 0-msgRetentionSeconds, where 0 means not enabling the feature, and msgRetentionSeconds, which refers to the period for which the message is retained in the queue, is the maximum rewind time. |
| ## 3. Output Parameters |
| Parameter Name | Type | Description |
|---|---|---|
| code | Int | 0: Succeeded, others: Error. See the table below for specific errors. |
| message | String | Error message. |
| requestId | String | Request ID generated by server. When there is an internal error on the server, users can submit this ID to the backend to locate the problem. |
| queueId | String | Unique ID of the queue. |
| Error Code | Module Error Code | Error Message | Description |
|---|---|---|---|
| 4000 | 10020 | Queue name format error | The format of the queue name is incorrect. See the description of the queueName field for the API CreateQueue for the rules. |
| 4450 | 10220 | Number of queues has reached the limit | The number of queues has reached the upper limit. The number of queues for an account is limited (1,000). When the maximum number is reached, no queue can be created then. |
| 6040 | 10660 | It will take some time to release resources of previous queue before you create a new one with the same name, please try later | Failed to create a queue with the same name. It will take some time to release resources of the previous queue with the same name. Currently, to ensure data consistency of CMQ, it is not allowed to create a new queue with the same name within ten seconds after a queue is deleted. |
Note: The error codes listed in the above table are specific to this API. If the error code you are looking for is not in the table, you may find it in the Common Error Codes.
4. Example
Input:
https://domain/v2/index.php?Action=CreateQueue &queueName=test-queue-123 &<Common Request Parameters>
Output:
{
"code" : 0,
"message" : "",
"requestId":"14534664555",
"queueId":"queue-ajksdfasdowe"
}