阿里云API网关（3）快速入门（调用 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参数定义。
• 应用 app：作为调用API时的身份， AppKey 和 AppSecret 用于验证身份。
• API 和 App 的权限关系：App 想调用某个 API 需要具有该 API 的权限，这个权限通过授权的功能来建立。

以下会详细说如何具备三个条件，并提供 API 调用 Demo 供参考。

一、获取 API 文档

1、从数据市场购买的 API 服务

您购买 API 服务时，如果还没有开通 API 网关服务，那么会同时帮助您开通 API 网关服务，让您使用的更流畅。

购买成功之后您进入云市场的 管理控制台，就会看见您购买的所有 API 服务。您可以在当前控制台查看 API 接口的定义。

             

您还可以跳转到 API 网关的控制台，在 已购买 API 页面，展示您购买的所有 API 服务列表，以及使用情况概况。

选择一个服务点击 查看 API ，页面会展示该服务的基本信息和 API 接口列表。注意在基本信息处关键的信息是 访问域名。

选择一个 API 接口，点击 详情，就会出现详细的接口定义了。

2、不经过购买，由提供方主动授权

提供 API 的一方需要在控制台主动操作授权，这时您需要已经创建过应用 APP，并且将 AppId告知提供方，由他们搜索您的 APP 然后操作授权。

APP 的相关内容在 创建 APP 中介绍。这里先假设您已经创建了 APP，并且提供 API 的一方已经为您的 APP 授权。

您进入 API 网关的控制台应用管理页面，这里是您创建的所有应用APP。

点击 APP 的名称进入 APP 详情，此处会展示 APP 的基本信息以及两个最重要的信息。AppKey 和 已授权的 API 。

AppKey 是您这个 APP 的 Key 和 Secret。您请求的时候需要带上这对密钥，网关会根据这对密钥对您进行身份验证。后面会详细解释。已授权的 API 是您该 APP 已经被授权的 API ，如果提供方已经操作了授权，那么您会在这里看见 API 接口。点击 详情 就可以查看详细的接口定义

以上是两种 API 渠道的获取 API 定义的方式。

二、创建应用

应用（APP）是调用 API 服务时的身份。

每个 APP 有一组 Key 和 Secret，调用 API 时这两个参数的用途如下：

• 将 AppKey 做参数传入
• AppSecret 用于签名计算，不能在请求中传递，

网关会校验这对密钥对您进行身份认证。

调用 API 需要这个 APP 具备调用该API的权限，这个授权和鉴权是面向 APP 的。您可以在 API 网关控制台 应用管理 页面创建您的 APP。

创建成功后，系统会为 APP 分配一对 AppKey 和 AppSecret。

调用服务时，客户端程序需要用 AppSecret 完成签名计算，请求时携带AppKey和签名信息1，

网关会根据AppKey找到服务器侧的AppSecret重新计算签名信息2和签名信息1比对，这就是身份验证。

在应用管理 页面，点击应用名称进入详情，就能看见 AppKey 和 AppSecret 信息了，如果密钥丢失还可以操作重置。

APP 更多说明参见 用户指南（调用API）

三、获得授权

授权，是指授予 APP 调用某个 API 的权限。您的 APP 需要获得 API 的授权才能调用该API。根据获取 API 的渠道不同，建立授权的方式也不同。

从数据市场购买的 API 服务

您购买了 API 服务就意味着您已经获得了授权。但是为了更精确的权限控制，您的账号获得了授权，不代表您的每个 APP 都获得了授权。您需要手动操作将已购买的API授权给哪些 APP，然后这些 APP 才能调用该API。

不经过购买，由提供方主动授权

您需要向 API 服务商提供您的 应用 ID (AppID) 或者阿里云邮箱账户，使 API 服务商能够搜索到您的 APP，并完成授权。完成授权后您可以在控制台看到该 APP 被授权的 API。

由提供方操作授权的 API 会出现在应用详情的 已授权 API 子页面。提供方授权时就已经将 API 授权给准确的 APP 了，所以不需要调用者来操作授权。

四、调用 API

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

通过上述步骤，您已经获取了 API 定义文档、创建了 APP、建立了授权关系。

您可以调用 API 了。API 的请求步骤说明如下：

第一部分：请求

请求地址：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定义可以设置多个自定义请求头。

第二部分：响应

状态码：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 协议提交请求，都需要在请求中包含签名信息。详细加密签名的计算传递方式，见下。

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

五、请求签名说明文档

1、名词解释

1.1、域名

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

1.2、系统级 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 错误。

2、签名校验

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

String stringToSign=

HTTPMethod + " " +

Accept + " " + //建议显示设置 Accept Header。当 Accept 为空时，部分 Http 客户端会给 Accept 设置默认值为 */*，导致签名校验失败。

Content-MD5 + " "

Content-Type + " " +

Date + " " +

Headers +

Url

HTTPMethod 为全大写，如 POST。

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

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 + “:” + “ ”参与签名，需要保留 Key 和英文冒号。

String headers =

HeaderKey1 + ":" + HeaderValue1 + " "+

HeaderKey2 + ":" + HeaderValue2 + " "+

...

HeaderKeyN + ":" + HeaderValueN + " "

将 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 参与签名计算。

2.2、计算签名

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 的密钥。

2.3、传递签名

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

3、签名错误排查方法

当签名校验失败时，API网关会将服务端的 StringToSign 放到 HTTP Response 的 Header 中返回到客户端，Key为：X-Ca-Error-Message，

只需要将本地计算的 StringToSign 与服务端返回的 StringToSign 进行对比即可找到问题；

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

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

4、签名 demo

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

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