445      阿里云

请求签名说明文档__使用手册（调用API）_API 网关-阿里云

• 每个 API 服务都属于一个 API 分组，每个 API 分组有不同的域名。域名是由服务端绑定的独立域名，API 网关通过域名来寻址定位 API 分组。
• 域名的格式为 www.[独立域名].com/[Path]?[HTTPMethod]
• API 网关通过域名定位到一个唯一的分组，通过 Path+HTTPMethod 确定该分组下唯一的 API。
• 您购买后在控制台“已购买的 API”可以获得 API 文档说明，若无购买行为，则可以联系 API 提供者操作授权，授权后您就可以在控制台“已授权的 API”获得 API 文档说明。

系统级Header

• 【必选】X-Ca-Key：AppKey。
• 【必选】X-Ca-Signature：签名字符串。
• 【可选】X-Ca-Timestamp：API 调用者传递时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟。
• 【可选】X-Ca-Nonce：API 调用者生成的 UUID，结合时间戳防重放。
• 【可选】Content-MD5 当请求 Body 非 Form 表单时，可以计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验。
• 【可选】X-Ca-Stage请求 API 所属 Stage，目前仅支持 TEST 和 RELEASE，默认RELEASE，若您调用的 API 不在线上环境，请一定要指定该参数的值，否则会报 URL 错误。

签名校验

组织参与签名计算的字符串

String stringToSign= 
HTTPMethod + "n" + 
Accept + "n" +                //建议显示设置 Accept Header，部分 Http 客户端当 Accept 为空时会给 Accept 设置默认值：*/*，导致签名校验失败。
Content-MD5 + "n" 
Content-Type + "n" + 
Date + "n" + 
Headers + 
Url

HTTPMethod 为全大写，如 POST。

Accept、Content-MD5、Content-Type、Date 如果为空也需要添加换行符”n”，Headers如果为空不需要添加”n”。

Content-MD5

Content-MD5 是指 Body 的 MD5 值，只有当 Body 非 Form 表单时才计算 MD5，计算方式为：

String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

bodyStream 为字节数组。

Headers

Headers 是指参与 Headers 签名计算的 Header 的 Key、Value 拼接的字符串，建议对 X-Ca 开头以及自定义 Header 计算签名，注意如下参数不参与 Headers 签名计算：X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date。

Headers 组织方法：

先对参与 Headers 签名计算的 Header的Key 按照字典排序后使用如下方式拼接，如果某个 Header 的 Value 为空，则使用 HeaderKey + “:” + “n”参与签名，需要保留 Key 和英文冒号。

String headers =
HeaderKey1 + ":" + HeaderValue1 + "n"+
HeaderKey2 + ":" + HeaderValue2 + "n"+
...
HeaderKeyN + ":" + HeaderValueN + "n"

将 Headers 签名中 Header 的 Key 使用英文逗号分割放到 Request 的 Header 中，Key为：X-Ca-Signature-Headers。

Url

Url 指 Path + Query + Body 中 Form 参数，组织方法：对 Query+Form 参数按照字典对 Key 进行排序后按照如下方法拼接，如果 Query 或 Form 参数为空，则 Url = Path，不需要添加”?”，如果某个参数的 Value 为空只保留 Key 参与签名，等号不需要再加入签名。

String url =
Path +
"?" +
Key1 + "=" + Value1 +
"&" + Key2 + "=" + Value2 +
...
"&" + KeyN + "=" + ValueN

注意这里 Query 或 Form 参数的 Value 可能有多个，多个的时候只取第一个 Value 参与签名计算。

计算签名

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] keyBytes = secret.getBytes("UTF-8");
hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
String sign = new String(Base64.encodeBase64(Sha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

secret 为 APP 的密钥。

传递签名

将计算的签名结果放到 Request 的 Header 中，Key为：X-Ca-Signature。

签名错误排查方法

当签名校验失败时，API网关会将服务端的 StringToSign 放到 HTTP Response 的 Header 中返回到客户端，Key为：X-Ca-Error-Message，只需要将本地计算的 StringToSign 与服务端返回的 StringToSign 进行对比即可找到问题；

如果服务端与客户端的 StringToSign 一致请检查用于签名计算的密钥是否正确；

因为 HTTP Header 中无法表示换行，因此 StringToSign 中的换行符都被过滤掉了，对比时请忽略换行符。

签名demo

签名计算的详细demo（JAVA）请参照链接：https://github.com/aliyun/api-gateway-demo-sign-java。

在API网关控制台，调用API——SDK下载处还有更多语言的调用demo。

最后更新：2016-11-23 17:16:06

  上一篇： 使用限制__使用手册（调用API）_API 网关-阿里云

  下一篇： 获取API的定义文档__快速入门（调用API）_API 网关-阿里云