阿里云API网关（2）开放 API 并接入 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网关：https://help.aliyun.com/document_detail/48777.html?spm=5176.doc29464.6.545.8kpfId

类似于web-service，可以包含多个操作。API 网关上，一个API分组下可以有多个 API。

下面以一个 API 配置流程作为例子，假如数据市场开放一个服务。

服务名称：已开放的 API 服务信息查询。

服务描述：您通过调用 API 可以查询已经开放的 API 的列表、详细信息等。

例1：Path 中没有动态参数。

例2：Path 中有动态参数。

后端前端的灵活映射：

前端：您调用 API 时，API 请求从您到网关的部分。

后端：请求到达网关后，网关到实际后端服务的部分。

后端host ≠ 前端域名。

后端path ≠ 前端 path。

客户传入参数的位置和名称 ≠ 实际后端服务接收参数的位置和名称（注意 body 只能前后端都为二进制或者都为 form）。

API 网关可以做全方位的前后都映射。

那么上面这个例子该要怎么配置，基本步骤流程如下（以例 2 为例）:

一、前端配置

步骤 1: 创建分组

步骤 2: 绑定域名

创建分组之后，到分组详情页面获取该分组的二级域名，如上图。

去购买对外独立域名 globalservice.api.com 的网站，将独立域名 CNAME 解析到分组的二级域名上。

解析 CNAME 完成后，回到分组详情页面，点击绑定域名，将 globalservice.api.com 绑定到该分组。

由于后端是 https，所以还需要上传 SSL 证书，不支持上传文件，需要把内容复制进来。

步骤 3: 创建 API_基本信息

基本信息这一步完成的是 API 分组选定、 API 名称设置、API 认证方式和类型的选择，完善 API 描述文案。



如上图所示，进入 API 列表页。

选择跟 API 分组同一个区域。

注意安全认证。

APP：表示客户调用您的 API 时由 API 网关对其 APPkey 和 Secret 做验证，您不需要认证客户的身份。

无认证：表示任何人只要获取了调用方式就可以调用您的 API，且无法区分调用者进行计量。无认证的 API 不建议上架数据市场。

API 类型。

公开：意味着任何人在“发现 API ”页面可以看见该 API，且上架数据市场时，分组内公开类型的 API 才会上架。

私有：意味着任何人不会看见该 API，除非某个 APP 获得了授权。所在分组上架数据市场时，不包括组内私有类型的 API。

步骤4: 创建 API_定义 API 请求

定义 API 请求这一步完成的是第三方使用者调用数据市场上的 API 时的请求样式，即前端。

首先配置协议、Path、Method。如下图：



配置协议。

在前端配置中可以同时支持 HTTP/HTTPS 协议，后端如果要支持 https，需要给独立域名匹配 SSL 证书。

配置请求 path。

Path 就是您调用 API 时，Url 中 .com 后到 ？ 之前的部分，Path 包含动态参数的情况在后续的后端配置步骤中详细说明。

举例说明：

比如您调用的 Url 前部分为：

https://globalservice.api.com/getapilist?command=...[/code] 


那么您的 Path 就是：




/getapilist


由于要示范带有 Body 的 API ，所以此处将 Method 选为 Post。

步骤5： API 网关_入参配置
入参定义是指您调用 API 时，需要传入的参数的说明。

API 网关入参配置是支持混排的，把所有参数在一起配置，然后选择参数的位置是 Header、Query 还是 Body，甚至是在 Path上。仍以上面的初始假设为例，入参配置如下图：



需要注意所有参数的名称会校验是否唯一。

再次注意这一步配置的是您调用 API 时的入参，也就是前端的展现样式。配置这一步中的5个参数需要您把 Url中 在 ? 后面的部分以 keyvalue 形式传入 command 和 region，配置在 Query 上。另外几个参数 key1、key2、group，需要用户在 Body Form 传入，配置在 Body 上。

左侧有快捷键可以快速调整参数顺序，跟定义展示有关。

至此，前端入参就配置完成了，下一步骤配置后端服务定义。

二、后端配置
创建API_定义API后端服务
定义 API 后端服务 这一步完成的是后端服务接收 API 请求的样式定义。即用户按照上一步教程的完成前端配置发送 API 调用到 API 网关，然后 API 网关通过解析您的映射规则，按照您的要求去请求您的后端，保证后端服务最低成本的改造和最高的兼容。

也就是说这一步配置的是网关请求您的后端时，网关的请求样式定义，来符合您后端的既定格式。

步骤1：首先配置后端基础定义，包括后端服务地址、后端请求 Path、后端 Method、超时时间。


后端服务地址，就是您后端服务的http(s)://host:port，也可以是一个域名。这个例子中的后端服务地址就是https://a.b.com:8080。

后端请求 Path，即网关访问后端时用的 Path，是 Url 中后端服务地址后到?前的内容，这里的后端请求Path就是 /region/group。

注意，这里前端的 Path 是/getapilist，可以和后端不一样，而且后端的 Path 中需要有参数传入。这个报错下一部分说明。

后端的 Method 也可以跟前端不一样，这里建议最好一致，这里仍然是 POST。

步骤2:配置后端服务参数，其实主要是映射。


如上图，这一步会把上一步配置的前端入参拉取过来，需要变更的是左侧标红的两列，当然如果前后端一致就不用变化了。

需要注意的是 region、group，这里的前端是配置在 Query 和 Body 里面，而后端从 Path 以接收。上面配置 Path 时报错了，按照图示更改之后，报错就会消失了。

根据后端实际的参数名和接收位置进行调整。图示左侧标红的部分是针对后端需要修改的，右侧不能修改的是既定前端配置。当然如果前端有变化还可以回去上一步修改。

配置完成如下图：



注意 Path 中的参数位置选择 Parameter Path。

常量参数和系统参数 API 的请求者不可见，由网关在请求后端服务时添加上。

常量参数。比如您的后端需要接收一个常量，但是这个常量您不希望被您的客户看见，那么就设置一个常量参数，可以在 Header 或者 Query 里面接收。

系统参数。比如您需要获取客户调用 API 时用的 APP 的 ID 来做日志统计，您在系统参数配置，可以在 Header 或者 Query 里面接收。强烈建议后端接收 CaRequestId 字段，每个请求一个 ID 唯一，便于问题定位和建立全量日志。如下图：



创建 API _定义返回结果
目前返回结果在 API 网关是不做解析的，API 网关直接转发给 API 的请求者。

三、发布上线
完成前后端配置之后，就完成了 API 定义的配置。接下来还需要做调试、测试、线上发布。然后就可以上架云市场了。

步骤 1：调试
在 API 网关控制台，进入 API 的管理，有个调试页面。在该页面可以设定入参来简单调试，调试默认调用的是测试环境的 API，所以需要把 API 发布到测试环境。如下图：



页面可以支持 Mock 或者非 Mock 两种调试。

选择 Mock，需要写定返回结果，Mock 下调试不会真的去调用后端，但是会把访问后端之前的参数、Path 寻址都校验掉。

不选择 Mock 则会真实调用后端服务，右侧会返回真实的请求结果，这个结果可以是 API 网关返回的也可以是您后端返回的，看具体情况。

步骤 2：测试
这里区别于调试的就是需要真实的模拟 API 使用者的场景来调用测试环境的 API。测试环境的 API 可以通过分组的二级域名进行访问，此时可以尚未绑定独立域名。

API 需要发布到测试环境，需要创建 APP 并操作授权后，才能真实模拟 API 调用。

发布 API 到测试环境，发布成功后在 API 列表环境的测试后面显示 运行中。



创建 APP。



查看应用 ID，应用 ID 后面要用于搜索 APP。



授权使该 APP 可以调用该 API，授权要注意区分环境。



更多说明：

至此，您已经能够使用您创建的 APP 的 Key 和 Secret 模拟第三方客户调用了。Key 和 Secret 在控制台应用详情查看。具体调用说明请参见 快速入门（调用 API）。

APP 是 API 使用者调用 API 的身份，每一个 API 的使用者都需要申请 APP。具体调用说明请参见 快速入门（调用 API）。

APP 和 API 之间的鉴权关系通过授权来实现，就是哪个 APP 有调用哪个 API 的权限。授权的完成可以通过 API 开放者主动授权和数据市场完成购买两种方式。具体请参见 快速入门（调用 API）。

步骤 3：线上发布后上架数据市场
您需要准备一个独立域名。该独立域名不能与您后端服务地址相同，但是可以为现有域名的二级、三级甚至更多级的域名。

该域名需要解析到分组的二级域名上。比如您要把某一组 API 上架数据市场，那么就要将独立域名 CNAME 解析到该分组的二级域名上。

该域名需要在阿里云 备案，或者原备案不在阿里云但是完成在阿里云的 备案接入。

在 API 网关控制台，把准备好的域名绑定到分组上。

操作 API 发布到线上环境，然后就可以在数据市场走上架流程了。请参见 数据市场上架引导。

步骤4: 辅助 CheckList
调试、测试调不通，检查服务地址和 Path 配置是否正确。

返回结果不对，API 网关支持您把后端的 a 映射成前端的 b，检查映射是否正确。

调不通，检查绑定的独立域名是否在阿里云备案，或者是否在阿里云接入备案。

调不通，检查绑定的独立域名是否正确 CNAME 解析到相应的二级域名上。

如果 Invalid Url 报错，检查在调试、测试 API 时， API 是否已经发布到测试环境（环境后显示“运行中”才是发布完成）。

如果 Invalid Url 报错，检查上架数据市场时，API 是否已经发布到线上（环境后显示“运行中”才是发布完成）。

在重新更改了定义后，调用发现没生效时，检查是否重新操作了发布。

上架数据市场的 API 不能选择 无认证，不能选择 私有。

参考一下：https://help.aliyun.com/document_detail/29468.html?spm=5176.doc29466.6.543.dS7JPu