创建API-API网关-开放API网关-API管理

操作场景

API提供者把API接口配置在API网关中，开放后端能力。

创建API主要分为四个步骤：设置基本信息、定义API请求、定义后端服务和定义返回结果。

API网关服务基于REST的API架构，API的开放和调用需要遵循RESTful相关规范。
每个用户最多可以创建200个API。

前提条件

已创建API分组。如果未创建API分组，可在本操作页面中创建API分组。
如果后端服务需要使用VPC通道，请先创建VPC通道，或在本操作页面中创建VPC通道。

设置基本信息

步骤 1 登录管理控制台。

步骤 2 单击管理控制台左上角，然后单击“API网关 APIG”。

步骤 3 在左侧导航单击“专享版”，进入专享版实例列表页，单击“查看控制台”，进入API开发与调用管理页面。

步骤 4 单击“开放API > API管理”，进入到API列表信息页面。

步骤 5 单击“新建API”，进入“新建API”页面。填写如表5-4所示信息。

表5-4基本信息

信息项	描述
API名称	API名称，根据规划自定义。建议您按照一定的命名规则填写API名称，方便您快速识别和查找。
所属分组	API所属分组。如果尚未创建API分组，单击“新建分组”，为API新创建一个分组。
网关响应	网关响应指API网关未能成功处理API请求，从而产生的错误响应。 API网关提供默认的网关响应（default）。如果您需要自定义响应状态码或网关响应内容，可在API分组管理中新增网关响应，按照您自己的响应内容，符合JSON格式即可。
类型	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发布。
自定义认证	仅当“安全认证”选择“APP认证”或“IAM认证”且“支持双重认证”开启时，或者“安全认证”选择“自定义认证”时需要配置。自定义认证需要提前创建，可单击右侧的“新建自定义认证”链接创建。
标签	标签主要用于对API添加分类属性，方便在创建了大量API后，快速过滤和查找。
描述	API的描述。

步骤 6单击“下一步”，进入“定义API请求”页面。

定义API请求

步骤 1 在“定义API请求”页面，填写如表5-5所示信息。

表5-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.输入如表5-6所示信息。

表5-6入参定义

信息项	描述
参数名	参数的名称，如果参数在“PATH”位置，那么参数名称需要和“请求Path”中的名称相同。说明 l 参数名不能是x-apig- 、x-sdk-开头，不区分大小写。 l 参数名不能是x-stage，不区分大小写。 l 参数位置为HEADER时，参数名不能是“Authorization”和“X-Auth-Token”，不区分大小写，也不支持下划线。
参数位置	选择参数在请求中的位置。参数位置有如下三种：PATH、HEADER、QUERY。说明当您定义了PATH中的参数时，该参数需要在“请求Path”中同步定义。
类型	字段的类型，包含String和Number。说明入参如果为boolean，请选择String。
必填	请求API时，此参数是否为必填。如果选择“是”，API网关将校验请求中是否包含此参数，如果不包含，则拒绝该请求。
默认值	“必填”为“否”时，默认值生效。请求中不包含此参数时，API网关自动增加默认值发送给后端服务。
最小长度	参数值的最小长度，仅允许输入数字。
最大长度	参数值的最大长度，仅允许输入数字。
示例	参数值的填写示例。
描述	对于此参数的描述。

3.单击“确定”，完成入参定义的设置。

步骤 3 单击“下一步”，进入“定义后端服务”页面。

定义后端服务

AP方分配专用的后端服务。

除了定义一个默认的API后端服务，一个API共可以定义5个策略后端。

步骤 1 定义默认后端。

添加策略后端前必须定义一个默认后端，当不满足任何一个策略后端的API请求，都将转发到默认的API后端。

在“定义后端服务”页面，选择API后端服务类型。

后端服务类型分HTTP/HTTPS、FunctionGraph和Mock三种，具体参数描述见表5-7、表5-8。

表5-7HTTP/HTTPS类型定义后端服务I网关支持定义多个策略后端，即满足一定条件后转发给指定的API后端服务，用以满足不同的调用场景。例如为了区分普通调用与特殊调用，可以定义一个“策略后端”，通过调用方的源IP地址，为特殊调用

服务参数	参数说明
协议	HTTP或HTTPS，传输重要或敏感数据时推荐使用HTTPS。说明支持WebSocket通信。
请求方式	接口调用方式，包括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。
后端认证	当您的后端服务需要对API调用增加自己的认证，则需要开启后端认证。后端认证需要先添加一个5.8.1 创建自定义认证，自定义认证通过函数工作流服务实现，在函数工作流服务中编写一个函数，实现您的认证鉴权流程，或者使用函数调用您的统一鉴权服务。说明后端认证依赖函数工作流服务，此功能仅在部分区域开放。

表5-8Mock类型定义后端服务

服务参数	参数说明
Mock返回结果	Mock一般用于开发调试验证。在项目初始阶段，后端服务没有搭建好API联调环境，可以使用Mock模式，将预期结果固定返回给API调用方，方便调用方进行项目开发。
后端认证	参考表5-7中的后端认证。

如果“后端请求Path”中设置了环境变量，在API调试页面将无法调试API。
如果“后端请求Path”中设置了环境变量，则必须在待发布环境上配置变量名和变量值，否则变量无法赋值，API将无法正常调用。
环境变量名严格区分大小写。

步骤 2（可选）添加后端策略。

添加多个后端策略后，通过不同的策略条件，请求被转发到不同的后端服务中。

1.单击“添加后端策略”。

2.策略后端增加的参数，具体如下表所示，其他参数说明参见表5-7。

表5-9后端策略参数

信息项	描述
后端策略名称	您自定义的名称，用于识别不同的后端策略。
生效方式	满足任一条件：只要满足策略条件中的任意一项，此后端策略就可以生效。满足全部条件：只有满足所有的策略条件，此后端策略才生效。
策略条件	使后端策略生效的条件，具体如表5-10所示。

表5-10策略条件

信息项	描述
条件来源	源地址：以访问API的请求地址作为策略条件来源。请求入参：以请求入参参数作为策略条件来源。须知选择“请求入参”作为策略条件时，入参需要在API前端请求中配置好，如在Header中添加一个参数。
参数名称	当“条件来源”为“请求入参”时，需要设置。选择已创建的入参参数名称。当“条件来源”为“系统参数”时，需要选择参数名称。 − reqPath：请求URI，如“/a/b/c”。 − reqMethod：请求方法，如“GET”。
参数位置	仅在“条件来源”为“请求入参”时，展示请求入参的参数位置。
条件类型	仅在“条件来源”为“请求入参”和“系统参数”时，需要设置。相等：请求参数值必须为输入值时，条件成立。枚举：请求参数值只需要和枚举值中任何一个值相同，条件成立。匹配：请求参数值只需要和正则表达式中任何一个值相同，条件成立。说明当“条件来源”为“系统参数”并且“参数名称”为“Method”时，“条件类型”仅支持选择相等或枚举。
条件值	“条件类型”为“相等”时，输入一个值。 “条件类型”为“枚举”时，输入多个值，以英文逗号隔开。 “条件类型”为“匹配”时，输入一个范围，例如：[0-5]。 “条件来源”为“源地址”时，输入一个或多个IP地址，以英文逗号隔开。

步骤 3 （可选）配置后端服务参数。

将调用API时传入的参数映射到后端服务对应的位置。

1.在“后端服务参数”右侧单击，通过以下任意一种方法配置后端服务参数。

−单击“导入入参定义”，系统自动添加已创建的所有入参参数。

−单击“添加后端参数映射”，按照需求添加您所需要的后端参数映射。

2.根据后端服务实际的参数名称和参数位置修改映射关系。

a.参数在“PATH”位置，那么参数名称需要和“后端请求Path”中的名称相同。

b.调用API的请求参数名称、位置可以与后端参数名称、位置不同。

参数名不能是x-apig- 、x-sdk-开头，不区分大小写。
参数名不能是x-stage，不区分大小写。
参数位置为HEADER时，参数名不区分大小写，也不支持下划线。

c.如上图，test01和test03在调用API时分别配置于PATH和QUERY位置，后端服务通过映射，将在HEADER位置接收test01和test03的值。test02在调用API时配置于HEADER位置，后端服务通过映射，将在PATH位置以参数名test05来接收test02的值。

例如，test01为abc，test02为def，test03为xyz。

调用API请求：

curl -ik -H 'test02:def' -X GET https://www.example01.com/v1.0/abc?test03=xyz

后端服务请求：

curl -ik -H 'test01:abc' -H 'test03:xyz' -X GET https://www.example02.com/v1.0/def

步骤 4（可选）设置常量参数。

如果后端服务需要接收API调用者不可见的常量，可以通过设置常量参数来实现。API网关在请求后端服务时，将常量参数增加到指定请求位置，并将请求发送给后端服务。

1.在“常量参数”右边单击，显示常量参数列表。

2.单击“添加常量参数”，输入如表5-11所示信息。

表5-11常量参数

信息项	描述
常量参数名	常量参数的名称，如果参数在“PATH”位置，那么参数名称需要和“后端请求Path”中的名称相同。说明参数名不能是x-apig- 、x-sdk-开头，不区分大小写。参数名不能是x-stage，不区分大小写。参数位置为HEADER时，参数名不区分大小写，也不支持下划线。
参数位置	选择参数在请求中的位置。参数位置有如下三种：PATH、QUERY、HEADER
参数值	输入参数的值。
描述	对于此常量参数的描述。

API网关将包含常量参数的请求发送给后端服务前，会对特殊参数值进行百分号编码，请确保后端服务支持百分号编码。例如，参数值[apig]，在百分号编码后变为%5Bapig%5D。
“PATH”位置的参数值会对如下字符进行百分号编码：ASCII码为0到31的字符、?、>、<、/、%、#、"、[、\、]、^、`、{、|、}、空白符、ASCII码为127到255的字符。
“QUERY”位置的参数值会对如下字符进行百分号编码：ASCII码为0到31的字符、>、=、<、+、&、%、#、"、[、\、]、^、`、{、|、}、空白符、ASCII码为127到255的字符。

步骤 5（可选）设置系统参数。

系统参数指API网关服务处理API请求时的系统运行时参数信息，包括网关内置参数、前端认证参数、后端认证参数等，API的后端服务获取到这些信息，可以用于做一些辅助性的访问控制或提供自定义认证能力。

1.在“系统参数”右边单击，显示系统参数列表。

2.单击“添加系统参数”，输入如表5-12所示信息。

表5-12系统参数

信息项	描述
系统参数类型	网关内置参数：API网关支持配置的参数。前端认证参数：前端自定义认证返回结果中的参数。在基本信息中，使用“自定义认证”后，才可以选择此参数类型。后端认证参数：后端自定义认证返回结果中的参数。在定义后端服务中，开启“后端认证”后，才可以选择此参数类型。
系统参数名称	“系统参数类型”为“网关内置参数”时，支持选择如下参数：sourceIp（API调用的源地址）、stage（API调用的环境名称）、apiId（API调用的API ID）、appId（API调用的APP ID）、requestId（当次API调用生成的请求ID）。 “系统参数类型”为“前端认证参数”/“后端认证参数”时，此参数名称必须和自定义认证函数返回结果中的参数名称一致。自定义认证函数的编写以及返回结果参数的获取方法，请参考API网关开发指南。
后端参数名称	将系统参数映射到后端参数中。设置需要映射的后端参数名称。说明参数名不能为x-apig- 、x-sdk-开头，不区分大小写。参数名不能是x-stage，不区分大小写。参数位置为HEADER时，参数名不支持下划线且名称重复时不区分大小写。
后端参数位置	设置需要映射的后端参数位置。
描述	对于此系统参数的描述。

步骤 6 单击“下一步”，进入“返回结果基础定义”页面。

定义返回结果

步骤 1 在“返回结果基础定义”页面，填写如表5-13所示信息。

表5-13定义返回结果

信息项	描述
成功响应示例	成功调用API时，返回的响应信息示例。
失败响应示例	调用API失败时，返回的响应信息示例。

步骤 2 单击“完成”，完成API的创建。

API创建完成后，在API列表页面单击API名称，查看API详细信息。

后续操作

您创建完API后，通过调试API，验证服务是否正常。

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

查看所有产品

API网关

API网关

活动

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

查看所有产品

API网关

API网关