Request structure, response structure, and examples of the operation for consuming messages in ApsaraMQ for RocketMQ - ApsaraMQ for RocketMQ

You can call this operation to consume messages from an ApsaraMQ for RocketMQ broker.

Request structure

Request line

GET /topics/TopicName/messages?ns=INSTANCE_ID&consumer=GID&tag=taga&numOfMessages=3&waitseconds=3 HTTP/1.1

Important

The total length of the request line cannot exceed 1,024 characters.

The following table describes the parameters in the request line.

Parameter	Required	Description
TopicName	Yes	The name of the topic from which you want to consume messages.
ns	No	The instance ID. This parameter is required for new instances that have namespaces. Check whether your instance has a namespace on the Instance Details page in the ApsaraMQ for RocketMQ console. Instances are classified into default instances and new instances based on whether they have namespaces. Default instance: A default instance does not have a namespace. The names of all resources in a default instance must be globally unique. New instance: A new instance has a namespace. The names of all resources in a new instance must be unique within the instance. For more information, see Use instances.
consumer	Yes	The consumer group ID.
tag	No	The message tag. If you do not specify a tag, all messages are pulled. If you want to specify multiple tags, separate them with double vertical bars (\|\|). Example: TagA\|\|TagB.
numOfMessages	Yes	The maximum number of messages that can be consumed at a time. Valid values: 1 to 16.
waitseconds	No	The long polling period. If you set this parameter to 0 or leave this parameter empty, short polling is used. Valid values: 0 to 30. Unit: seconds. When a consumer obtains messages from the broker for consumption, the consumer can use the long polling mode or the short polling mode. Long polling: The consumer sends a request to the broker to obtain messages in a specific topic. If no message exists in the topic, the broker suspends the request and returns a response until messages are produced in the topic or the specified period for the long polling elapses. Short polling: If no message exists in the topic, the broker immediately returns a response. After the client receives the response, the client repeatedly initiates subscription requests. Note If you use the short polling mode and no message is produced in the topic, a large number of invalid requests may be generated. You are charged API call fees for these requests. To reduce the number of invalid subscription requests and save costs, we recommend that you use the long polling mode and increase the waiting time for long polling. For information about how to calculate API call fees, see API call fees.

Request body (XML format)
None.

Response structure

A message is available for consumption.

Response line
HTTP/1.1 200

Response body

The following table describes the parameters in the response body.

Parameter	Type	Description
MessageId	String	The message ID.
MessageBodyMD5	String	The MD5 hash value of the message body.
MessageBody	String	The message body.
ReceiptHandle	String	The receipt handle that is used to acknowledge that a message is consumed. The receipt handle can be used only once and must be used before the period of time specified by the NextConsumeTime parameter elapses. The receipt handles that are obtained each time the same message is retried and consumed are different.
PublishTime	String	The timestamp that indicates the time when the message was sent. Unit: milliseconds.
FirstConsumeTime	String	The timestamp that indicates the time when the message was consumed for the first time. Unit: milliseconds.
NextConsumeTime	String	The timestamp that indicates the absolute time when the message was retried. Unit: milliseconds. Note If you connect to ApsaraMQ for RocketMQ over HTTP, a non-ordered message is retried every 5 minutes and an ordered message is retried every minute. Each message can be retried up to 288 times.
ConsumedTimes	String	The number of retries after the message failed to be consumed.
MessageTag	String	The message tag.
Properties	String	The message attributes.

The following items describe key-value pairs in the serialized attributes of the message:

The key-value pairs are displayed in the key1:value1|key2:value2|key3:value3 format.

The following table describes the parameters in a key-value pair.

Parameter	Type	Description
KEYS	String	The message key.
__STARTDELIVERTIME	Long	The absolute scheduled time of a scheduled message. This value is a UNIX timestamp in milliseconds.
__TransCheckT	Long	The relative time that indicates the time when the first status check for a transactional message is performed. Unit: seconds. Valid values: 10 to 300.

No message is available for consumption.

Response line
HTTP/1.1 404

Response body

The following table describes the parameters in the response body.

Parameter	Type	Description
Code	String	The error code. `MessageNotExist` indicates that no message is available for consumption. If this error code is returned, the response is a normal response.
Message	String	The error message.
RequestId	String	The request ID.
HostId	String	The host that sent the request.

Sample responses

A message is available for consumption.

<?xml version="1.0" ?>
<Messages xmlns="http://mq.aliyuncs.com/doc/v1">
<Message>
  <MessageId>1E057D5E6EAD42A579937046FE17****</MessageId>
  <MessageBodyMD5>0CC175B9C0F1B6A831C399E26977****</MessageBodyMD5>
  <MessageBody>a</MessageBody>
  <ReceiptHandle>1E057D5E6EAD42A579937046FE17****-MTI5N****</ReceiptHandle>
  <PublishTime>1571742900759</PublishTime>
  <FirstConsumeTime>1571742902463</FirstConsumeTime>
  <NextConsumeTime>1571742922463</NextConsumeTime>
  <ConsumedTimes>1</ConsumedTimes>
  <MessageTag>Tag</MessageTag>
  <Properties>KEYS:MessageKey|__BORNHOST:30.5.**.**|</Properties>
</Message>
<Message>
  <MessageId>1E057D5E6EAD42A579937046FE17****</MessageId>
  <MessageBodyMD5>0CC175B9C0F1B6A831C399E26977****</MessageBodyMD5>
  <MessageBody>a</MessageBody>
  <ReceiptHandle>1E057D5E6EAD42A579937046FE17****-MTI5N****</ReceiptHandle>
  <PublishTime>1571742900759</PublishTime>
  <FirstConsumeTime>1571742902463</FirstConsumeTime>
  <NextConsumeTime>1571742922463</NextConsumeTime>
  <ConsumedTimes>1</ConsumedTimes>
  <MessageTag>Tag</MessageTag>
  <Properties>KEYS:MessageKey|__BORNHOST:30.5.**.**|</Properties>
</Message>
</Messages>

No message is available for consumption.

<?xml version="1.0" ?>
<Error xmlns="http://mq.aliyuncs.com/doc/v1">
  <Code>MessageNotExist</Code>
  <Message>Message not exist.</Message>
  <RequestId>5DAEE3FF463541AD6E0322EB</RequestId>
  <HostId>http://123.mqrest.cn-hangzhou.aliyuncs.com</HostId>
</Error>