Subscribers can consume messages on the Message Queue for Apache RocketMQ broker by calling this operation.

Request structure

  • Request line

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

    The following table describes the request parameters.

    Parameter Required Description
    TopicName Yes The name of the destination topic to which messages are sent.
    ns No The ID of the instance. This parameter is required for new instances that have namespaces.

    Check whether your instance has a namespace on the Instance Details page in the Message Queue for Apache RocketMQ console. Instances are classified into default instances and new instances based on whether they have namespaces.

    • Default instances: These instances do not have namespaces. All resource names in a default instance must be globally unique.
    • New instances: These instances have namespaces. Resource names in a new instance must be unique within the instance.
    For more information, see Updates.
    consumer Yes The group ID, which is ID of the consumer group.
    tag No The tag of the message. If you do not specify a tag, all messages are pulled. If you need to specify multiple tags, separate them with double vertical bars (||). For example, you can set this parameter to TagA||TagB.
    numOfMessages Yes The number of messages that can be consumed at a time. Valid values: 1 to 16.
    waitseconds No The long polling interval. Short polling is applied if this parameter is not set. Valid values: 1 to 30. Unit: seconds.
  • Request body (XML format)

    None

Response structure

  • A message is available for consumption.
    • Status line

      HTTP/1.1 200

    • Response body

      The following table describes the parameters in the response body.

      Parameter Type Description
      MessageId String The ID of the message.
      MessageBodyMD5 String The MD5 hash of the message body.
      MessageBody String The message body.
      ReceiptHandle String The receipt handle that is used to check whether a message is consumed. The receipt handle can be used only once and must be used before the time specified by the NextConsumeTime parameter. Receipt handles 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 For Message Queue for Apache RocketMQ HTTP client SDK, unordered messages are retried every 5 minutes, and ordered messages are retried every 1 minute. A maximum of 288 retries are allowed for both ordered and unordered messages.
      ConsumedTimes String The number of retries after the message has failed to be consumed.
      MessageTag String The tag of the message.
      Properties String The properties of the message.

      The following information describes key-value pairs in the serialized properties of the message:

      • Key-value pairs are in the key1:value1|key2:value2|key3:value3 format.
      • The following table describes related parameters.
        Parameter Type Description
        KEYS String The key of the message.
        __STARTDELIVERTIME Long The absolute scheduled time of a scheduled message. This value is a UNIX timestamp representing the number of milliseconds.
        __TransCheckT Long The relative time for checking the first transactional message. Unit: seconds. Valid values: 10 to 300.
  • No message is available for consumption.
    • Status 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 can be consumed. This response is a normal response.
      Message String The error message returned.
      RequestId String The ID of the request.
      HostId String The host for 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>