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.

Once a consumer group specifies a message label, the consumer group must use the label for all subsequent retrievals. If a consumer group changes a label during the next retrieval, the next retrieval will fail.

URI

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}&tag={tag1}&tag={tag2}&tag_type={TYPE}

Table 1 describes the parameters of this API.

**Table 1** Parameters
Parameter	Type	Mandatory	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.
tag	String	No	Indicates the message label. You can use message labels to filter the messages you want to retrieve from the chosen queue.	The number of labels cannot exceed 3. A label contains a maximum of 64 characters.
tag_type	String	No	Indicates the message filter mode when multiple message labels are configured.	Options: and: Only messages that match all labels are consumed. or: Messages that match any one label are consumed. Default value: or.

Example

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

Request

Request parameters

None.

Example request

None.

Response

Response parameters

Table 2 and Table 3 describe the response parameters.

**Table 2** Response parameters
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.
tags	JSON array	Indicates the message label.

Example response

[{
  "message" : {
   "body" : {
    "foo" : "123="
   },
   "attributes": {
       "attribute1": "value1",
       "attribute2": "value2"
        }
  },
  "tags":["tag1","tag2"],  
  "handler" : "eyJjZyI6Im15X2pzb25fZ3JvdXAiLCJjaSI6InJlc3QtY29uc3VtZXItYzNlNThiNjEtYzA0NC00NGJkLTkxM2ItZDgzNjljNmJhYTQxIiwiY291bnQiOjAsIm9mZnNldCI6MCwicCI6MCwidCI6InRlc3QyIn0="
 }, {
  "message" : {
   "body" : {
    "foo" : "123="
   },
   "attributes": {
       "attribute1": "value1",
       "attribute2": "value2"
        }
  },
  "tags":["tag1","tag2"],  
  "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.