A consumer can call this operation to consume messages from a Message Queue for Apache RocketMQ (RocketMQ) broker.

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 lists the parameters in the request line.

    Parameter Required Description
    TopicName Yes The name of the destination topic to which a message is sent.
    ns No The instance ID. It is required for a new instance with a namespace. You can check whether the instance has a namespace on the Instances page of the console. Instances are classified into default instances and new instances depending on whether they have namespaces.
    • Default instance: has no namespace. All resource names in this default instance must be globally unique.
    • New instance: has a namespace. The resource names must be unique within this instance.
    For more information, see Updates.
    consumer Yes The group ID of a consumer.
    tag No The message tag.
    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 adopted if this parameter is not set. Valid values: 1 to 30. Unit: seconds.
  • Request content (XML format)

    None

Response structure

  • A message is available for consumption.
    • Status line

      HTTP/1.1 200

    • Response content

      The following table lists the parameters in the response content.

      Parameter Type Description
      MessageId String The message ID.
      MessageBodyMD5 String The MD5 value of the message content.
      MessageBody String The message content.
      ReceiptHandle String The message handle that is used to check whether a message is successfully consumed. The message handle can be used only once. The message handles obtained in consumption retries of the same message are different. The message handle must be used before NextConsumeTime.
      PublishTime String The time when the message is sent. Unit: milliseconds.
      FirstConsumeTime String The time when the message is consumed for the first time. Unit: milliseconds.
      NextConsumeTime String The absolute time when the message is consumed for the second time (a retry). Unit: milliseconds.
      ConsumedTimes String The number of message consumption times.
      MessageTag String The message tag.
      Properties String The properties of the message.

      The following describes the key values in the serialized properties of the message:

      • Format: key1:value1|key2:value2|key3:value3
      • The following table lists the key values.
        Parameter Type Description
        KEYS String The message key.
        __STARTDELIVERTIME Long The absolute scheduled time of a scheduled message. Unit: milliseconds in UNIX.
        __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 content

      The following table lists the parameters in the response content.

      Parameter Type Description
      Code String The error code. **MessageNotExist** indicates that no message can be consumed and that it is a normal response.
      Message String The error message.
      RequestId String The ID of the request.
      HostId String The request host.

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>