• Distributed Message Service

dms
  1. Help Center
  2. Distributed Message Service
  3. API Reference
  4. APIs for Managing Queues and Messages
  5. Consuming Dead Letter Messages

Consuming Dead Letter Messages

Function

This API is used to consume the dead letter messages generated by a specified consumer group. Multiple messages can be consumed at a time. The load of messages consumed each time cannot exceed 512 KB.

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

URI

URI format: GET /v1.0/{project_id}/queues/{queue_id}/groups/{consumer_group_id}/deadletters?max_msgs={max_msgs}&time_wait={time_wait}&ack_wait={ack_wait}

Table 1 describes the parameters of this API.

Table 1 Parameter description

Parameter

Type

Mandatory or Not

Description

Value Range

project_id

String

Yes

Indicates the ID of a project.

N/A

queue_id

String

Yes

Indicates the queue ID.

N/A

consumer_group_id

String

Yes

Indicates the consumer group ID. You can obtain the consumer group ID from the response message returned after you call the API to view all consumer groups of a specified queue. For details, see Viewing All Consumer Groups of a Specified Queue.

N/A

max_msgs

Integer

No

Indicates the number of consumable dead letter messages that can be obtained a time.

NOTE:

The number of dead letter messages actually consumed at a time may be less than the message quantity specified in the consumption request. However, all dead letter messages in the queue will be eventually obtained by the consumer after multiple rounds of consumption.

Value range: 1–10.

Default Value: 10.

time_wait

Integer

No

Indicates the waiting time for reading messages when the number of dead letter messages that can be consumed by a consumer group is 0.

If a dead letter message is available during the wait period, the message consumption result is returned immediately. If no dead letter message is available until the wait period expires, an empty response will be returned after the wait period ends.

Value range: 1 to 60 seconds.

Default value: 3s.

The default wait period is 3 seconds even if the API request does not carry the time_wait parameter or the time_wait parameter in the API request is left unspecified.

ack_wait

Integer

No

Indicates the commit submission timeout interval. Acknowledgement within the time specified by this parameter is valid. Otherwise, the system displays a message indicating that the message acknowledgement times out or the handler is invalid.

Value range: 15 to 300 seconds.

Default value: 30s.

If this parameter is left unspecified or empty, the default value 30s is used.

Example

v1.0/b78a90ae2a134b4b8b2ba30acab4e23a/queues/075ae7da-6ce5-4966-940c-17c19fb5175e/groups/g-5ec247fd-d4a2-4d4f-9876-e4ff3280c461/deadletters?max_msgs=10&ack_wait=30

Request

Request parameters

None.

Example request

None.

Response

Response parameters

Table 2 and Table 3 describe the response parameters.

Table 2 Parameter description

Parameter

Type

Description

message

JSON object

Indicates the message content.

handler

String

Indicates the message handler.

Table 3 message parameter description

Parameter

Type

Description

body

JSON

Indicates the message body.

attributes

JSON object

Indicates the list of attributes.

Example response

[{
  "message" : {
   "body" : {
    "foo" : "123="
   },
   "attributes": {
       "attribute1": "value1",
       "attribute2": "value2"
        }
  },
  "handler" : "eyJjZyI6Im15X2pzb25fZ3JvdXAiLCJjaSI6InJlc3QtY29uc3VtZXItYzNlNThiNjEtYzA0NC00NGJkLTkxM2ItZDgzNjljNmJhYTQxIiwiY291bnQiOjAsIm9mZnNldCI6MCwicCI6MCwidCI6InRlc3QyIn0="
 }, {
  "message" : {
   "body" : {
    "foo" : "123="
   },
   "attributes": {
       "attribute1": "value1",
       "attribute2": "value2"
        }
  },
  "handler" : "eyJjZyI6Im15X2pzb25fZ3JvdXAiLCJjaSI6InJlc3QtY29uc3VtZXItYzNlNThiNjEtYzA0NC00NGJkLTkxM2ItZDgzNjljNmJhYTQxIiwiY291bnQiOjAsIm9mZnNldCI6MSwicCI6MCwidCI6InRlc3QyIn0="
 }
]

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

200

The information is obtained successfully.