• Distributed Message Service

dms
  1. Help Center
  2. Distributed Message Service
  3. API Reference
  4. APIs for Managing Queues and Messages
  5. Creating a Queue

Creating a Queue

Function

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

NOTE:

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 later.

URI

URI format: POST /v1.0/{project_id}/queues

Table 1 describes the parameter of this API.

Table 1 Parameter description

Parameter

Type

Mandatory or Not

Description

project_id

String

Yes

Indicates the ID of a project.

Request

Request parameters

Table 2 describes the parameters.

Table 2 Parameter description

Parameter

Type

Mandatory or Not

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.

This parameter 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 Parameter description

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.

Table 4 Status code

Status Code

Description

201

The queue is created successfully.