全部产品
Search

搜索本产品

    轻量消息队列（原 MNS）：请求协议说明

    文档中心

    轻量消息队列（原 MNS）：请求协议说明

    更新时间：Nov 21, 2024

    本文介绍使用轻量消息队列（原 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）

    按照以下伪代码构造待签名的字符串（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>