阿里云API网关（5）用户指南（调用 API）

网关指南： https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl

网关控制台： https://apigateway.console.aliyun.com/?spm=5176.doc42740.2.2.Q4z5ws#/cn-hangzhou/apis/list

一、概述

您可以通过 API 网关，调用由其他阿里云用户或者第三方服务商开放的 API 服务。API 网关将为您提供一系列管理服务与支撑。

调用 API

您可以直接用 API 网关控制台为您提供的多语言调用示例来测试调用。您也可以自行编辑 HTTP(s) 请求调用 API 。签名方式您可以参照控制台的 SDK示例下载。

API 调用方式说明及示例如下：（调用 API 前期流程请参照 快速入门（调用 API））。

1.请求

请求地址

http://e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com/demo/post

请求方法

POST

请求体

FormParam1=FormParamValue1&FormParam2=FormParamValue2

//HTTP Request Body

请求头部

Host: e710888d3ccb4638a723ff8d03837095-cn-qingdao.aliapi.com

Date: Mon, 22 Aug 2016 11:21:04 GMT

User-Agent: Apache-HttpClient/4.1.2 (java 1.6)

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

//请求体类型，请根据实际请求体内容设置。

Accept: application/json

//请求响应体类型，部分 API 可以根据指定的响应类型来返回对应数据格式，建议手动指定此请求头，如果不设置，部分 HTTP 客户端会设置默认值 */*，导致签名错误。

X-Ca-Request-Mode: debug

//是否开启 Debug 模式，大小写不敏感，不设置默认关闭，一般 API 调试阶段可以打开此设置。

X-Ca-Version: 1

// API 版本号，目前所有 API 仅支持版本号『1』，可以不设置此请求头，默认版本号为『1』。

X-Ca-Signature-Headers: X-Ca-Request-Mode,X-Ca-Version,X-Ca-Stage,X-Ca-Key,X-Ca-Timestamp

//参与签名的自定义请求头，服务端将根据此配置读取请求头进行签名，此处设置不包含 Content-Type、Accept、Content-MD5、Date 请求头，这些请求头已经包含在了基础的签名结构中，详情参照请求签名说明文档。

X-Ca-Stage: RELEASE

//请求 API 的 Stage，目前支持 TEST、PRE、RELEASE 三个 Stage，大小写不敏感，API 提供者可以选择发布到哪个 Stage，只有发布到指定 Stage 后 API 才可以调用，否则会提示 API 找不到或 Invalid Url。

X-Ca-Key: 60022326

//请求的 AppKey，请到 API 网关控制台生成，只有获得 API 授权后才可以调用，通过云市场等渠道购买的 API 默认已经给 APP 授过权，阿里云所有云产品共用一套 AppKey 体系，删除 ApppKey 请谨慎，避免影响到其他已经开通服务的云产品。

X-Ca-Timestamp: 1471864864235

//请求的时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟。

X-Ca-Nonce:b931bc77-645a-4299-b24b-f3669be577ac

//请求唯一标识，15分钟内 AppKey+API+Nonce 不能重复，与时间戳结合使用才能起到防重放作用。

X-Ca-Signature: FJleSrCYPGCU7dMlLTG+UD3Bc5Elh3TV3CWHtSKh1Ys=

//请求签名。

CustomHeader: CustomHeaderValue

//自定义请求头，此处仅作为示例，实际请求中根据 API 定义可以设置多个自定义请求头。

2.响应

状态码

400

//响应状态码，大于等于200小于300表示成功；大于等于400小于500为客户端错误；大于500为服务端错误。

响应头

X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF

//请求唯一 ID，请求一旦进入 API 网关应用后，API 网关就会生成请求 ID 并通过响应头返回给客户端，建议客户端与后端服务都记录此请求 ID，可用于问题排查与跟踪。

X-Ca-Error-Message: Invalid Url

//API网关返回的错误消息，当请求出现错误时 API 网关会通过响应头将错误消息返回给客户。

X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}

//当打开 Debug 模式后会返回 Debug 信息，此信息后期可能会有变更，仅用做联调阶段参考

您调用 API 时，无论使用 HTTP 还是 HTTPS 协议提交请求，都需要在请求中包含签名信息。AppKey 用于标识您的身份，AppSecret 是用于加密签名字符串和服务器端验证签名字符串的密钥。详细加密签名的计算传递方式，请查看文档 请求签名说明文档。

签名的计算 demo 请参照 API 网关控制台 SDK下载 页面的 SDK 示例。

若需要了解更多详情，请您查看 用户指南（调用API）。

二、应用app

您需要创建应用（APP）作为您调用 API 的身份，每个 APP 有一对 AppKey 和 AppSecret 密钥对，AppKey 需要在请求时作为参数在 Header 传入，AppSecret 需要用于计算请求签名。

在 API 网关，您需要创建应用（APP）作为请求者的身份。APP 创建时，系统会自动分配一对 AppKey 和 AppSecret。在您请求 API 时，需要用到密钥。详细加密签名的计算传递方式，请查看文档——请求签名说明文档。

AppKey 和 AppSecret 密钥对，具备该 APP 的全部权限，需要妥善保管。如果发生泄漏，您可以在 API 网关的控制台进行重置。

您可以拥有多个 APP，可以根据您的业务需求分别被授权不同的 API。注意，API 的授权对象是 APP 而不是阿里云用户账号。

您可以在 API 网关控制台完成对 APP 的创建、修改、删除、查看详情、密钥管理、查看已授权等管理操作。

三、授权

授权，是指授予某个 APP 调用某个 API 的权限。您的 APP 需要获得 API 的授权才能调用该API。

• 如果您在市场购买了 API，那么您有权操作已购买的 API 授权给您的 APP；如果您没有 APP,购买时云市场会为您创建一个 APP，并且授权，具体请前往云市场的 控制台 查看。
• 如果您想要使用合作伙伴提供的 API，并无购买行为，是线下协议。那么需要 API 的提供者主动操作授权。您需要自行创建 APP，并且向 API 的提供者提供您的 AppId。

四、加密签名

您调用 API 时，需要拼接签名字符串，并将签名计算后的字符串放在请求的 Header 传入，网关会通过对称计算签名来验证请求者的身份。

在请求的 Header 需要传入一个计算后的签名字符串。

您需要将入参信息按照请求签名说明文档组织成为 String to sign，再用 SDK 样例中的算法计算签名。计算结果就是上面提到的计算后的签名字符串。

HTTP 和 HTTPS 请求，都需要加入请求签名。

请求签名 String to sign 的组织方法详见请求签名说明文档，您只需要在SDK 样例中，将 AppKey、AppSecret 换成您自己的真实密钥值，再根据实际 API 文档按照签名文档组织 String to sign，您就可以成功发起请求了。

五、使用限制

• 每个账号下 app 个数上限为10个，app 名称应为账号下唯一。
• 调用 API 的流控限制为，单个 IP，QPS 不超过100。
• 您有权操作购买的 API 与 app 的授权和解除授权。由服务提供方授权给您 app 的 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 、PRE 和 RELEASE，默认RELEASE，若您调用的 API 不在线上环境，请一定要指定该参数的值，否则会报 URL 错误。

签名校验

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

String stringToSign=

HTTPMethod + "\n" +

Accept + "\n" + //建议显示设置 Accept Header。当 Accept 为空时，部分 Http 客户端会给 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。