本文介绍使用轻量消息队列(原 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访问地址,格式如下: |
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)
按照以下伪代码构造待签名的字符串(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 | 本次操作的时间。
|
CanonicalizedMNSHeaders | HTTP中的
|
CanonicalizedResource | HTTP所请求资源的URI。例如 |
步骤二:计算签名值(Signature)
Signature = Base64( HMAC-SHA1( ${AccessSecret}, UTF-8-Encoding-Of(${StringToSign})) )
其中,各参数的含义如下:
参数 | 说明 |
Base64 | Base64编码。 |
HMAC-SHA1 | 签名的方法采用RFC 2104中定义的 |
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>