請(qǐng)求協(xié)議說(shuō)明
本文介紹使用輕量消息隊(duì)列（原 MNS）發(fā)送HTTP請(qǐng)求調(diào)用API時(shí)的請(qǐng)求結(jié)構(gòu)、公共參數(shù)、返回結(jié)果及簽名認(rèn)證方式。
請(qǐng)求結(jié)構(gòu)
服務(wù)地址
輕量消息隊(duì)列（原 MNS）支持多個(gè)地域，每個(gè)地域分別提供了公網(wǎng)訪問地址、內(nèi)網(wǎng)訪問地址。更多信息，請(qǐng)參見功能開服和接入點(diǎn)。
請(qǐng)求方法
輕量消息隊(duì)列（原 MNS）支持通過(guò)HTTP協(xié)議進(jìn)行請(qǐng)求通信。使用HTTP的PUT、POST、GET、DELETE等HTTP Method發(fā)送不同的請(qǐng)求。
發(fā)送的請(qǐng)求需要帶上正確的請(qǐng)求參數(shù)、請(qǐng)求頭和請(qǐng)求正文，請(qǐng)求及返回結(jié)果都使用UTF-8字符集進(jìn)行編碼。
公共參數(shù)
公共請(qǐng)求參數(shù)（Header）
參數(shù) | 是否必選 | 說(shuō)明 |
Authorization | 是 | 驗(yàn)證字符串。更多信息，請(qǐng)參見請(qǐng)求簽名機(jī)制。 |
Content-Length | 是 | HTTP消息體的長(zhǎng)度。 |
Content-Type | 是 | 請(qǐng)求內(nèi)容的MIME類型，目前請(qǐng)求僅支持text或xml格式。 |
Content-MD5 | 否 | HTTP消息體的MD5值。更多信息，請(qǐng)參見The Content-MD5 Header Field。 |
Date | 是 | 請(qǐng)求的構(gòu)造時(shí)間。目前只支持GMT格式，如果和SMQ的服務(wù)器時(shí)間前后差異超過(guò)15分鐘將返回本次請(qǐng)求非法。 |
Host | 針對(duì)HTTP/1.1為必選，針對(duì)HTTP/1.0為可選。 | 從阿里云官網(wǎng)獲取AccountId，從API文檔中獲取各地域SMQ訪問地址，格式如下： |
x-mns-version | 是 | 調(diào)用SMQ接口的版本號(hào)。當(dāng)前版本為2015-06-06。 |
x-mns-date | 否 | Date替代字段。用于解決部分瀏覽器上用戶程序無(wú)法設(shè)置HTTP請(qǐng)求Date字段的場(chǎng)景。 |
公共返回參數(shù)
參數(shù) | 說(shuō)明 |
Content-Length | HTTP消息體返回的長(zhǎng)度。 |
Connection | HTTP連接狀態(tài)。 |
Date | 響應(yīng)的返回時(shí)間，目前只支持GMT格式。 |
Server | 請(qǐng)求響應(yīng)的SMQ服務(wù)器名。 |
x-mns-request-id | 此次Request操作的編號(hào)。 |
x-mns-version | SMQ接口的版本編號(hào)，當(dāng)前版本是2015-06-06。 |
返回結(jié)果
調(diào)用API服務(wù)后返回?cái)?shù)據(jù)采用統(tǒng)一格式。返回的HTTP狀態(tài)碼為2xx，說(shuō)明調(diào)用成功；返回的HTTP狀態(tài)碼為4xx或5xx，說(shuō)明調(diào)用失敗。調(diào)用成功返回的數(shù)據(jù)格式為XML格式。
XML返回結(jié)果包括請(qǐng)求是否成功信息和具體的業(yè)務(wù)數(shù)據(jù)。示例如下：
<?xml version="1.0" encoding="utf-8"?>
<!--結(jié)果的根結(jié)點(diǎn)-->
<根節(jié)點(diǎn) xmlns="http://mns.aliyuncs.com/doc/v1/">
<!--返回的子節(jié)點(diǎn)-->
</根節(jié)點(diǎn)>調(diào)用接口出錯(cuò)后，將不會(huì)返回結(jié)果數(shù)據(jù)，HTTP請(qǐng)求返回一個(gè)4xx或5xx的HTTP狀態(tài)碼。返回的消息體中是具體的錯(cuò)誤代碼及錯(cuò)誤信息。另外還包含一個(gè)全局唯一的請(qǐng)求ID：RequestId和一個(gè)您本次請(qǐng)求訪問的站點(diǎn)ID：HostId。
具體的錯(cuò)誤信息。請(qǐng)參見錯(cuò)誤碼。
請(qǐng)求簽名機(jī)制
簽名機(jī)制介紹
輕量消息隊(duì)列（原 MNS）服務(wù)會(huì)對(duì)每個(gè)訪問的請(qǐng)求進(jìn)行驗(yàn)證，每個(gè)請(qǐng)求向輕量消息隊(duì)列（原 MNS）提交時(shí)，都需要在該請(qǐng)求的Header中包含簽名。輕量消息隊(duì)列（原 MNS） SDK已實(shí)現(xiàn)自動(dòng)完成簽名，建議您采用SDK的方式發(fā)起請(qǐng)求，即可免去手動(dòng)簽名的過(guò)程。
簽名過(guò)程可分為如下步驟：
步驟一：構(gòu)造待簽名字符串（StringToSign）
按照以下偽代碼構(gòu)造待簽名的字符串（StringToSign）
StringToSign = HttpMethod + "\n"
+ CONTENT-MD5 + "\n"
+ CONTENT-TYPE + "\n"
+ DATE + "\n"
+ CanonicalizedMNSHeaders
+ CanonicalizedResource;參數(shù) | 描述 |
HttpMethod | 大寫的HTTP方法。例如：PUT、GET、POST、DELETE。 |
Content-Md5 | 請(qǐng)求內(nèi)容數(shù)據(jù)的MD5值，若無(wú)則為空。 |
CONTENT-TYPE | 請(qǐng)求內(nèi)容的類型，若無(wú)則為空。 |
DATE | 本次操作的時(shí)間。
|
CanonicalizedMNSHeaders | HTTP中的
|
CanonicalizedResource | HTTP所請(qǐng)求資源的URI。例如 |
步驟二：計(jì)算簽名值（Signature）
Signature = Base64( HMAC-SHA1( ${AccessSecret}, UTF-8-Encoding-Of(${StringToSign})) ) 其中，各參數(shù)的含義如下：
參數(shù) | 說(shuō)明 |
Base64 | Base64編碼。 |
HMAC-SHA1 | 簽名的方法采用RFC 2104中定義的 |
AccessSecret | 阿里云用戶AccessKey Secret，和簽名的AccessKey ID對(duì)應(yīng)。 |
UTF-8-Encoding-Of | 指UTF-8 格式。 |
StringToSign | 自定義構(gòu)建的待簽名字符串，即步驟一：構(gòu)造待簽名字符串（StringToSign）生成的值。 |
步驟三：將簽名添加到請(qǐng)求中
addHeader("Authorization","MNS " + ${AccessKeyId}+ ":" + ${Signature})Key為常量的字符串Authorization，Value為基于AccessKeyId和Sigature兩個(gè)變量拼接成的字符串，整體格式為MNS ${accessKeyId}:${Signature}。其中Sigature為輕量消息隊(duì)列（原 MNS）自定義構(gòu)建的簽名，即步驟二：計(jì)算簽名值（Signature）生成的值。
簽名示例
請(qǐng)求示例如下：
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> 示例二
如果簽名驗(yàn)證的時(shí)候，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> 示例三
傳入請(qǐng)求的時(shí)間在輕量消息隊(duì)列（原 MNS）服務(wù)器當(dāng)前時(shí)間之后的15分鐘以內(nèi)，否則返回408超時(shí)。
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>