3.2 API 管理
3.2.1 创建 API
操作场景
API提供者把API接口配置在API网关中，开放后端能力。
创建API主要分为四个步骤：设置基本信息、定义API请求、定义后端服务和定义返回 结果。
说明
API网关服务基于REST的API架构，API的开放和调用需要遵循RESTful相关规范。
前提条件
● 已创建API分组。如果未创建API分组，可在本操作页面中创建API分组。
● 如果后端服务需要使用VPC通道，请先创建VPC通道，或在本操作页面中创建VPC 通道。
设置基本信息
步骤2 在管理控制台左上角单击 ，选择区域。
步骤3 单击管理控制台左上角 ，然后单击“API网关 APIG”。
步骤4 在左侧选择您的API版本，单击并进入到对应版本的API开发与调用管理页面。
● “共享版”指直接创建并管理API，如涉及到费用，以API调用次数计费。
● “专享版”指在API专享版实例中创建并管理API，如涉及到费用，按实例运行时 间计费。
步骤5 单击“开放API > API管理”，进入到API列表信息页面。
步骤6 单击“新建API”，进入“新建API”页面。填写如表3-4所示信息。
图3-2 基本信息
表3-4 基本信息
信息项 描述
API名称 API名称，根据规划自定义。建议您按照一定的命名规则填写API名 称，方便您快速识别和查找。
所属分组 API所属分组。
如果尚未创建API分组，单击“新建分组”，为API新创建一个分 组。
网关响应 网关响应指API网关未能成功处理API请求，从而产生的错误响应。
API网关提供默认的网关响应（default）。如果您需要自定义响应 状态码或网关响应内容，可在API分组管理中新增网关响应，按照 您自己的响应内容，符合JSON格式即可。
信息项 描述
类型 API类型：
● 公开：选择“公开”类型时，API支持上架。
● 私有：选择“私有”类型时，当该API所在分组上架时，该API 不会上架。
安全认证 API认证方式：
● APP认证：表示由API网关服务负责接口请求的安全认证。
● 华为IAM认证：表示借助IAM服务进行安全认证。
● 自定义认证：用户有自己的认证系统或服务（如使用OAuth认 证），可选择“自定义认证”。
● 无认证：表示不需要认证。
各种认证方式下的API调用稍有不同，具体请参考《开发指南》。
推荐使用APP认证方式。
须知
● 认证方式为华为IAM认证时，任何API网关租户均可以访问此API，可能 存在恶意刷流量，导致过量计费的风险。
● 认证方式为无认证时，任何公网用户均可以访问此API，可能存在恶意刷 流量，导致过量计费的风险。
● 认证方式为自定义认证时，需要在函数工作流服务中写一段函数，对接 用户自己的认证系统或服务。如果当前Region没有上线函数工作流服 务，则不支持自定义认证。
支持简易认证 仅当“安全认证”选择“APP认证”时可配置。
简易认证指APP认证方式下调用API时，在HTTP请求头部消息增加 一个参数X-Apig-AppCode，而不需要对请求内容签名，API网关也 仅校验AppCode，不校验请求签名，从而实现快速响应。
注意仅支持HTTPS方式调用，不支持HTTP方式。具体使用请参考 为简易认证添加AppCode。
说明如果首次创建API未开启简易认证，那么之后开启简易认证，需要重新发布 API。请参考发布API发布。
自定义认证 “安全认证”选择“自定义认证”时需要配置。
自定义认证需要提前创建，可单击右侧的“新建自定义认证”链接 创建。
标签 标签主要用于对API添加分类属性，方便在创建了大量API后，快速 过滤和查找。
描述 API的描述。
步骤7 单击“下一步”，进入“定义API请求”页面。
----结束
定义 API 请求
步骤1 在“定义API请求”页面，填写如表3-5所示信息。
图3-3 定义 API 请求
表3-5 定义 API 请求
信息项 描述
域名 系统默认分配的一个子域名。
请求协议 分为三种类型：
● HTTP
● HTTPS
● HTTP&HTTPS
传输重要或敏感数据时推荐使用HTTPS。
请求Path 接口请求的路径。
格式如：/users/{userId}/projects
● {}中的变量为请求参数，表示匹配"/"之间的一整段，不支持匹 配"/"之间的一部分，例如/abc{userId}。若匹配模式为绝对匹 配，则尾部的请求参数可以添加+号，例如/users/{p+}，其中变 量p匹配1或多段"/"之间的部分。
● 请求Path中包含请求参数时，必须设置对应的入参定义。
● 内容区分大小写。
信息项 描述
匹配模式 分为两种模式：
● 绝对匹配：调用的请求Path固定为创建时填写的API请求Path。
● 前缀匹配：调用的请求Path将以创建时填写的API请求Path为前 缀，支持接口定义多个不同Path。
例如，请求路径为/test/AA，使用前缀匹配时，通过/
test/AA/CC可以访问，但是通过/test/AACC无法访问。
说明
使用前缀匹配时，匹配剩余的路径将透传到后端。
例如，使用前缀匹配，前端请求路径定义为/test/，后端请求路径定义为/
test2/，通过/test/AA/CC访问API，则后端收到的请求url为/test2/AA/CC。
Method 接口调用方式：GET、POST、DELETE、PUT、PATCH、HEAD、
OPTIONS、ANY
● 其中ANY表示该API支持任意请求方法。
● 当“Method”为“POST”/“PUT”/“PATCH”/“ANY”
时，您可以在“请求体内容描述”中增加对于请求体的描述信 息。
支持CORS 是否开启跨域访问CORS（cross-origin resource sharing）。
CORS允许浏览器向跨域服务器，发出XMLHttpRequest请求，从 而克服了AJAX只能同源使用的限制。
CORS请求分为两类：
● 简单请求：头信息之中，增加一个Origin字段。
● 非简单请求：在正式通信之前，增加一次HTTP查询请求。
开启CORS（非简单请求）时，您需要单独创建一个“Method”为
“OPTIONS”的API，具体步骤请参见开启跨域访问。
步骤2 （可选）设置入参定义。
入参定义是指您调用API时，需要传入的参数的说明。
1. 单击“添加入参定义”，弹出“添加入参定义”对话框。
2. 输入如表3-6所示信息。
表3-6 入参定义
信息项 描述
参数名 参数的名称，如果参数在“PATH”位置，那么参数名称需要和
“请求Path”中的名称相同。
说明
– 参数名不能是x-apig- 、x-sdk-开头，不区分大小写。
– 参数名不能是x-stage，不区分大小写。
– 参数位置为HEADER时，参数名不能是“Authorization”和“X-Auth-Token”，不区分大小写，也不支持下划线。
信息项 描述
参数位置 选择参数在请求中的位置。参数位置有如下三种：PATH、
HEADER、QUERY。
说明当您定义了PATH中的参数时，该参数需要在“请求Path”中同步定
义。
类型 字段的类型，包含String和Number。
说明入参如果为boolean，请选择String。
必填 请求API时，此参数是否为必填。如果选择“是”，API网关将 校验请求中是否包含此参数，如果不包含，则拒绝该请求。
透传 请求参数是否透传到后端服务。
默认值 “必填”为“否”时，默认值生效。请求中不包含此参数时，
API网关自动增加默认值发送给后端服务。
枚举 请求参数的枚举值，请求参数的值只能从枚举值中选择，多个 枚举值间用英文逗号隔开。
最小长度 参数值的最小长度，仅允许输入数字。
最大长度 参数值的最大长度，仅允许输入数字。
示例 参数值的填写示例。
描述 对于此参数的描述。
3. 单击“确定”，完成入参定义的设置。
步骤3 单击“下一步”，进入“定义后端服务”页面。
----结束
定义后端服务
API网关支持定义多个策略后端，即满足一定条件后转发给指定的API后端服务，用以 满足不同的调用场景。例如为了区分普通调用与特殊调用，可以定义一个“策略后 端”，通过调用方的源IP地址，为特殊调用方分配专用的后端服务。
除了定义一个默认的API后端服务，一个API共可以定义5个策略后端。
步骤1 定义默认后端。
添加策略后端前必须定义一个默认后端，当不满足任何一个策略后端的API请求，都将 转发到默认的API后端。
在“定义后端服务”页面，选择API后端服务类型。
后端服务类型参数描述见表3-7、表3-8、表3-9。
表3-7 HTTP/HTTPS 类型定义后端服务 服务参数 参数说明
协议 HTTP或HTTPS，定义的后端服务协议须与用户的后端业务协议保 持一致。
说明
● 支持WebSocket通信。
● 传输重要或敏感数据时推荐使用HTTPS。
请求方式 接口调用方式，包括GET、POST、DELETE、PUT、PATCH、
HEAD、OPTIONS、ANY。
其中ANY表示该API支持任意请求方法。
使用VPC通道 是否使用VPC通道访问后端服务。
● 若使用VPC通道，选择已创建的VPC通道名称。
说明
– VPC通道中，云服务器的安全组必须允许100.125.0.0/16网段访问，
否则将导致健康检查失败及业务不通。
● 若不使用VPC通道，需要设置后端服务地址。
格式：“主机:端口”，主机为IP地址/域名，未指定端口时，
HTTP协议默认使用80端口，HTTPS协议默认使用443端口。
端口范围：1 ~ 65535。
如果需要创建变量标识，则填写“#变量名#”，如
#ipaddress#。支持创建多个变量标识，如
#ipaddress##test#。
自定义host头 域（可选）
仅当“使用VPC通道”选择“使用”时可配置。
在请求被发送到VPC通道中主机前，允许您自定义请求的Host头 域，默认将使用请求中原始的Host头域。
后端请求Path 后端服务的路径，即服务的uri，可以包含路径参数，以{路径参数}
形式表示，比如/getUserInfo/{userId}。
如果请求路径中含有环境变量，则使用#变量名#的方式将环境变 量定义到请求路径中，如/#path#。支持创建多个环境变量，如/
#path##request#。
后端超时 后端服务请求的超时时间。
如果在API调试过程中，遇到后端响应超时之类的错误，请适当调 大后端超时时间，以便排查原因。
说明
专享版可以在实例配置参数中修改超时时间上限，可修改范围为 1-600000ms。
双向认证 指HTTPS的双向认证，开启后，API网关将认证API后端服务。双向 认证所需的证书配置说明，请参考配置参数。
说明
仅专享版实例支持双向认证功能。
仅部分region支持双向认证功能。
服务参数 参数说明
后端认证 当您的后端服务需要对API调用增加自己的认证，则需要开启后端 认证。
后端认证需要先添加一个自定义认证，自定义认证通过函数工作流 服务实现，在函数工作流服务中编写一个函数，实现您的认证鉴权
后端认证需要先添加一个自定义认证，自定义认证通过函数工作流 服务实现，在函数工作流服务中编写一个函数，实现您的认证鉴权