API 网关
最佳实践
文档版本 01
发布日期 2022-01-11
版权所有 © 华为技术有限公司 2022。 保留一切权利。
非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传 播。
商标声明
和其他华为商标均为华为技术有限公司的商标。
本文档提及的其他所有商标或注册商标，由各自的所有人拥有。
注意
您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或 特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声 明或保证。
由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文 档中的所有陈述、信息和建议不构成任何明示或暗示的担保。
目 录
1 使用 API 网关开放云容器引擎的工作负载... 1
2 使用专享版 API 网关开放本地数据中心的服务能力... 10
3 使用函数服务开发自定义认证...14
4 API 网关跨 VPC 开放后端服务...19
5 对接 Web 应用防火墙 WAF...30
最佳实践 目 录
1 使用 API 网关开放云容器引擎的工作负载
简介
本手册基于华为云API网关实践所编写，用于指导您开放并调用API。
云容器引擎（Cloud Container Engine，即CCE）中的工作负载，以及微服务，可通过 API网关将服务能力以API形式对外开放。借助API网关开放容器应用，具有如下优势：
● 无需设置弹性公网IP，节省网络带宽成本
API网关支持建立VPC通道，访问CCE中工作负载的地址。
● 提供多种认证方式，增加访问安全性
● 提供访问流量控制策略，增加后端服务的安全性
与直接访问容器应用相比，API网关提供流量控制，确保后端服务稳定运行。
● 支持多实例负载均衡，合理利用资源，增加系统可靠性 本手册介绍如何通过API网关访问CCE中的工作负载。
图1-1 通过 API 网关访问 CCE 工作负载（由实例组成）
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
图1-2 查询访问端口
图1-3 查询工作负载中实例所属弹性服务器的名称
创建 VPC 通道
步骤1 登录控制台，进入API网关服务。
下述步骤以共享版API网关版本为示例进行介绍。
步骤2 创建VPC通道。
1. 在“创建VPC通道”的“基本信息”界面，单击“创建快速通道”。
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
图1-4 VPC 通道列表界面
2. 输入如下图所示信息，其他参数保持默认值。
如果您想了解参数更详细的信息，请参见《API网关 用户指南》。
图1-5 设置 VPC 通道基本信息
步骤3 添加需要通过API网关访问的CCE工作负载的实例节点。
可添加多个实例，API网关支持负载均衡功能。
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
步骤4 单击“完成”，添加VPC通道。
----结束
开放 API
步骤1 创建分组，输入如图1-6所示信息。
图1-6 创建分组
步骤2 创建API。
如果您想了解参数更详细的信息，请参见《API网关 用户指南》。
1. 单击“新建API”，操作如下图所示。
图1-7 API 列表界面
2. 在“新建API”的“基本信息”界面，输入如下图所示信息。
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
图1-8 设置 API 的基本信息
3. 在“定义API请求”界面，输入如下图所示信息。
4. 在“定义后端服务”界面，输入如下图所示信息。
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
6. 单击“完成”，完成API的创建。
步骤3 调试API。
1. 单击“调试”，操作如下图所示。
图1-9 API 列表界面
2. 调试API，操作如下图所示。
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
图1-10 调试 API，返回 200，表示调用成功
步骤4 发布API。
1. 单击“发布”。
图1-11 API 列表界面
2. 设置发布信息。
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
图1-12 发布 API
----结束
调用 API
步骤1 在API详情界面，复制“API URL”。
1. 进入API详情界面。
图1-13 进入 API 详情界面
2. 在API详情界面，复制“API URL”。
图1-14 复制 API URL
步骤2 打开浏览器，在地址栏粘贴“API URL”的地址。请求API成功时，显示如下界面。
如果想要设置一段时长内API的调用次数，请设置流控策略，具体参见《API网关 用户 指南》。
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
----结束
最佳实践 1 使用 API 网关开放云容器引擎的工作负载
2 使用专享版 API 网关开放本地数据中心的服 务能力
API网关的后端服务有3类部署形态：
● 后端服务部署在虚拟私有云（以下简称VPC）中，仅支持私有地址访问。
可在API网关创建VPC通道，利用VPC通道，打通API网关与虚拟私有云的网络路 由。
● 后端服务部署在公网环境中，即可以直接通过公网地址访问。
● 后端服务部署在本地数据中心，且不能通过公网地址直接访问。
如果您使用专享版API网关，可为本地数据中心搭建一条与API网关（所绑定的华 为云VPC）之间的专线。
本节针对后端服务部署在本地数据中心的场景，介绍使用API网关开放API的注意事 项。
图2-1 使用云专线连通客户本地数据中心与华为云专享版 API 网关
连通云专线与 API 网关
步骤1 创建VPC。
具体请参考《虚拟私有云 VPC》。
专享版API网关需要绑定1个VPC，将本地数据中心与VPC之间建立云专线后，API网关 即可访问本地数据中心的服务。
最佳实践 2 使用专享版 API 网关开放本地数据中心的服务能力
图2-2 创建 VPC 示例参考
说明
● 需要为API网关规划1个子网段。
● 一条云专线只能打通本地数据中心到1个VPC的网络，您在云上的资源，建议都绑定到同一 VPC中，避免不同VPC都需要使用云专线访问本地数据中心带来的成本增加。
● 如果已有VPC，可不用新建。
步骤2 购买专享版API网关。
具体请参考《用户指南》的购买专享版API网关。
最佳实践 2 使用专享版 API 网关开放本地数据中心的服务能力
图2-3 购买 API 网关专享版示例参考
步骤3 购买云专线。
购买一条连接本地数据中心到华为云API网关（所绑定的虚拟私有云）的云专线，请按 以下操作顺序执行：
1. 购买物理连接接入
即购买一条连接本地数据中心与华为云的运营商线路。建议您选择“一站式接 入”，华为云负责施工工程。
如果已有数据中心到华为云的物理连接，可直接使用。
2. 创建虚拟网关
虚拟网关用于关联专享版API网关绑定的VPC。
说明
在选择VPC网段时，需要添加专享版API网关所使用的网段，表示允许专线可访问的VPC子 网。可在专享版API网关控制台查询网段详情。
3. 创建虚拟接口
虚拟接口将物理连接与虚拟网关（配置了VPC和网段）关联绑定，打通物理与专 享版API网关所在VPC的网络。
注意远端网关与远端子网要分别配置您本地数据中心的开放API接口访问的网关和 子网。例如您本地数据中心的API调用地址为http://192.168.0.25:80/{URI}，则远 端网关和远端子网要配置192.168.0.25所在的子网段与网关。
4. 配置本地路由
如果本地数据中心的子网不在以下三个大子网段内，暂时不支持配置本地路由：
10.0.0.0/8-24、172.16.0.0/12-24、192.168.0.0/16-24。
步骤4 验证网络连通。
最佳实践 2 使用专享版 API 网关开放本地数据中心的服务能力
再创建一台按需的ECS，选择与专享版API网关相同的VPC、子网与安全组。只要本地 数据中心能连通ECS，则与专享版API网关也能连通。
----结束
使用专享版 API 网关开放 API
本地数据中心与专享版API网关的网络连通后，您可以正常使用API网关的所有操作。
具体请参考《用户指南》的入门。
注意，API的后端服务地址填写您本地数据中心的API调用地址。
最佳实践 2 使用专享版 API 网关开放本地数据中心的服务能力
3 使用函数服务开发自定义认证
简介
本手册基于华为云API网关实践所编写，用于指导如何为API添加自定义认证。
在API的安全认证方面，API网关提供IAM认证、APP认证等方式，帮助用户快速开放 API，同时API网关也支持用户使用自己的认证方式（以下简称自定义认证），以便更 好地兼容已有业务能力。
API网关支持的自定义认证需要借助函数工作流服务实现，用户在函数工作流中创建自 定义认证函数，API网关调用该函数，实现自定义认证。下面以Basic认证为例，介绍 如何使用函数服务实现自定义认证。
编写自定义认证函数
在函数工作流的控制台编写函数，自定义认证的代码编写指南参见创建用于前端自定 义认证的函数。
在函数工作流页面创建一个函数，语言选Python 3.6，代码如下。
最佳实践 3 使用函数服务开发自定义认证
# -*- coding:utf-8 -*- import json
def handler(event, context):
#以下表示认证信息匹配正确，则返回用户名，
if event["headers"]["authorization"]=='Basic dXNlcjE6cGFzc3dvcmQ=':
return {
'statusCode': 200, 'body': json.dumps({
"status":"allow", "context":{
"user_name":"user1"
} }) } else:
return {
'statusCode': 200, 'body': json.dumps({
"status":"deny", "context":{
"code":"1001",
"message":"incorrect username or password"
最佳实践 3 使用函数服务开发自定义认证
创建自定义认证的 API
创建API，具体步骤请参见创建API。将认证类型修改为自定义认证，并选择上一步创 建的自定义认证。编辑完成之后发布API。
设置错误响应
调用API如果输入错误的认证信息，则返回结果如下：
最佳实践 3 使用函数服务开发自定义认证
{"error_msg":"Incorrect authentication information: frontend authorizer","error_code":"APIG.
0305","request_id":"36e42b3019077c2b720b6fc847733ce9"}
为了让API响应结果为函数中返回的context中的字段，需要修改网关响应模板。在API 所在的分组中，网关响应页签下，编辑自定义认证失败的响应详情，将响应状态码改 为401，将消息模板改为
{"code":"$context.authorizer.frontend.code","message":"$context.authorizer.frontend.message"}
修改之后，调用API传入错误的认证信息，返回状态码为401，返回结果如下：
{"code":"1001","message":"incorrect username or password"}
映射后端参数
如果认证通过，函数返回的context信息，可以传到后端，配置方式如下：
编辑API，在后端服务页面，添加系统参数，参数类型为前端认证参数，系统参数名称 填自定义认证函数中context中的字段，后端参数名称和位置填需要传入到后端请求的 参数名和位置。
最佳实践 3 使用函数服务开发自定义认证
编辑和发布完成之后，使用正确的认证信息调用API，可以看到后端打印了X-User- Name头，值为函数代码中写入到context中的user_name字段的用户名。
最佳实践 3 使用函数服务开发自定义认证
4 API 网关跨 VPC 开放后端服务
用户后端服务器所在的VPC与创建实例所选择的VPC处于不同的场景时，用户如何完成 服务配置，并且实现跨VPC对接？本文以ELB（弹性负载均衡）为例，讲述如何在API 网关上开放内网ELB中的服务。
图4-1 API 网关跨 VPC 开放后端服务
操作流程
1. 创建虚拟私有云
创建两个VPC，VPC1为API网关所在VPC，VPC2为后端应用所在VPC。
最佳实践 4 API 网关跨 VPC 开放后端服务
7. 购买ECS
购买ECS（应用服务器），启动后端服务，并将ECS挂载到已购买的ELB上。
8. 调试API
验证对接内网ELB是否成功。
创建虚拟私有云
步骤1 登录网络控制台。
步骤2 在“虚拟私有云”页面，单击“创建虚拟私有云”，请参考表4-1和表4-2配置信息。
表4-1 配置信息
参数 配置说明
区域 选择所在的区域，此处选择“华北-北京四”。
名称 VPC1（API网关所在VPC）。
企业项目 选择所属的企业项目，此处选择“default”。
可用区 选择子网所属可用区，此处选择“可用区1”。
最佳实践 4 API 网关跨 VPC 开放后端服务
表4-2 VPC 规划
VPC1 APIG实例系统VPC VPC2
10.X 172.31.0.0/16 不能与VPC1和APIG实例系统VPC重复。
172.X 192.168.0.0/16 192.X 172.31.0.0/16
步骤3 单击“立即创建”。
步骤4 重复步骤2~步骤3，创建“VPC2（后端应用所在VPC）”。
----结束
购买 API 网关专享版实例
步骤1 登录API网关控制台。
步骤2 在左侧导航栏选择“专享版”。
步骤3 单击“购买专享版实例”。
最佳实践 4 API 网关跨 VPC 开放后端服务
参数 配置说明
可用区 选择实例所在的可用区，此处选择“可用区1”。
实例名称 填写实例的名称，根据规划自定义。建议您按照一定的命 名规则填写实例名称，方便您快速识别和查找。
实例规格 选择实例的容量规格，实例创建后规格不可修改，此处选 择“专业版”。
时间窗 选择技术支持对实例进行维护的时间段，建议选择业务量 较少的时间段，保持默认设置“22：00：00---02：00：
00”。
企业项目 选择实例所属的企业项目，保持默认设置“default”。
网络 选择已创建的虚拟私有云“VPC1”和子网。
安全组 单击“管理安全组”，创建安全组，企业项目选择
“default”后，即可创建。
描述 填写实例的描述信息。
步骤4 单击“立即购买”。
步骤5 规格确认无误后，勾选用户协议和隐私政策的阅读并同意声明。支付费用后，实例开 始创建，界面显示创建进度。
----结束
购买 ELB
步骤1 登录网络控制台。
步骤2 在左侧导航栏选择“弹性负载均衡 > 负载均衡器”。
步骤3 单击“购买弹性负载均衡”。
步骤4 配置负载均衡信息。
最佳实践 4 API 网关跨 VPC 开放后端服务
表4-4 弹性负载均衡参数
参数 配置说明
实例规格类型 选择实例的规格类型。
计费模式 此处默认“按需计费”。
区域 选择实例所在的区域，此处选择“华北-北京四”。
可用区 选择实例所在的可用区，此处选择“可用区1”。
网络类型 选择网络类型“IPv4私网”。
所属VPC 所属虚拟私有云，选择已创建的虚拟私有云“VPC2”。
子网 选择子网。
最佳实践 4 API 网关跨 VPC 开放后端服务
1. 单击已创建弹性负载均衡的名称，在“监听器”页签中单击“添加监听器”。
2. 配置监听器名称、前端协议及端口，单击“下一步”。
3. 配置后端服务器组名称、后端协议和分配策略类型。
4. 单击“完成”。下图所示为配置后的信息。
图4-2 监听器基本信息
图4-3 后端服务器组
----结束
创建对等连接
步骤1 登录网络控制台。
步骤2 在左侧导航栏选择“对等连接”。
步骤3 单击“创建对等连接”，配置对等连接。
表4-5 对等连接配置
参数 配置说明
名称 填写对等连接的名称，根据规划自定义。建议您按照一定 的命名规则填写实例名称，方便您快速识别和查找。
本端VPC 已创建的虚拟私有云“VPC1”。
帐户 此处默认“当前帐户”。
对端项目 选择已有项目。
对端VPC 已创建的虚拟私有云“VPC2”。
步骤4 单击“确定”。
步骤5 在弹框中单击“查看路由”，进入对等对接详情。
步骤6 在“本端路由”页签中单击“路由表”，添加路由。
1. 在“路由”区域单击“添加路由”。
最佳实践 4 API 网关跨 VPC 开放后端服务
2. 在弹窗中填写路由信息。
– 目的地址：为已购买ELB详情页面，“基本信息”页签中的“服务地址”。
– 下一跳类型：选择“对等连接”。
3. 单击“确定”。
图4-4 本端路由
步骤7 返回对等对接详情，在“对端路由”页签中单击“路由表”，添加路由。
1. 在“路由”区域单击“添加路由”。
2. 在弹窗中填写路由信息。
– 目的地址：为已购买专享版实例概览页面，“基本信息”页签中的“出私网 IP”地址。
– 下一跳类型：选择“对等连接”。
3. 单击“确定”。
图4-5 对端路由
----结束
配置路由
最佳实践 4 API 网关跨 VPC 开放后端服务
步骤5 单击“保存”。
----结束
创建 API
步骤1 登录API网关控制台。
步骤2 在左侧导航栏单击“专享版”。
步骤3 进入已购买的实例。
步骤4 在“新建API”页面，设置API基本信息后，单击“下一步”。
表4-6 设置基本信息
参数 配置说明
API名称 填写API名称，建议您按照一定的命名规则填写，方便您 快速识别和查找。
所属分组 默认“DEFAULT”。
网关响应 API网关未能成功处理API请求，从而产生的错误响应。
默认的网关响应为“default”。
安全认证 选择API认证方式，此处选择“无认证”。
最佳实践 4 API 网关跨 VPC 开放后端服务
步骤5 定义API请求后，单击“下一步”。
表4-7 定义 API 请求
参数 配置说明
请求协议 选择API请求协议，此处选择“HTTPS”。
请求Path 接口请求的路径。
步骤6 定义后端服务后，单击“下一步”。
表4-8 HTTP/HTTPS 类型定义后端服务
服务参数 参数说明
协议 选择协议类型，此处选择“HTTP”。
请求方式 接口调用方式，此处选择“GET”。
使用VPC通道 选择“不使用”VPC通道访问后端服务。
后端服务地址 填写已购买ELB的服务地址。
后端请求Path 后端服务的路径。
步骤7 定义返回结果后，单击“完成”。
----结束
购买 ECS
步骤1 登录云服务器控制台。
步骤2 单击“购买弹性云服务器”。
步骤3 基础配置后，单击“下一步：网络配置”。
最佳实践 4 API 网关跨 VPC 开放后端服务
表4-9 基础配置
参数 配置说明
计费模式 选择“按需计费”。
区域 选择弹性云服务器所属区域。
可用区 选择弹性云服务器所属可用区。
CPU机构 默认“x86计算”。
规格 根据业务规划，选择规格。
镜像 根据业务规划，选择镜像。
步骤4 网络配置后，单击“下一步：高级配置”。
表4-10 网络配置
参数 配置说明
网络 选择已创建的虚拟私有云“VPC2”和子网。
安全组 选择已购买专享版实例中已创建的安全组。
弹性公网IP 选择“暂不购买”。
步骤5 高级配置后，单击“下一步：确认配置”。
最佳实践 4 API 网关跨 VPC 开放后端服务
表4-11 高级配置
参数 配置说明
云服务器名称 填写弹性云服务器名称，建议您按照一定的命名规则填 写，方便您快速识别和查找。
登录凭证 登录云服务器凭证，此处默认“密码”。
用户名 默认“root”。
密码 填写登录云服务器的密码。
确认密码 保证密码正确性。
步骤6 确认配置信息后，选择企业项目，此处选择“default”。
步骤7 勾选协议声明后，单击“立即购买”。
----结束
调试 API
步骤1 在已购买弹性负载均衡中的“后端服务器组”页签中，添加已购买的云服务器。
步骤2 进入弹性云服务器启动服务器。
步骤3 进入已购买专享版实例中的“API管理”页面，在已创建API所在行选择“更多 > 调 试”。
步骤4 填写请求参数，单击“发送请求”。
最佳实践 4 API 网关跨 VPC 开放后端服务
5 对接 Web 应用防火墙 WAF
企业为了保护APIG及后端服务器免受恶意攻击，可在APIG和外部网络之间部署WAF。
图5-1 后端服务器访问原理
方案一（推荐）：WAF 侧注册对外访问域名并配置证书，通过 APIG 实例的分组子 域名访问后端服务
推荐原因：API分组通过域名方式对外提供服务，具备更强的可扩展性。
步骤1 在APIG实例中，新建API分组，并记录子域名，将API添加在新建的分组中。
图5-2 新建 API 分组并记录子域名
图5-3 新建 API
步骤2 在WAF侧添加防护域名时，配置“源站地址”填写为API分组的子域名，并添加证书。
详细操作步骤请参考网站接入WAF（云模式）。
说明
客户从公网客户端访问WAF时，使用的是WAF对外访问域名，WAF转发给APIG时同样使用该对 外访问域名，APIG收到访问该域名的请求无次数限制。
最佳实践 5 对接 Web 应用防火墙 WAF
步骤3 在APIG实例中，为API分组绑定已创建的防护域名。
步骤4 在APIG实例中，将“real_ip_from_xff”开关打开，并设置参数运行值为“1”。
说明
客户从公网客户端访问WAF时，WAF会在HTTP头部“X-Forwarded-For”中记录用户的真实 IP，APIG需要据此解析出用户的真实IP。
最佳实践 5 对接 Web 应用防火墙 WAF
方案二（备选）：使用 DEFAULT 分组实现转发功能，WAF 侧通过 IP 访问后端服务
步骤1 在APIG实例中，查看入口地址。通过IP调用访问APIG实例，无访问次数限制。
● 虚拟私有云访问地址为VPC内网地址。
● 弹性IP地址为公网地址。
步骤2 在DEFAULT分组中添加API。
步骤3 在WAF侧添加防护域名时，配置“源站地址”为API网关实例的入口地址，并添加证 书，以及复制WAF回源IP段。详细操作步骤请参考网站接入WAF（云模式）。
说明
● 如果WAF与APIG在同一VPC下，“源站地址”可以填写私网地址。
● 如果APIG绑定弹性IP，“源站地址”可以填写公网地址。
步骤4 在APIG实例中，为DEFAULT分组绑定已创建的防护域名。
最佳实践 5 对接 Web 应用防火墙 WAF
步骤5 在APIG实例中，将“real_ip_from_xff”开关打开，并设置参数运行值为“1”。
说明
客户从公网客户端访问WAF时，WAF会在HTTP头部“X-Forwarded-For”中记录用户的真实 IP，APIG需要据此解析出用户的真实IP。
----结束
最佳实践 5 对接 Web 应用防火墙 WAF
