• Distributed Message Service

dms
  1. Help Center
  2. Distributed Message Service
  3. API Reference
  4. APIs for Managing Queues and Messages
  5. Acknowledging Consumption of Specified Messages

Acknowledging Consumption of Specified Messages

Function

This API is used to confirm the consumption of specified messages.

While a message is being consumed, it remains in the queue and cannot be consumed again within 30s. If the message fails to be consumed within 30s, it can be consumed again.

If a message is consumed, it cannot be consumed again by the consumer group. However, it is retained in the queue (unless the queue is deleted) and can be consumed by other consumer groups. The retention period is 72 hours by default and the message will be deleted 72 hours later.

After a batch of messages is consumed, consumers must acknowledge the message consumption in the exact order that the messages are consumed. DMS checks whether messages are successfully consumed in the same order. If a message has not been acknowledged as a consumed message or failed to be consumed, DMS stops checking and determines that all the subsequent messages fail to be consumed. Therefore, when a consumer fails to acknowledge the consumption of a message (in a batch of messages), you are advised to stop the consumer from consuming the rest of the messages, and acknowledge the consumption of messages that have been successfully consumed.

If the consumption of a message fails to be acknowledged, this message can be re-consumed and its consumption can also be acknowledged again. If dead letter messages are enabled and a message fails to be consumed for a preset number of times, the message will be sent to the dead letter queue and retained in the dead letter queue for a maximum of 72 hours. You can then consume the message from the dead letter queue.

URI

URI format: POST /v1.0/{project_id}/queues/{queue_id}/groups/{consumer_group_id}/ack

Table 1 describes the parameters of this API.

Table 1 Parameter description

Parameter

Type

Mandatory or Not

Description

project_id

String

Yes

Indicates the ID of a project.

queue_id

String

Yes

Indicates the queue ID.

consumer_group_id

String

Yes

Indicates the consumer group ID.

Request

Request parameters

Table 2 and Table 3 list the parameter description.

Table 2 Parameter description

Parameter

Type

Mandatory or Not

Description

message

Array

Yes

Indicates the message confirmation arrays.

Table 3 message parameter description

Parameter

Type

Mandatory or Not

Description

handler

String

Yes

Indicates the ID returned during the consumption.

status

String

Yes

Indicates the message consumption status.

The value can be success or fail.

Example request

{
  "message": [
    {
      "handler": "eyJjb25zdW1lckdyb3VwIjoibXFzX2NvbnN1bWVyXzMiLCJjb25zdW1lckluc3RhbmNlIjoicmVzdC1jb25zdW1lci1hMWM5YTRlMy1mNTY5LTQyYTgtOTQ1Ni1hYmU0NDVmZjUxYzkiLCJjb3VudCI6MSwib2Zmc2V0IjowLCJvZmZzZXRJbmRleCI6LTEsInBhcnRpdGlvbiI6MiwidG9waWMiOiJxLWI3OGE5MGFlMmExMzRiNGI4YjJiYTMwYWNhYjRlMjNhLTA3NWFlN2RhLTZjZTUtNDk2Ni05NDBjLTE3YzE5ZmI1MTc1ZSJ9",
      "status": "success"
    }
  ]
}

Response

Response parameters

Table 4 describes the response parameters.

Table 4 Parameter description

Parameter

Type

Description

success

Integer

Indicates the number of messages that are successfully acknowledged. The value N indicates that the first N messages are successfully acknowledged.

fail

Integer

Indicates the number of messages that failed to be acknowledged. The value N indicates that the last N messages failed to be acknowledged.

Example response

{
  "success": 1, 
  "fail": 2
}

Status Code

Table 5 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 5 Status code

Status Code

Description

200

The messages are successfully consumed.