You can call this operation to consume messages from a 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 1024 characters.

    The following table describes the parameters in the request line.

    ParameterRequiredDescription
    TopicNameYesThe name of the topic from which you want to consume messages.
    nsNoThe ID of the instance. This parameter is required for new instances that have namespaces.

    You can check whether your instance has a namespace on the Instances 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 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.
    consumerYesThe ID of the consumer group.
    tagNoThe tag of the message. If you do not specify a tag, all messages are pulled. If you want to specify multiple tags, separate them with double vertical bars (||). For example, you can set this parameter to TagA||TagB.
    numOfMessagesYesThe maximum number of messages that can be consumed at a time. Valid values: 1 to 16.
    waitsecondsNoThe long polling period. If you do not specify this parameter, short polling is used. 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.

      ParameterTypeDescription
      MessageIdStringThe ID of the message.
      MessageBodyMD5StringThe MD5 hash value of the message body.
      MessageBodyStringThe content of the message.
      ReceiptHandleStringThe 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.
      PublishTimeStringThe timestamp that indicates the time when the message was sent. Unit: milliseconds.
      FirstConsumeTimeStringThe timestamp that indicates the time when the message was consumed for the first time. Unit: milliseconds.
      NextConsumeTimeStringThe timestamp that indicates the absolute time when the message was retried. Unit: milliseconds.
      Note If a message that is sent over HTTP fails to be consumed, Message Queue for Apache RocketMQ retries to send the message based on the following mechanism: 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.
      ConsumedTimesStringThe number of retries after the message failed to be consumed.
      MessageTagStringThe tag of the message.
      PropertiesStringThe properties of the message.

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

      • The key-value pairs are displayed in the following format: key1:value1|key2:value2|key3:value3.
      • The following table describes the parameters that are used to indicate the key-value pairs.
        ParameterTypeDescription
        KEYSStringThe key of the message.
        __STARTDELIVERTIMELongThe absolute scheduled time of a scheduled message. This value is a UNIX timestamp that represents the number of milliseconds.
        __TransCheckTLongThe 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.
    • Status line

      HTTP/1.1 404

    • Response body

      The following table describes the parameters in the response body.

      ParameterTypeDescription
      CodeStringThe error code. MessageNotExist indicates that no message is available for consumption. If this error code is returned, the response is a normal response.
      MessageStringThe error message returned.
      RequestIdStringThe ID of the request.
      HostIdStringThe 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>