• 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 Dead Letter Messages

Acknowledging Consumption of Specified Dead Letter Messages

Function

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

When a dead letter message is being consumed, it remains in the queue. It cannot be consumed again by the same consumer group within 30s since the start of the consumption. If consumption is not acknowledged within this period, DMS determines that this dead letter message fails to be consumed, and this dead letter message can be consumed again.

Once consumption is acknowledged, this dead letter message can no longer be consumed by the same consumer group. Dead letter messages remain in the queue for 72 hours (unless the consumer group is deleted) and will be deleted after this period.

After a batch of messages is consumed, consumers must submit their consumption acknowledgement by strictly following the message consumption sequence. DMS sequentially checks whether messages are successfully consumed. If DMS finds that a message is not acknowledged as a consumed message or fails to be consumed, DMS stops checking but directly 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.

Only NORMAL and FIFO queues can consume dead letter messages and therefore can have the Dead Letter Message function enabled.

URI

URI format: POST /v1.0/{project_id}/queues/{queue_id}/groups/{consumer_group_id}/deadletters/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 dead letter messages that are successfully confirmed. The value N indicates that the first N dead letter messages are successfully confirmed.

fail

Integer

Indicates the number of dead letter messages that failed to be confirmed. The value N indicates that the first N dead letter messages failed to be confirmed.

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 consumption of the dead letter message is successfully acknowledged.