665      阿里云

开放API接入API网关__分步详解_API 网关-阿里云

API网关上，创建API之前要创建分组，一个分组下可以有多个API。也就是说一项服务，可以包装成一个分组，一项服务中的多个功能接口分别是这个分组下的多个API。

Part 2： 假设我有一个服务

以一个服务中，一个API的配置为例。假如我要开放一个服务。

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

例1：Path中没有动态参数

例2：Path中有动态参数

后端前端的灵活映射：

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

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

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

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

Part 3： 上面这个例子我怎么配置（例2）

Step1: 创建分组

Step2: 绑定域名

1. 创建分组之后，到分组详情页面获取该分组的二级域名，如图
2. 去购买对外独立域名globalservice.api.com的网站，将独立域名CNAME解析到分组的二级域名上
3. CNAME完成后，回到分组详情页面，点击“绑定域名”，将globalservice.api.com绑定到该分组
4. 我的后端是https，所以我还需要上传SSL证书，不支持上传文件，需要把内容复制进来。

Step3: 创建API_基本信息

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

1. 进入API列表页
2. 选择跟API分组同一个区域
3. 注意安全认证。【阿里云APP】表示客户调用我的API时由API网关对其APPkey和Secret做验证，我不需要认证客户的身份。【无认证】表示任何人只要获取了调用方式就可以调用我的API，且无法区分调用者进行计量。无认证的API不建议上架数据市场。
4. API类型。【公开】意味着任何人在“发现API”页面可以看见该API，且上架数据市场时，分组内公开类型的API才会上架。【私有】意味着任何人不会看见该API，除非我给某个APP授权了。所在分组上架数据市场时，不包括组内私有类型的API。

Step4: 创建API_定义API请求

“定义API请求”这一步完成的是第三方使用者调用我的API时的请求样式，即前端。

首先配置协议、Path、method。如图

1. 我们支持HTTP/HTTPS协议，可以同时支持，后端如果要支持https，需要给独立域名匹配SSL证书。

2. 配置请求path。Path就是客户调用我的API时，Url中.com后到？之前的部分。Path包含动态参数的情况我们到配置后端的时候再说。比如：

   我希望用户调用时的Url前部分为：

   https://globalservice.api.com/getapilist?command=…

   那么我的Path就是：

   /getapilist

3. 由于要示范带有body的API，所以此处将method选为post。

然后我们来配置入参，入参定义是指我的客户调用我的API时，需要传入的参数的说明。

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

1. 需要注意所有参数的名称会校验是否唯一。
2. 我有5个参数，再次注意这一步配置的用户调用时的入参，也就是前端的展现样式。我需要客户的Url在?后面以keyvalue形式传入command和region，配置在Query上。另外几个参数key1、key2、group，需要用户在body form传入，配置在Body上。
3. 左侧有快捷键可以快速调整参数顺序，跟定义展示有关。

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

Step5: 创建API_定义API后端服务

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

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

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

1. 后端服务地址，就是您后端服务的http(s)://host:port，也可以是一个域名。这里，我的后端服务地址就是https://a.b.com:8080。
2. 后端请求Path。即网关访问后端时用的Path，是Url中后端服务地址后到?前的内容，我的后端请求Path就是/[region]/[group]
3. 注意，我前端的Path是/getapilist，可以和后端不一样，而且我后端的Path中需要有参数传入。这个报错下一部分说明。
4. 后端的method也可以跟前端不一样，我们建议最好一致，这里仍然是POST。

然后配置后端服务参数，其实主要是映射

1. 如图，这一步会把上一步配置的前端入参拉取过来，需要变更的是左侧标红的两列，当然如果前后端一致就不用变化了。
2. 需要注意的是region、group我的前端是配置在Query和Body里面，而后端希望从Path以接收。上面配置Path时报错了，按照图示更改之后，报错就会消失了。
3. 我根据我后端实际的参数名和接收位置进行了调整。图示左侧标红的部分是针对后端需要修改的，右侧不能修改的是既定前端配置。当然如果前端有变化还可以回去上一步修改。

配置完成如下图：

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

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

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

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

Step6： 创建API_定义返回结果

目前返回结果在API网关是不做解析的，API网关直接转发给API的请求者。请求示例建议是完整示例，带有适当的注释说明。

Part 4： 配置完定义——上架数据市场

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

Step1：调试

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

1. 页面可以支持Mock或者非Mock两周调试。
2. 选择Mock，需要写定返回结果，Mock下调试不会真的去调用后端，但是会把访问后端之前的参数校验、Path寻址都校验掉。
3. 不选择Mock则会真实调用后端服务，右侧会返回真实的请求结果，这个结果可以是API网关返回的也可以是您后端返回的，看具体情况。

Step2：测试

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

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

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

创建APP

查看AppID，AppID后面要用于搜索APP

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

更多说明：

1. 至此，您已经能够使用您创建的APP的Key和Secret模拟第三方客户调用了。Key和Secret在控制台应用详情查看。具体调用说明请参见《快速入门（调用API）》
2. APP是API使用者调用API的身份，每一个API的使用者都需要申请APP。具体调用说明请参见《快速入门（调用API）》
3. APP和API之间的鉴权关系通过授权来实现，就是哪个APP有调用哪个API的权限。授权的完成可以通过API开放者主动授权和数据市场完成购买两种方式。具体请参见《快速入门（调用API）》

Step3：线上发布后上架数据市场

1. 您需要准备一个独立域名。该独立域名不能与您后端服务地址相同，但是可以为现有域名的二级、三级甚至更多级的域名。
2. 该域名需要解析到分组的二级域名上。比如我要把某一组API上架数据市场，那么就要将独立域名CNAME解析到该分组的二级域名上。
3. 该域名需要在阿里云备案，或者原备案不在阿里云但是完成在阿里云的备案接入。
4. 在API网关控制台，把准备好的域名绑定到分组上。
5. 操作API发布到线上环境，然后就可以在数据市场走上架流程了。请参见《数据市场上架引导》。

Part 4： 辅助CheckList

1. 调试、测试调不通，服务地址和Path配置是否正确？
2. 返回结果不对，API网关支持您把后端的a映射成前端的b，映射是否正确？
3. 调不通，绑定的独立域名是否在阿里云备案，或者是否在阿里云接入备案？
4. 调不通，绑定的独立域名是否正确CNAME解析到相应的二级域名上？
5. 报错Invalid Url，调试、测试API时，API是否已经发布到测试环境？（环境后显示“运行中”才是发布完成）
6. 报错Invalid Url，上架数据市场时API是否已经发布到线上？（环境后显示“运行中”才是发布完成）
7. 重新更改了定义调用发现没生效，是否重新操作了发布？
8. 上架数据市场的API不能选择“无认证”，不能选择“私有”

最后更新：2016-11-24 11:23:49

  上一篇： 邮件推送常见退信代码___使用问题_邮件推送-阿里云

  下一篇： 概述及样例__使用手册（调用API）_API 网关-阿里云