订阅者可通过调用订阅消息API来消费消息队列RocketMQ版服务端中的消息。

请求构造

  • 请求行

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

    重要 请求行总长度不能超过1024个字符。

    参数说明如下。

    参数 是否必选 说明
    TopicName 是 将消息发送至的Topic名称。
    ns 否 实例ID，针对有命名空间的新建实例，该参数为必填。

    是否有命名空间可以在控制台实例详情页面查看。实例根据其是否有命名空间分为默认实例和新建实例：

    • 默认实例：无命名空间，所有资源命名在该默认实例内需全局唯一。
    • 新建实例：有命名空间，资源命名只需保证在该实例内唯一。
    详细信息，请参见实例化支持。
    consumer 是 消费者群组的标识，即Group ID。
    tag 否 消息Tag。如果不指定Tag，则拉取所有消息。如果需要指定多个Tag，则使用双竖线（||）隔开，例如TagA||TagB。
    numOfMessages 是 一次最多消费多少条消息，取值范围：1～16。
    waitseconds 否 长轮询时间，不填则为短轮询，取值范围：1～30，单位：秒。
  • 请求内容（XML格式）

    无

响应构造

  • 有消息可消费
    • 响应行

      HTTP/1.1 200

    • 响应内容

      响应内容的参数说明如下。

      参数 类型 说明
      MessageId String 消息ID。
      MessageBodyMD5 String 消息内容的MD5。
      MessageBody String 消息内容。
      ReceiptHandle String 消息的句柄，用于确认消息消费成功，句柄仅使用一次，对于同一条消息如果存在重试每次拿到的句柄是不同的，消息句柄应该在到NextConsumeTime指定的时间之前使用。
      PublishTime String 消息的发送时间戳，单位：毫秒。
      FirstConsumeTime String 消息第一次消费的时间戳，单位：毫秒。
      NextConsumeTime String 该消息再次被消费到（即重试）的绝对时间戳，单位：毫秒。
      说明 HTTP协议下 消息队列RocketMQ版的消息重试机制为：无序消息每隔5分钟重试一次，顺序消息每隔1分钟重试一次，最多重试288次。
      ConsumedTimes String 消息被消费的次数。
      MessageTag String 消息Tag。
      Properties String 消息属性。

      属性（Properties）的序列化，其中特殊用途的键值说明如下：

      • 格式：key1:value1|key2:value2|key3:value3
      • 键值说明如下：
        参数 类型 说明
        KEYS String 消息的Key。
        __STARTDELIVERTIME Long 表示定时消息的定时绝对时间，UNIX毫秒时间戳。
        __TransCheckT Long 表示第一次事务消息的回查时间，相对时间，单位：秒，取值范围：10～300。
  • 无消息可消费
    • 响应行

      HTTP/1.1 404

    • 响应内容

      响应内容的参数说明如下。

      参数 类型 说明
      Code String 错误代码，其中MessageNotExist表示没有消息可以消费，是正常的响应。
      Message String 错误内容。
      RequestId String 请求ID。
      HostId String 请求Host。

响应示例

  • 有消息可消费
    <?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>
  • 无消息可消费
    <?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>