阿里云API网关（4）快速入门（开放 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

http://66bc382db8344b3b93056c696fab49a8-cn-hangzhou.alicloudapi.com/LsqGrp1/LsqApi1?access_token=2689594c-ca7e-4b54-a20a-43b538f2b3c7

一、创建api分组

API 分组是 API 的管理单元，先创建 API 分组，然后在分组下创建 API。

• 分组有 Region 属性，API 选定分组就选定了 Region，不可更改。

• 分组创建时，会绑定一个唯一的二级域名，您可以访问该二级域名调用该分组下测试中的 API。

• 若要开放 API 服务，您需要为分组绑定独立域名，独立域名需要在阿里云系统备案并且 CNAME 到该分组的二级域名上，用户访问独立域名时会调用该分组下线上的 API。

• 如果您的 API 支持 HTTPS 协议，您还需要为该独立域名上传 SSL 证书。

二、绑定域名和证书

域名是绑定在 API 分组上面的，API 网关通过域名来定位到一个唯一的 API 分组，再通过Path+HTTPMethod 确定唯一的 API。

如果您需要开放 API 则需要为分组绑定独立域名。独立域名需要满足以下几点：

• 独立域名需要在 阿里云备案 或者在 阿里云备案接入。
• 独立域名要 CNAME 解析到该分组的二级域名上，然后操作绑定。先解析，后绑定，否则绑定操作会报错。
• 若您需要将其他分组的独立域名变更到当前分组，需要先变更解析，才能成功绑定。

若该分组下的 API 支持 HTTPS 协议，您还需要为该独立域名上 SSL 证书。不支持文件上传，需要填写证书名称、内容和私钥。

三、创建api

API 分组创建完成您就可以创建 API 了，创建 API 是定义 API 请求的过程。您需要在创建中依次定义以下内容：

1. API 的基本信息：分组、API 名称、API 类型、API 认证方式、描述。
2. API 请求：协议、Method、Path、入参。
3. API 服务：后端服务协议、后端服务 Method、后端服务地址、后端服务 Path、服务超时时间、参数映射、系统参数、常量参数。
4. API 返回结果：返回类型及示例，目前网关对于返回结果不做处理，直接透传给请求者。后续会支持用户定制化、格式化的定义返回信息。

至此完成 API 的创建，并且具备开放的条件。操作详细说明请看 使用手册（开放API）。

四、发布api

完成 API 创建后，需要进行调试、测试和正式上线 API。

操作步骤：

1.调试

您要把 API 发布到测试环境，然后在 API 网关控制台的调试页面上调试 API。

调试时，会跳过 APP 鉴权 和 签名校验 环节，只是调试 API 的请求链路是否正确。

如果您勾选了 Mock，就是把返回结果定义为一个常量，然后调试时不会真的去请求后端服务，而会直接返回常量结果。这种 Mock 调试模式，不要求后端服务完备。

如果未勾选 Mock，则网关会真实地请求后端服务。返回信息里可能有网关的 X-Ca 开头的返回信息，也会有底层服务真实返回的信息。

2.测试

为了模拟真实的用户请求，您可以自己创建一个 APP，操作您的 API 给这个 APP 授权。

然后按照真实的请求场景，写代码或者基于网关提供的 SDK 样例 请求 API。

您可以将 API 发布到测试或者线上环境，在绑定独立域名之前，可以直接访问二级域名来进行测试调用。请求时注意指定环境，若不指定则默认为访问线上。参见 API 调用示例。

调用API的方法，请您查看 使用手册（调用 API）。

3.发布

完成测试后，您就可以把 API 开放出去了。

要上架到 API 市场则必须将 API 发布到线上，且 API 的类型应为公开。

对外开放的 API，应在所属分组上绑定独立域名，直接访问二级域名有流控限制为1000次/天。

API 网关支持对测试/线上的 API 做版本管理，您可以发布 API、下线 API 还可以切换版本，切换版本是实时生效。

五、授权给应用

应用（APP）代表请求者的身份。当您的客户或者您自己测试调用 API 时，都需要创建 APP 作为请求者的身份，然后由您操作给 APP 授权。

• 如果您的 API 已经上架云市场，购买者能够给自己的 APP 授权，不需要您再配置。

• 无购买行为时的授权操作需要以下几个步骤：

  1. 获知待授权的 APP 的 AppID 或者 APP 所有者的阿里云邮箱账号。
  2. 在授权操作页面，选择一个或者多个准备开放调用权限的 API，选定 测试/线上。
  3. 选定 API 后，用 AppID 或者阿里云邮箱账号搜索到 APP。
  4. 确认授权。

注意：授权是区分环境的，同一个API、同一个APP，在两个环境需要分别授权，避免因为授权的环境和请求的环境不一致，导致报错。

六、安全服务

接下来您可以配置安全防护设置。目前 API 网关为您提供后端服务签名密钥和流量控制策略两种安全措施。

• 后端服务签名密钥主要是用于您后端验证网关的身份，在网关请求您后端时，保障您后端的安全。

  签名密钥的 Key 和 Secret 都是您自定义的，您将创建的密钥绑定到 API 上后，相当于网关请求这个 API 时需要出示这一对 Key 和 Secret，您后端通过验证签名字符串来验证网关的身份。具体后端签名密钥的说明请参见 后端签名密钥说明文档。

• 流量控制策略用于您管控 API 服务的流量，详见 流量控制策略。

• 您还可以在控制台进行更多 API 生命周期的管理操作，如 API 下线、API 版本切换、API调 用情况监控和预警等。更多详情请您查看 使用手册（开放API）。

七、附录

1、后端签名秘钥说明文档

概述

• API 网关提供后端 HTTP 服务签名验证功能，创建签名密钥并将签名密钥绑定到 API 即可开启后端签名（请妥善保管此密钥，API 网关会对密钥进行加密存储来保障密钥的安全性）。
• 开启后端签名后 API 网关到后端HTTP服务的请求将会添加签名信息，后端 HTTP 服务读取 API 网关的签名字符串，然后对收到的请求进行本地签名计算，比对网关与本地签名结果是否一致。
• 所有您定义的参数都会参与签名，包括您录入的业务参数、您定义的常量系统参数和 API 网关系统参数（如 CaClientIp 等）。
• 后端对 API 网关的签名字符串校验后，如果校验失败，建议返回 errorcode = 403；errormessage = “InvalidSignature”。
• 若您的后端服务为VPC环境，且通过内网对接（专属网络VPC环境开放API），您无需使用后端签名，通道自身是安全的。

读取 API 网关签名方法

网关计算的签名保存在 Request 的 Header 中，Header 名称：X-Ca-Proxy-Signature

后端 HTTP 服务加签方法

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

签名计算方法步骤如下：

组织参与加签的数据

1. String stringToSign=
2. HTTPMethod + "\n" + //Method全大写
3. Content-MD5 + "\n" + //Content-MD5 需要判断是否为空，如果为空则跳过，但是为空也需要添加换行符 "\n"
4. Headers + //Headers 如果为空不需要添加"\n"，不为空的Headers中包含了"\n"，详见下面组织Headers的描述
5. Url

计算签名

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

secret 为绑定到 API 上的签名密钥

补充说明

• Content-MD5

  Content-MD5 是指 Body 的 MD5 值，只有 HttpMethod 为 PUT 或者 POST 且 Body 为非 Form 表单时才计算 MD5，计算方式为：

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

• Headers

  Headers 指所有参与签名计算的 Header的Key、Value。参与签名计算的 Header 的 Key 从 Request Header 中读取，Key为：”X-Ca-Proxy-Signature-Headers”，多个 Key 用英文逗号分割。

• Headers 组织方法：

  先对所有参与签名计算的 Header 的 Key 按照字典排序，然后将 Header 的 Key 转换成小写后按照如下方式拼接：

  String headers = HeaderKey1.toLowerCase() + “:” + HeaderValue1 + “\n”+ HeaderKey2.toLowerCase() + “:” + HeaderValue2 + “\n”+ … HeaderKeyN.toLowerCase() + “:” + HeaderValueN + “\n”

• Url

  Url指 Path+Query+Body 中 Form 参数，组织方法：如果有 Query 或 Form 参数则加 ?，然后对 Query+Form 参数按照字典对 Key 进行排序后按照如下方法拼接，如果没有 Query 或 Form 参数，则 Url = Path

1. String url =
2. Path +
3. "?" +
4. Key1 + "=" + Value1 +
5. "&" + Key2 + "=" + Value2 +
6. ...
7. "&" + KeyN + "=" + ValueN
8. 注意:这里 Query 或 Form 参数的 Value 可能有多个，多个的时候只取第一个 Value 参与签名计算

• 调试模式

  为了方便后端签名接入与调试，可以开启 Debug 模式进行调试，具体方法如下：

  1. 请求API网关的 Header 中添加 X-Ca-Request-Mode = debug

  2. 后端服务在 Header 中读取 X-Ca-Proxy-Signature-String-To-Sign 即可，因为 HTTP Header 中值不允许有换行符，因此换行符被替换成了 “|”。

     注意：X-Ca-Proxy-Signature-String-To-Sign 不参与后端签名计算。

• 时间戳校验

  如果后端需要对请求进行时间戳校验，可以在 API 定义中选择系统参数 “CaRequestHandleTime” ，值为网关收到请求的格林威治时间。

2、流量控制策略

流量控制策略和 API 分别是独立管理的，操作两者绑定后，流控策略才会对已绑定的 API 起作用。

在已有的流量控制策略上，可以额外配置特殊用户和特殊应用（APP），这些特例也是针对当前策略已绑定的API生效。

流量控制策略可以配置对 API、用户、应用三个对象的流控值，流控的单位可以是分钟、小时、天。使用流量控制策略您需要了解以下几点：

• 流量控制策略可以涵盖下表中的维度：

  API 流量限制	该策略绑定的API在单位时间内被调用的次数不能超过设定值，单位时间可选分钟、小时、天，如5000次/分钟。
  APP 流量限制	每个APP对该策略绑定的任何一个API在单位时间内的调用次数不能超过设定值。如50000次/小时。
  用户流量限制	每个阿里云账号对该策略绑定的任何一个 API 在单位时间内的调用次数不能超过设定值。一个阿里云账号可能有多个 APP，所以对阿里云账号的流量限制就是对该账号下所有 APP 的流量总和的限制。如 50 万次/天。

  此外，您可以在流控策略下添加特殊应用（APP）和特殊用户。对于特例，流控策略基础的 API 流量限制 依然有效，您需要额外设定一个阈值作为该 APP 或者该用户的流量限制值，该值不能超过策略的 API流量限制 值，同时流控策略基础的 APP流量限制 和 用户流量限制 对该 APP 或用户失效。

• 与签名密钥相似，当您创建流量控制策略时，需要选择 Region，Region 一旦选定不可更改，且仅能被应用于同一个 Region 下的 API。

• 由于 API 网关限制，当您设置 API 流量限制 值时，考虑每个 API 分组的默认流控上限是500QPS（该值可以通过提交工单申请提高）。

• 绑定 API。您可以将策略绑定于多个 API，流控策略的限制值和特例将对该策略绑定的每一个 API 单独生效。当您绑定 API 时，如果该 API 已经与某个策略绑定，您的此次操作将替换之前的策略，实时生效。

• 特殊对象。如果您想要添加特殊应用或者特殊用户，您需要获得应用 ID 即 AppID 或者用户的阿里云邮箱账号。

• 在 API 网关控制台，您可以完成对流量控制策略的创建、修改、删除、查看等基本操作。还有流控策略与 API 的绑定解绑，流量控制策略特殊对象的添加删除等操作。