訂閱者可通過調用訂閱消息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>