调用方式
请求结构
服务地址
MNS 服务在多个地域部署，都分别提供了公网访问地址和阿里云私网访问 地址。如表所示：
| 区域 | 公网访问地址 | 私网访问地址 |
|---|---|---|
| 杭州 | mns.cn-hangzhou.aliyuncs.com | mns.cn-hangzhou-internal.aliyuncs.com |
| 青岛 | mns.cn-qingdao.aliyuncs.com | mns.cn-qingdao-internal.aliyuncs.com |
| 北京 | mns.cn-beijing.aliyuncs.com | mns.cn-beijing-internal.aliyuncs.com |
通信协议
支持通过 HTTP 协议进行请求通信。
请求方法
使用 HTTP 的 PUT、 POST、 GET、 DELETE 等 HTTP Method 发送不同的请 求，详见下文“开放接口规范”章节。
请求组成
向 MNS 发送 HTTP 请求完成某项 API接口操作，发送的请求还需要带上正确的请求参数、请求头以及请求正文。
请求编码
请求及返回结果都使用 UTF-8 字符集进行编码。
公共参数
公共请求头
| 参数名称 | 说明 | 选项 |
|---|---|---|
| Authorization | 验证字符串，由MNS + 空格 + AccessKeyId + : + signature构成，详见本文档在Head中包含签名部分 | Required |
| Content-Length | HTTP消息体的长度 | Required |
| Content-Type | 请求内容的MIME类型，目前请求仅支持text/xml格式 | Required |
| Content-MD5 | HTTP消息体的MD5值, 具体格式请参考https://tools.ietf.org/html/rfc1864 | Optional |
| Date | 请求的构造时间，目前只支持GMT格式，如果和MNS的服务器时间前后差异超过15分钟将返回本次请求非法 | Required |
| Host | 从阿里云官网获取AccountId，从API文档中获取各region MNS访问地址，格式如下：$AccountId.mns.cn-hangzhou.aliyuncs.com Required(HTTP/1.1) | Optional(HTTP/1.0) |
| x-mns-version | 调用MNS接口的版本号，当前版本为2015-06-06 | Required |
公共返回头
| 参数名称 | 说明 |
|---|---|
| Content-Length | HTTP消息体返回的长度 |
| Connection | HTTP连接状态 |
| Date | 响应的返回时间，GMT时间格式 |
| Server | 请求响应的MNS服务器名 |
| x-mns-request-id | 此次Request操作的编号 |
| x-mns-version | MNS接口的版本编号，当前版本是2015-06-06 |
返回结果
调用 API 服务后返回数据采用统一格式，返回的HTTP状态码为2xx，代表调用成功；返回 4xx 或5xx的HTTP状态码代表调用失败。调用成功返回的数据格式为XML。本文档中的返回示例为了便于用户查看，做了格式化处理，实际返回结果是没有进行换行、缩进等处理的。
返回成功
XML返回结果包括请求是否成功信息和具体的业务数据。示例如下：
<?xml version="1.0" encoding="utf-8"?>
<!—结果的根结点-->
<根节点 xmlns=”http://mns.aliyuncs.com/doc/v1/”>
<!—返回的子节点-->
</根节点>
错误结果
调用接口出错后，将不会返回结果数据。调用方可根据附表<错误代码表>来定位错误原因。
当调用出错时，HTTP请求返回一个4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。另外还包含一个全局唯一的请求ID：RequestId 和一个您该次请求访问的站点ID：HostId。在调用方找不到错误原因，可以联系阿里云客服，并提供该 HostId 和RequestId，以便我们尽快帮您解决问题。
签名机制
Access Key ID和Access Key Secret由阿里云官方颁发给访问者（可以通过阿里云官方网站申请和管理），其中 Access Key ID 用于标识访问者的身份；Access Key Secret 是用于加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密，只有阿里云和用户知道。
MNS服务会对每个访问的请求进行验证，每个向MNS提交的请求，都需要在请求中包含签名（Signature）信息。MNS通过使用 Access Key ID 和Access Key Secret 进行对称加密的方法来验证请求的发送者身份。如果计算出来的验证码和提供的一样即认为该请求是有效的；否则，MNS将拒绝处理这次请求，并返回HTTP 403错误。
用户可以在HTTP请求中增加Authorization（授权）的Head来包含签名信息，表明这个消息已被授权。
MNS要求将签名包含在HTTP Header中，格式如下： Authorization: MNS空格 Access Key Id : Signature
Signature计算方法如下：
Signature = base64(hmac-sha1(VERB + "\n"
+ CONTENT-MD5 + "\n"
+ CONTENT-TYPE + "\n"
+ DATE + "\n"
+ CanonicalizedMNSHeaders
+ CanonicalizedResource))
- VERB表示HTTP的Method(如示例中：PUT)
- Content-Md5 表示请求内容数据的MD5值（见下文其他事项3）
- CONTENT-TYPE表示请求内容的类型（见下文其他事项3）
- DATE表示此次操作的时间，不能为空，目前只支持GMT格式，如果请求时间和MNS服务器时间相差超过15分钟，MNS会判定此请求不合法，返回400错误，错误信息及错误码详见本文档第5部分。（如示例中：Thu, 17 Mar 2012 18:49:58 GMT）
- CanonicalizedMNSHeaders表示 http中的x-mns-开始的字段组合。（见下文注意事项）
- CanonicalizedResource表示http所请求资源的URI(统一资源标识符)。（如示例中：/queues/$queueName?metaOverride=true）
注意：
CanonicalizedMNSHeaders（即x-mns-开头的head）在签名验证前需要符合以下规范:
- head的名字需要变成小写
- head自小到大排序
- 分割head name和value的冒号前后不能有空格
- 每个Head之后都有一个\n，如果没有以x-mns-开头的head，则在签名时CanonicalizedMNSHeaders就设置为空
其他：
- 用来签名的字符串为UTF-8格式。
- 签名的方法用RFC 2104。中定义的HMAC-SHA1方法，其中Key为AccessKeySecret。
- content-type和content-md5在请求中不是必须的，但是如果请求需要签名验证，空值的话以\n符代替。
请求的示例如下：
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 15B4D3461F177624206A:xQE0diMbLRepdf3YB+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>
如果传入的AccessKey Id不存在或inactive，返回403 Forbidden。
返回示例：
Content-Type: text/xml
Content-Length: 314
Date: Wed, 18Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956133E
<?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>512B2A634403E52B1956133E</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>
`
如果签名验证的时候，头中没有传入Date或者格式不正确，返回403 Forbidden错误。
返回示例：
Content-Type: text/xml
Content-Length: 274
Date: Wed, 18Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956133E
<?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>7E1A5CF258F535884403E533</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: 512B2A634403E52B1956133E
<?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>512B2A634403E52B1956133E</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>