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