Creating a Queue

Function

By default, a maximum of 30 queues can be created for a project.

When a queue is created, it takes one to three seconds to initialize the queue. Therefore, if operations such as message production, message consumption, queue details query, consumer group creation, and queue deletion are performed immediately after a queue is created, the operations may fail. You are advised to perform these operations three seconds after creating the queue.

URI

POST /v1.0/{project_id}/queues

Table 1 describes the parameter of this API.

**Table 1** Parameter
Parameter	Type	Mandatory	Description
project_id	String	Yes	Indicates the ID of a project.

Request

Request parameters

Table 2 describes the parameters.

**Table 2** Request parameters
Parameter	Type	Mandatory	Description
name	String	Yes	Indicates the unique name of a queue. The value is a string of 1 to 64 characters that contain letters, digits, hyphens (-), and underscores (_). The name cannot be modified once specified.
queue_mode	String	No	Indicates the queue type. Options: NORMAL: Standard queue, which supports high concurrency performance but cannot guarantee that messages are retrieved in the exact sequence as how they are received. FIFO: First-in-first-out (FIFO) queue, which guarantees that messages are retrieved in the exact sequence as how they are received. KAFKA_HA: High-reliability Kafka queue. All message replicas are flushed to a disk synchronously, ensuring message reliability. KAFKA_HT: High-throughput Kafka queue. All message replicas are flushed to a disk asynchronously, ensuring high performance. The default value is NORMAL.
description	String	No	Indicates the basic information about a queue. The value is a string of a maximum of 160 characters and cannot contain the angle brackets (<>).
redrive_policy	String	No	This parameter is valid only when queue_mode is set to NORMAL or FIFO. This parameter specifies whether to enable dead letter messages. Dead letter messages are messages that cannot be normally consumed. When a message fails to be consumed after the number of consumption attempts of this message reaches this value, DMS stores this message into the dead letter queue. This message will be retained in the deal letter queue for 72 hours. During this period, consumers can consume the dead letter message. Dead letter messages can be consumed only by the consumer group that generated these dead letter messages. Dead letter messages of a FIFO queue are stored and consumed based on the FIFO sequence. Options: enable disable The default value is disable.
max_consume_count	Integer	No	This parameter is mandatory only when redrive_policy is set to enable. Indicates the maximum number of allowed message consumption failures. When a message fails to be consumed after the number of consumption attempts of this message reaches this value, DMS stores this message into the dead letter queue. Value range: 1–100.
retention_hours	Integer	No	Indicates the hours of storing messages in the Kafka queue. This parameter is valid only when queue_mode is set to KAFKA_HA or KAFKA_HT. Value range: 1–72.

Example request

Creating a FIFO queue:

{
  "name" : "queue-001",
  "description" : "This is a FIFO queue.",
  "queue_mode" : "FIFO",
  "redrive_policy" : "enable",
  "max_consume_count" : 3
}

Creating a Kafka queue:

{
  "name" : "queue-002",
  "description" : "This is a Kafka queue.",
  "queue_mode" : "KAFKA_HA",
  "retention_hours" : 36
}

Response

Response parameters

Table 3 describes the response parameters.

**Table 3** Response parameters
Parameter	Type	Description
id	String	Indicates the queue ID.
name	String	Indicates the name of a queue.
kafka_topic	String	This parameter is returned only for Kafka queues. Indicates the Kafka topic ID when Kafka SDK is used.

Example response

Creating a FIFO queue:

{
    "id": "9bf46390-38a2-462d-b392-4d5b2d519c55", 
    "name": "queue_001"
}

Creating a Kafka queue:

{
  "id" : "3ec7a4a2-541b-430a-9c2b-77fa4b64ed8",
  "name" : "queue_002",
  "kafka_topic" : "k-fdc60cfe407a4b2a96a498efda55c785-3ec7a4a2-541b-430a-9c2b-77fa4b64ed8"
}

Status Code

Table 4 lists the status code indicating that the operation is successful. For details about the status codes indicating that the operation fails, see Status Code.