API請求協議說明 - Simple Message Queue (formerly MNS)

本文介紹使用輕量訊息佇列（原 MNS）發送HTTP請求調用API時的請求結構、公用參數、返回結果及簽名認證方式。

請求結構

服務地址

輕量訊息佇列（原 MNS）支援多個地區，每個地區分別提供了公網訪問地址、內網訪問地址。更多資訊，請參見功能開服和存取點。

要求方法

輕量訊息佇列（原 MNS）支援通過HTTP協議進行請求通訊。使用HTTP的PUT、POST、GET、DELETE等HTTP Method發送不同的請求。

發送的請求需要帶上正確的請求參數、要求標頭和請求本文，請求及返回結果都使用UTF-8字元集進行編碼。

公用參數

公用請求參數（Header）

參數	是否必選	說明
Authorization	是	驗證字串。更多資訊，請參見請求籤名機制。
Content-Length	是	HTTP訊息體的長度。
Content-Type	是	請求內容的MIME類型，目前請求僅支援text或xml格式。
Content-MD5	否	HTTP訊息體的MD5值。更多資訊，請參見The Content-MD5 Header Field。
Date	是	請求的構造時間。目前只支援GMT格式，如果和SMQ的伺服器時間前後差異超過15分鐘將返回本次請求非法。
Host	針對HTTP/1.1為必選，針對HTTP/1.0為可選。	從阿里雲官網擷取AccountId，從API文檔中擷取各地區SMQ訪問地址，格式如下：`$AccountId.mns.cn-hangzhou.aliyuncs.com`。
x-mns-version	是	調用SMQ介面的版本號碼。目前的版本為2015-06-06。
x-mns-date	否	Date替代欄位。用於解決部分瀏覽器上使用者程式無法設定HTTP請求Date欄位的情境。

公用返回參數

參數	說明
Content-Length	HTTP訊息體返回的長度。
Connection	HTTP串連狀態。
Date	響應的返回時間，目前只支援GMT格式。
Server	請求響應的SMQ伺服器名。
x-mns-request-id	此次Request操作的編號。
x-mns-version	SMQ介面的版本編號，目前的版本是2015-06-06。

返回結果

調用API服務後返回資料採用統一格式。返回的HTTP狀態代碼為2xx，說明調用成功；返回的HTTP狀態代碼為4xx或5xx，說明調用失敗。調用成功返回的資料格式為XML格式。

XML返回結果包括請求是否成功資訊和具體的業務資料。樣本如下：

    <?xml version="1.0" encoding="utf-8"?> 
    <!--結果的根結點--> 
    <根節點 xmlns="http://mns.aliyuncs.com/doc/v1/">
    <!--返回的子節點-->
    </根節點>

調用介面出錯後，將不會返回結果資料，HTTP請求返回一個4xx或5xx的HTTP狀態代碼。返回的訊息體中是具體的錯誤碼及錯誤資訊。另外還包含一個全域唯一的請求ID：RequestId和一個您本次請求訪問的網站ID：HostId。

具體的錯誤資訊。請參見錯誤碼。

請求籤名機制

簽名機制介紹

輕量訊息佇列（原 MNS）服務會對每個訪問的請求進行驗證，每個請求向輕量訊息佇列（原 MNS）提交時，都需要在該請求的Header中包含簽名。輕量訊息佇列（原 MNS） SDK已實現自動完成簽名，建議您採用SDK的方式發起請求，即可免去手動簽名的過程。

簽名過程可分為如下步驟：

步驟一：構造待簽名字串（StringToSign）
步驟二：計算簽名值（Signature）
步驟三：將簽名添加到請求中

步驟一：構造待簽名字串（StringToSign）

按照以下虛擬碼構造待簽名的字串（StringToSign）

StringToSign = HttpMethod + "\n" 
         + CONTENT-MD5 + "\n"     
         + CONTENT-TYPE + "\n" 
         + DATE + "\n" 
         + CanonicalizedMNSHeaders
         + CanonicalizedResource;

參數	描述
HttpMethod	大寫的HTTP方法。例如：PUT、GET、POST、DELETE。
Content-Md5	請求內容資料的MD5值，若無則為空白。
CONTENT-TYPE	請求內容的類型，若無則為空白。
DATE	本次操作的時間。格式為：`Thu, 07 Mar 2012 18:49:58 GMT`。如果用`x-mns-date`替代DATE，則DATE不能填空，需用`x-mns-date`的值替換。此參數不可為空，目前只支援GMT格式。如果請求時間和輕量訊息佇列（原 MNS）伺服器時間相差超過15分鐘，輕量訊息佇列（原 MNS）會判定此請求不合法，返回錯誤碼400。更多錯誤資訊及錯誤碼，請參見錯誤碼。
CanonicalizedMNSHeaders	HTTP中的`x-mns-`開頭的欄位組合。該欄位在簽名驗證前需要符合以下規範： Header的key需要變成小寫（toLowerCase）。 Header自小到大排序。拼接虛擬碼。 `// 原始請求Header Map<String, String> httpHeaders = request.getHeaders(); // 排序和小寫 sortHeadersKeyAndToLowerCase(httpHeaders); // 拼接 Set<String> keySet = httpHeaders.keySet(); for (String key : keySet) { if (key.startsWith("x-mns-")) { CanonicalizedMNSHeaders.append(key).append(":") .append(httpHeaders.get(key)).append("\n"); } }`
CanonicalizedResource	HTTP所請求資源的URI，是指對應訂閱配置的HTTP接收端地址去除網域名稱連接埠的部分。例如配置的接收端地址是`http://123.123.XX.XX:8080/api/test?code=200`，則URI是`/api/test?code=200`；如果接收端地址是`http://www.aliyun.com/mns/help`，則URI是`/mns/help`。

步驟二：計算簽名值（Signature）

Signature = Base64( HMAC-SHA1( ${AccessSecret}, UTF-8-Encoding-Of(${StringToSign})) )

其中，各參數的含義如下：

參數	說明
Base64	Base64編碼。
HMAC-SHA1	簽名的方法採用RFC 2104中定義的`HMAC-SHA1`方法。
AccessSecret	阿里雲使用者AccessKey Secret，和簽名的AccessKey ID對應。
UTF-8-Encoding-Of	指UTF-8 格式。
StringToSign	自訂構建的待簽名字串，即步驟一：構造待簽名字串（StringToSign）產生的值。

步驟三：將簽名添加到請求中

addHeader("Authorization","MNS " +  ${AccessKeyId}+ ":" + ${Signature})

Key為常量的字串Authorization，Value為基於AccessKeyId和Sigature兩個變數拼接成的字串，整體格式為MNS ${accessKeyId}:${Signature}。其中Sigature為輕量訊息佇列（原 MNS）自訂構建的簽名，即步驟二：計算簽名值（Signature）產生的值。

簽名樣本

請求樣本如下：

PUT /queues/$queueName?metaOverride=true HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 08 Mar 2012 12:00:00 GMT
Authorization: MNS 15B4D3461F177624****:xQE0diMbL****f3YB+FIEXAMPLE=

<?xml version="1.0" encoding="UTF-8"  ?>
<Queue xmlns="http://mns.aliyuncs.com/doc/v1/">
<VisibilityTimeout >60</VisibilityTimeout>
<MaximumMessageSize>1024</MaximumMessageSize>
<MessageRetentionPeriod>120</MessageRetentionPeriod>
<DelaySeconds>30</DelaySeconds>
</Queue>

返回樣本如下：

樣本一

如果傳入的AccessKeyId不存在或disabled，返回403 Forbidden。

Content-Type: text/xml
Content-Length: 314
Date: Wed, 18Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956****

<?xml version="1.0" encoding="utf-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>AccessIDAuthError</Code>
<Message>
    AccessID authentication fail, please check your AccessID and retry.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>

樣本二

如果簽名驗證的時候，Header中沒有傳入Date或者格式不正確，返回403 Forbidden。

Content-Type: text/xml
Content-Length: 274
Date: Wed, 18Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956****

<?xml version="1.0" encoding="UTF-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>InvalidArgument</Code>
<Message>Date Header is invalid or missing.</Message>
<RequestId>7E1A5CF258F535884403****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>

樣本三

傳入請求的時間在輕量訊息佇列（原 MNS）伺服器目前時間之後的15分鐘以內，否則返回408逾時。

Content-Type: text/xml
Content-Length: 283
Date: Wed, 11 May 2011 09:01:51 GMT
x-mns-request-id: 512B2A634403E52B1956****

<?xml version="1.0"  encoding="UTF-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>TimeExpired</Code>
<Message>
        The http request you sent is expired.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>