文档

订阅消息API

更新时间:
一键部署

订阅者可通过调用订阅消息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

    长轮询时间。设置为0或未设置时则为短轮询。

    取值范围:0~30,单位:秒。

    消费者向服务端获取消息消费时,支持长轮询和短轮询两种调用方式。

    • 长轮询:消费者向服务端发送请求获取指定Topic中的消息,若Topic中没有消息,服务端不会立即返回响应,会将该请求挂起,直到Topic有消息或达到长轮询时间才会返回响应。

    • 短轮询:若Topic中没有消息,服务端会立即返回响应,且再次不断发起订阅请求。

    说明

    当Topic中没有消息产生时,短轮询方式可能会产生大量无效的订阅请求,这部分请求也会仍然计算API调用费用,建议您可以使用长轮询方式适当增加长轮询等待时间,减少无效请求次数以降低费用。具体API调用费用计算方式,请参见API调用费用

  • 请求内容(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>       
  • 本页导读 (1)