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