• Distributed Message Service

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

Consuming Messages

Function

This API is used to consume messages in a specified queue. Multiple messages can be consumed at a time. The load of messages consumed each time cannot exceed 512 KB.

When there are only a few messages in a queue, the number of messages actually consumed at a time may be less than the message quantity specified in the consumption request. However, all messages in the queue will be eventually obtained by the message consumer after multiple rounds of consumption. If the queue is empty, no message will be returned to the consumer.

URI

URI format: GET /v1.0/{project_id}/queues/{queue_id}/groups/{consumer_group_id}/messages?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. Obtain the consumer group ID from the response message in Viewing All Consumer Groups of a Specified Queue.

N/A

max_msgs

Integer

No

Indicates the number of consumable messages that can be obtained per time.

Value range: 1–10.

Default Value: 10.

time_wait

Integer

No

Indicates the amount of time that the API call can wait for a message to arrive in the empty queue before returning an empty response.

If a message is available during the wait period, the call will return the message consumption result immediately.

If no message is available until the wait period expires, the call will return an empty response after the wait period expires.

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 timeout duration that the API call can wait for message consumption acknowledgement. The client needs to submit the message consumption acknowledgement within the specified time. If the message consumption is not acknowledged within this period of time, the system displays a message, indicating that message consumption acknowledgement has timed out or the handler is invalid. In this case, the system determines that the message fails to be consumed by default.

Value range: 15 to 300 seconds.

Default value: 30s.

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

Example

URI format: GET v1.0/b78a90ae2a134b4b8b2ba30acab4e23a/queues/075ae7da-6ce5-4966-940c-17c19fb5175e/groups/g-5ec247fd-d4a2-4d4f-9876-e4ff3280c461/messages?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.