阿里云API网关服务-使用手册

1.2.3.4.7.

使用手册（开放API）

提供API API网关（API Gateway），提供高性能、高可用的API托管服务，帮助您对外开放您部署在ECS、容器服务等阿里云产品上的应用，为您提供完整的API发布、管理、维护生命周期管理。您只需简单操作，即可快速、低成本、低风险的开放数据或服务。

在API网关您可以：

管理您的API 您可以对API的整个生命周期进行管理，包括API的创建、测试、发布、下线、版本切换等操作。

便捷转换数据 支持自定义映射规则，您可以配置映射将调用请求转换成后端需要的格式。

预设请求校验 您可以预先设置参数类型、参数值（范围、枚举、正则、Json Schema）校验，由网关帮助您过滤掉非法请求，减少您的后端对非法请求的处理成本。

灵活控制流量 您可以对API、用户、应用设置按分钟、小时、天的调用量控制。您还可以设置特例用户或者应用，对某个用户或应用单独配置流量控制。

轻松安全防护

支持Appkey认证，HMAC（SHA-1,SHA-256）算法签名。

支持SSL/TSL加密，并借助阿里云盾防病毒、防攻击。

全面监控与报警 为您提供可视化API实时监控，包括：调用量、调用方式、响应时间、错误率，并支持历史情况查询，以便统筹分析。您还可以配置预警方式（短信、Email）,订阅预警信息，以便实时掌握API运行情况。

降低开放成本 为您自动生成API文档和SDK（服务端、移动端），降低API开放成本。

创建API 创建API是定义API请求的过程。您需要在创建中定义API的请求调用格式、定义网关抛向后端服务的请求格式、定义返回结果格式、定义参数校验规则等等。

定义请求的基本信息

API基本信息包括API分组、API名称、描述、API类型。

1.

2. 3.

1. 2.

3.

1. 2.

3. 4. 5.API创建时需要选择分组。分组是API的管理单元，创建API之前您需要先创建分组。（API分组的详细说明见下文的"分组及域名"）分组携带Region属性且每个分组有不同的域名，同一个分组下的API的Region和域名都是相同的。分组一旦选定不可更改。

API名称应为该分组下唯一，一旦选定不可更改。

API类型分为公开和私有两种。在公测阶段，两种类型无实际差别。

定义请求的后端服务信息

API后端服务信息包括后端服务类型、后端服务地址和后端超时时间。

后端服务类型。目前仅支持HTTP，其他类型如Sigma、Mock后续会陆续支撑。

后端服务地址。是指API网关调用底层服务时的完整地址，包含域名/IP+Path。可以包含动态参数

，比如动态参数为username，写作[username]，这些动态参数只能从调用者传入的Path中获取

，所以您需要在下一步配置Path时选择性的做映射，并且定义最终Path时不要遗漏这些动态参数。

后端服务地址中不能包含Query参数。

后端超时时间。指API请求到达网关后，由网关去调API后端服务的响应时间，由网关请求后端开始

到网关收到后端返回结果的时间。该值不能超过30秒。

定义API请求格式

API请求格式定义包括协议及方法定义、Path的定义、入参定义、系统参数定义、参数映射、参数校验定义。

协议及方法定义。API调用支持HTTP/HTTPS协议。Method方法可选择PUT、GET、POST、

DELETE、HEAD、MULITIPART。

Path定义。这个Path是指服务对外开放后，调用者调用API网关时的路径，可以与后端服务地址中的Path不同，网关会保存对应关系完成寻址。如果您输入的后端服务地址中存在动态参数，这些动态

参数需要通过Path获取，您可以在定义Path的时候进行参数映射，注意最终的Path地址不要遗漏这

些动态参数。只要保证该Path中的动态参数与后端服务地址中的动态参数相对应即可，其他部分可

以与后端服务地址中的Path不同。

入参定义。您在这部分定义用户调用API时需要传入的参数，分别对请求的Header、Query和

Body进行入参定义。您需要定义用户请求传入的参数名称，参数类型如String、Number、

Boolean、Json等。选择参数是否必填，并给出示例值、默认值及描述。Body参数可以选择透传。

参数校验定义。在定义入参时，您还可以点击"更多"来为该参数设置校验，如枚举值、String的长度

校验、Number的最大最小值校验等等。网关会预先对非法请求进行拦截，减轻您后端服务的负担。

参数映射。如果您想要用户输入的参数名称与您后端实际的参数名称不符，或者您后端实际参数名称不方便直接暴露给用户，那么您只需要在定义参数时选择需要参数映射，既可以为每个参数配置起后端参数映射。

系统参数定义。系统参数对于API的调用者是不可见的。系统参数有两种，一种是网关的系统参数

，具体内容如下表：

1.2.3.1.在创建API时，您需要配置网关给您传送上述哪些系统参数，并且选择参数的位置和后端参数名称。

另一种是您的API后端服务需要的一些自定义系统参数，比如某一个常量参数。您需要配置参数值、

后端参数名称以及参数在请求中的位置。

返回结果定义。即选定返回类型和配置返回示例，目前网关对于返回结果是不做处理的。

注意：您所有录入的参数，包括Path中的动态参数、Headers参数、Query参数、Body参数（非二进制）、常量参数、系统参数，参数名称保证全局唯一。即如果您同时在Headers和Query里各有一个名为"name"的参数，是不允许的。

完成以上定义后，您就完成了API的创建。下一步您可以测试、发布并开放API服务，给您的客户授权，同时还可以为API绑定签名密钥和流量控制等安全配置。

开放API服务

API创建完成后，您就可以开放API服务了。要开放API服务您需要绑定一个在阿里云系统备案成功的独立域名，且该域名要完成CNAME解析。而独立域名是绑定在API分组上面的，所以在这个部分为您详细说明一下开放API服务需要了解的API分组和域名。

API分组

API分组是API的管理单元。您创建API之前，需要先创建分组，然后在某个分组下创建API。分组包含名称、描述、地域（Region）、域名几大属性。

分组的地域（Region）在分组创建时选定不可更改。创建API时，如果选定分组那么Region也一同选定，不可更改。

每个账号API分组个数上限为50个，每个分组API个数上限为200个。

域名。分组创建时，系统会为分组分配一个二级域名，用于测试您的API。如果需要开放API服务

，您需要为分组绑定一个在阿里云系统备案成功的独立域名，且将独立域名CNAME到相应的二级域名上。每个分组最多只能绑定5个独立域名。具体请看下文--域名及证书。

域名及证书

API网关通过域名来定位到一个唯一的API分组，再通过Path+HTTPMethod确定唯一的API。如果要开放API服务，您需要了解二级域名和独立域名。

二级域名是分组创建时系统分配的，唯一且不可更改。您可以通过访问二级域名来调用您测试中的API。二级域名仅用于测试，默认被限制为较小的流量。