Pull messages from an ApsaraMQ for RocketMQ topic over HTTP. The broker returns up to 16 messages per request in XML format. Each message includes the message body, an MD5 digest, a receipt handle for acknowledgment, timestamps, and message attributes.
Request
GET /topics/<TopicName>/messages?ns=<instance-id>&consumer=<group-id>&tag=<tag>&numOfMessages=<count>&waitseconds=<seconds> HTTP/1.1The total request line length must not exceed 1,024 characters.
Parameters
| Parameter | Required | Description |
|---|---|---|
| TopicName | Yes | Topic name to consume messages from. |
| ns | Conditional | Instance ID. Required for instances that have namespaces. Check the Instance Details page in the ApsaraMQ for RocketMQ console to determine whether your instance has a namespace. For more information, see Use instances. |
| consumer | Yes | Consumer group ID. |
| tag | No | Message tag for filtering. Omit to pull all messages. Separate multiple tags with double vertical bars (||). Example: TagA||TagB. |
| numOfMessages | Yes | Maximum number of messages to return. Valid values: 1 to 16. |
| waitseconds | No | Long polling timeout in seconds. Valid values: 0 to 30. Set to 0 or omit for short polling. See Long polling vs. short polling. |
Request body
None.
Instance types
ApsaraMQ for RocketMQ has two types of instances:
Default instance -- No namespace. Resource names must be globally unique.
New instance -- Has a namespace. Resource names only need to be unique within the instance.
Long polling vs. short polling
The waitseconds parameter controls how the broker handles requests when no messages are available.
| Mode | Behavior |
|---|---|
Long polling (waitseconds > 0) | The broker holds the request open until a message arrives or the timeout elapses. |
Short polling (waitseconds = 0 or omitted) | The broker responds immediately, even if no messages are available. The client must poll repeatedly. |
Short polling generates a high volume of empty responses when no messages are being produced, and each response incurs API call fees. Use long polling with a higher waitseconds value to reduce costs.
Response
Success (HTTP 200)
The broker returns one or more <Message> elements in XML. Each element contains the following fields:
| Parameter | Type | Description |
|---|---|---|
| MessageId | String | Unique message ID. |
| MessageBodyMD5 | String | MD5 hash of the message body. |
| MessageBody | String | Message body content. |
| ReceiptHandle | String | Handle for acknowledging the message. Pass this handle to the acknowledge (delete) operation to confirm consumption. Single-use only -- expires at NextConsumeTime. A new handle is issued on each retry. |
| PublishTime | String | Time when the message was published. UNIX timestamp in milliseconds. |
| FirstConsumeTime | String | Time when the message was first consumed. UNIX timestamp in milliseconds. |
| NextConsumeTime | String | Time when the message becomes available for retry. UNIX timestamp in milliseconds. |
| ConsumedTimes | String | Number of consumption retries. |
| MessageTag | String | Message tag. |
| Properties | String | Serialized message attributes in key-value format. See Message properties format. |
Over HTTP, non-ordered messages are retried every 5 minutes, and ordered messages are retried every 1 minute. Each message can be retried up to 288 times.
Message properties format
The Properties field uses the format key1:value1|key2:value2|key3:value3.
| Key | Type | Description |
|---|---|---|
| KEYS | String | Message key. |
| __STARTDELIVERTIME | Long | Scheduled delivery time for a scheduled message. UNIX timestamp in milliseconds. |
| __TransCheckT | Long | Delay before the first transaction status check for a transactional message, in seconds. Valid values: 10 to 300. |
No messages available (HTTP 404)
If no messages are available, the broker returns HTTP 404 with the error code MessageNotExist. This is expected behavior, not an error.
| Parameter | Type | Description |
|---|---|---|
| Code | String | Error code. MessageNotExist indicates no messages are available. |
| Message | String | Error message. |
| RequestId | String | Request ID. |
| HostId | String | Host that sent the request. |
Sample responses
Messages available
<?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 messages available
<?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>