创建API
您可以通过创建API,把已有后端服务封装成标准的RESTful API,并开放给其他用户使用。
前提条件
- 每个API都要归属到某个集成应用下,在创建API前您需要有可用的集成应用,否则请提前创建集成应用。
- 每个API都要归属到某个API分组下,在创建API前您需要有可用的API分组,否则请提前创建API分组。
- 如果需要使用负载通道访问后端服务所在的服务器,请提前创建负载通道。
- 如果需要使用自定义认证方式进行API的安全认证,请提前创建前端自定义认证。
- 在创建API前,请确保ROMA Connect实例与您的后端服务所在网络互通。
- 若ROMA Connect实例跨VPC内网访问后端服务时,需要完成实例到后端服务所在子网的路由配置。
- 使用FunctionGraph作为API的后端服务时,用户需要具备FunctionGraph Administrator角色权限。
- 在同一实例内,无法创建两个所属分组、请求方法、请求路径和匹配模式都一样的API。
定义API请求
- 登录ROMA Connect控制台,在“实例”页面单击实例上的“查看控制台”,进入实例控制台。
- 在左侧的导航栏选择“服务集成 APIC > API列表”,在页面右上角单击“创建API”。
- 在创建API页面配置API的前端请求信息。
表1 前端请求配置 参数
说明
API名称
填写API的名称,根据规划自定义。建议您按照一定的命名规则填写API名称,方便您快速识别和查找。
集成应用
选择API所属的集成应用。若没有可用的集成应用,可单击右侧的“新建集成应用”,创建一个集成应用。
所属分组
选择API所属的API分组,仅可选择归属所选集成应用下的分组和全局类型分组。若没有可用的API分组,可单击右侧的“新建分组”,创建一个API分组。
说明:创建API后,将无法修改API所属的API分组,API分组关系到API的访问域名,请谨慎选择。
URL
配置API的URL。
- 请求方法:选择API的请求方法。“ANY”表示该API支持任意请求方法。
- 请求协议:选择API使用的请求协议,可选择“HTTP”、“HTTPS”和“HTTP&HTTPS”,传输重要或敏感数据时推荐使用HTTPS。
- 路径:填写API的请求路径,格式如:/getUserInfo/{userId}。请求路径中可包含Path参数,以{参数名}形式表示。
- Path参数应匹配"/"之间的一整段,不支持匹配"/"之间的一部分,例如不支持/abc{userId}。若匹配模式为绝对匹配,则尾部的Path参数可以添加+号,例如/users/{p+},其中变量p匹配一或多段"/"之间的部分。
- 请求路径中包含Path参数时,必须配置对应的入参定义。
- 请求路径中的内容区分大小写。
匹配模式
选择API请求路径的匹配模式。
- 绝对匹配:API请求中的请求路径要与“请求Path”的配置一致。
- 前缀匹配:API请求中的请求路径要以“请求Path”的配置为前缀。例如,“请求Path”为“/test/AA”,使用前缀匹配时,通过/test/AA/BB和/test/AA/CC都可以访问API,但是通过/test/AACC无法访问。
说明:使用前缀匹配时,匹配剩余的请求路径将透传到后端服务。例如,“请求Path”为“/test”,“后端请求Path”为“/test2”,使用前缀匹配时,通过/test/AA/CC访问API,后端服务收到的请求路径为/test2/AA/CC。
标签
添加API的标签信息,用于快速过滤和查找API。
描述
填写API的描述信息。
内容格式类型
仅当“请求方法”选择“POST”、“PUT”或“ANY”时可配置。
是否指定API请求的内容格式类型,支持选择“application/json”、“application/xml”、“text/plain”和“multipart/form-data”。
请求体内容描述
仅当“请求方法”选择“POST”、“PUT”、“PATCH”或“ANY”时可配置。
填写API请求中请求体的描述信息,用于帮助API调用者理解如何正确封装API请求。
- 配置API的安全配置信息。
表2 安全配置 参数
说明
类型
选择API的上架类型。
- 公开:表示API可以上架云市场。
- 私有:表示API所在分组上架云市场时,该API不会上架。
安全认证
选择API的安全认证方式,推荐使用APP认证方式。
- APP认证:表示由ROMA Connect对API请求进行安全认证。用户调用API时,使用授权集成应用的Key和Secret进行API请求的安全认证。使用该方式的API适合所有用户调用。
- 华为IAM认证:表示由IAM对API请求进行安全认证。用户调用API时,使用Token或AK/SK进行API请求的安全认证。使用该方式的API仅适合同一云服务平台的用户调用。
- 自定义认证:表示使用自定义的函数API对API请求进行安全认证。使用该方式的API适合所有用户调用。
- 无认证:表示API请求不需要认证。使用该方式的API适合所有用户调用。
支持简易认证
仅当“安全认证”选择“APP认证”时可配置。
是否对API的调用使用简易安全认证,仅当API请求协议为HTTPS时生效。若选择启用,则用户调用API时携带AppCode进行安全认证,无需对API请求进行签名校验。
支持双重认证
仅当“安全认证”选择“APP认证”或“华为IAM认证”时可配置。
是否在使用APP认证或IAM认证对API请求进行安全认证时,同时使用自定义的函数API对API请求进行安全认证。
若选择启用,还需选择已创建的前端类型自定义认证。若没有可用的自定义认证,可单击右侧的“新建自定义认证”,创建一个前端类型的自定义认证。
自定义认证
仅当“安全认证”选择“自定义认证”时需要配置。
选择已创建的前端类型自定义认证。若没有可用的自定义认证,可单击右侧的“新建自定义认证”,创建一个前端类型的自定义认证。
支持跨域CORS
是否支持跨域访问API。
浏览器出于安全性考虑,限制从页面脚本内发起的跨域请求,此时页面只能访问同源的资源。而CORS允许浏览器向跨域服务器发送XMLHttpRequest请求,从而实现跨域访问。跨域访问API请参见配置跨域访问API。
- 配置API的请求参数。
单击“新增请求参数”,根据实际需要定义API的请求参数。可分别添加Query参数、Header参数和cookies参数,若URL中包含Path参数时,还需要配置对应的Path变量。
表3 请求参数 参数
说明
参数名
请求参数的名称。
参数类型
选择请求参数的数据类型,可选择“STRING”和“NUMBER”。
必填
在API请求中,请求参数是否必填。
透传
请求参数是否透传到后端服务。
枚举
请求参数的枚举值,请求参数的值只能从枚举值中选择,多个枚举值间用英文逗号隔开。
默认值
仅当“必填”为“否”时可配置请求参数的默认值。
字节限制
“参数类型”为“STRING”时,设置参数值的最小和最大字符串长度,“参数类型”为“NUMBER”时,设置参数值的最小和最大值。
最小长度/最小值和最大长度/最大值同时设置成0时,表示不做限制。
示例
请求参数值的填写示例。
描述
请求参数的描述信息。
- 参数名不能以x-apig- 、x-sdk-开头,不能是x-stage,不区分大小写。
- 参数位置为HEADER时,安全认证为IAM的认证的API的参数名不能是“X-Auth-Token”和“Authorization”,安全认证为APP的API参数名不能是"Authorization",不区分大小写,且名称重复时不区分大小写。
- 建议不要设置敏感信息,防止泄露。
- 完成后单击“下一步”,定义后端配置。
定义后端配置
- 选择默认后端的“后端服务类型”,可选择“HTTP&HTTPS”、“FunctionGraph”和“Mock”类型。
FunctionGraph依赖于函数工作流服务FunctionGraph,若当前环境中未部署FunctionGraph服务,则后端服务类型FunctionGraph不可用。
- 配置默认后端基础定义,默认后端配置根据选择的“后端服务类型”不同有所差异。
- HTTP&HTTPS类型默认后端
表4 HTTP&HTTPS类型默认后端 参数
说明
负载通道
是否使用负载通道访问后端服务。若选择“使用”,您需要提前创建负载通道。
URL
配置后端服务的URL。
- 请求方法:选择后端服务的请求方法。“ANY”表示该后端服务支持任意请求方法。
- 请求协议:选择后端服务使用的请求协议,支持WebSocket通信。传输重要或敏感数据时推荐使用HTTPS。
- 后端服务地址:仅当“负载通道”选择“不使用”时需要配置。填写后端服务的访问地址,格式为“主机:端口”。主机为后端服务的访问IP或域名,未指定端口时,HTTP协议默认使用80端口,HTTPS协议默认使用443端口。
- 如果后端服务地址中需要携带环境变量,则使用“#变量名#”的形式将环境变量添加到后端服务地址中,如#ipaddress#。支持添加多个环境变量,如#ipaddress##test#。
- 如果通过自定义后端的“后端请求地址”调用自定义后端,还需要在系统参数中添加两个网关内置参数:
- apiId:后端参数名称设置为“x-auth-app”,后端参数位置为“HEADER”。
- providerAppId:后端参数名称设置为“x-ld-appid”,后端参数位置为“HEADER”。
- 负载通道:仅当“负载通道”选择“使用”时需要配置。选择访问后端服务所使用的负载通道。
- 路径:填写后端服务的请求路径,格式如:/getUserInfo/{userId}。请求路径中可包含Path参数,以{参数名}形式表示。
如果请求路径中需要携带环境变量,则使用“#变量名#”的形式将环境变量添加到请求路径中,如/#path#。环境变量名严格区分大小写,支持添加多个环境变量,如/#path##request#。
说明:- 如果URL的“路径”中设置了环境变量,在API调试页面将无法调试API。
- 如果URL的“路径”中设置了环境变量,则必须在待发布环境上配置变量名和变量值,否则变量无法赋值,API将无法正常调用。
级联标识
仅当实例配置参数“cascade”已设置为“on”且“负载通道”选择“使用”时可配置。
是否使用级联方式访问后端服务,当使用API级联时需要开启。
自定义host头域
仅当“负载通道”选择“使用”时可配置。
自定义后端服务请求中的Host头域。
后端超时(ms)
后端服务请求的超时时间,默认为5000ms。
重试次数
ROMA Connect调用后端服务失败后的重试次数。
- 值为-1时,表示不开启重试功能,但除POST和PATCH外的其他请求类型会默认重试1次。
- 值为0-10时,表示开启重试功能,并根据设置的值执行重试。
说明:若“使用负载通道”设置为“使用”时,重试次数应小于负载通道中已启用的后端服务器个数。
TLS双向认证
仅当URL中的“请求协议”选择“HTTPS”时可配置。
选择是否在ROMA Connect和后端服务间启用双向认证。若选择启用,则还需要配置用于客户端认证的证书。
后端认证
选择是否使用自定义安全认证。
若选择使用,还需选择已创建的后端类型自定义认证。若没有可用的自定义认证,可单击右侧的“新建自定义认证”,创建一个后端类型的自定义认证。
- FunctionGraph类型默认后端
表5 FunctionGraph类型默认后端 参数
说明
函数URN
函数请求的唯一标识。单击“添加”,添加作为后端服务的FunctionURN。
版本或别名
选择要使用的函数版本或者函数别名。
调用类型
选择函数的调用类型。
- Synchronous:表示同步调用,后端函数服务收到调用请求后立即执行并返回调用结果,客户端发送请求后同步等待,收到后端响应后关闭连接。
- Asynchronous:表示异步调用,后端函数服务收到调用请求后将请求排队,执行成功后返回调用结果,服务端在空闲的情况下会逐个处理排队的请求,客户端不关注请求调用的结果。
后端超时(ms)
后端服务请求的超时时间,默认为5000ms。
后端认证
选择是否使用自定义安全认证。
若选择使用,还需选择已创建的后端类型自定义认证。若没有可用的自定义认证,可单击右侧的“新建自定义认证”,创建一个后端类型的自定义认证。
- Mock类型默认后端
表6 Mock类型默认后端 参数
说明
Mock自定义返回码
选择API响应的HTTP状态码。
Mock返回结果
填写API的响应结果。
例如,Mock返回结果配置为“Successful Info”,则用户在调用该API时,API固定返回“Successful Info”作为响应结果。
后端认证
选择是否使用自定义安全认证。
若选择使用,还需选择已创建的后端类型自定义认证。若没有可用的自定义认证,可单击右侧的“新建自定义认证”,创建一个后端类型的自定义认证。
添加header参数
单击“添加header参数”,可自定义API响应的header参数。
- HTTP&HTTPS类型默认后端
- (可选)配置后端服务参数,将调用API时传入的请求参数映射到后端服务请求的对应位置。若API请求中未定义请求参数,可直接跳过此步骤。
- 在“后端服务参数”下,可通过以下任意一种方法添加后端服务参数。
- 单击“导入入参定义”,把所有已定义的API请求参数添加到后端服务参数。
- 单击“添加后端参数映射”,按需逐个添加后端服务参数。
- 修改API请求参数和后端服务参数的映射关系。
- 后端服务参数的名称、位置可以与传入的API请求参数名称、位置不同。
- 后端参数位置为“PATH”时,后端参数名称需要与后端URL中的参数名称一致。
- 后端参数名称不能以x-apig- 、x-sdk-开头,不能是x-stage,不区分大小写。
- 后端参数位置为“HEADER”时,参数名不区分大小写。
以下表的参数和后端URL路径为例进行说明。test01和test03分别在API请求中的PATH和QUERY位置,通过参数映射,后端服务将在HEADER位置接收test01和test03的值。test02在API请求中的HEADER位置,通过参数映射,后端服务将在PATH位置以参数名test05来接收test02的值。
表7 后端服务参数映射示例 入参名称
入参位置
后端参数名称
后端参数位置
test01
PATH
test01
HEADER
test02
HEADER
test05
PATH
test03
QUERY
test03
HEADER
后端URL路径:/apitest/{test05}
假设test01为aaa,test02为bbb,test03为ccc。
API调用请求:
curl -ik -H 'test02:bbb' -X GET https://example.com/v1.0/aaa?test03=ccc
后端服务请求:
curl -ik -H 'test01:aaa' -H 'test03:ccc' -X GET https://apitest/bbb
- 在“后端服务参数”下,可通过以下任意一种方法添加后端服务参数。
- (可选)配置后端常量参数。如果后端服务需要接收固定的常量信息,可以通过设置常量参数来实现。ROMA Connect向后端服务发送请求时,将常量参数添加到请求的指定位置,然后将请求发送给后端服务。
表8 常量参数配置 参数
说明
常量参数名
填写常量参数的名称。“参数位置”为“PATH”时,参数名需要与后端URL中的参数名称一致。
说明:- 参数名不能以x-apig- 、x-sdk-开头,不能是x-stage,不区分大小写。
- 参数位置为HEADER时,参数名不区分大小写。
参数位置
选择常量参数在后端服务请求中的位置,可选择“PATH”、“HEADER”和“QUERY”。
参数值
填写常量参数的值。
描述
填写常量参数的描述信息。
- ROMA Connect将包含常量参数的请求发送给后端服务前,会对特殊参数值进行百分号编码,请确保后端服务支持百分号编码。例如,参数值[api],在百分号编码后变为%5Bapi%5D。
- 对于PATH位置的参数值,ROMA Connect会对如下字符进行百分号编码:ASCII码为0到31的字符、?、>、<、/、%、#、"、[、\、]、^、`、{、|、}、空白符、ASCII码为127到255的字符。
- 对于QUERY位置的参数值,ROMA Connect会对如下字符进行百分号编码:ASCII码为0到31的字符、>、=、<、+、&、%、#、"、[、\、]、^、`、{、|、}、空白符、ASCII码为127到255的字符。
- (可选)配置后端系统参数。如果后端服务需要接收系统运行时产生的参数信息,如网关内置参数、前端认证参数和后端认证参数等,可以通过设置系统参数来实现。ROMA Connect向后端服务发送请求时,将系统参数添加到请求的指定位置,然后将请求发送给后端服务。
在“系统参数”下,单击“添加系统参数”,添加后端服务请求的系统参数。
表9 系统参数配置 参数
说明
系统参数类型
选择系统参数的类型。
- 网关内置参数:ROMA Connect支持配置的系统参数。
- 前端认证参数:前端自定义认证返回结果中的参数。在定义API请求中,“安全认证”选择“自定义认证”时,才可以选择此参数。
- 后端认证参数:后端自定义认证返回结果中的参数。在配置默认后端基础定义中,“后端认证”开启时,才可以选择此参数。
系统参数名
填写系统参数的名称。
- 系统参数类型为“网关内置参数”时,选择系统支持获取的参数。
- sourceIp:调用API的客户端源地址。
- stage:API所发布的环境名称。
- apiId:API的ID。
- appId:调用API所使用的集成应用的ID。
- requestId:当次调用API所生成的请求ID。
- serverAddr:网关服务器的地址 。
- serverName:网关服务器的名称。
- handleTime:本次调用API的处理时间。
- providerAppId:API所属的集成应用ID。
- apiName:API的名称,需要发布API后才可使用此参数。
- appName:调用API所使用的集成应用的名称。
- 系统参数类型为“前端认证参数”或“后端认证参数”时,支持自定义参数,但是此参数必须为自定义认证返回结果中的参数。
后端参数名称
填写系统参数需要映射的后端参数名称。
说明:- 参数名不能以x-apig- 、x-sdk-开头,不能是x-stage,不区分大小写。
- 参数位置为HEADER时,参数名不区分大小写。
后端参数位置
选择后端参数在后端服务请求中的位置,可选择“PATH”、“HEADER”和“QUERY”。
描述
填写系统参数的描述信息。
- (可选)添加策略后端。您可以根据需要为API添加多个策略后端,通过设置不同的策略条件,API请求被转发到不同的后端服务中。
- 单击“策略后端”旁的“”,为API添加一个策略后端。
- 配置策略后端的相关信息。
策略后端的部分基础定义参数与默认后端一致,可参见配置默认后端基础定义中的参数配置说明,表10中仅提供策略后端特有参数的说明。
表10 策略后端配置 参数
说明
后端策略名称
填写策略后端的名称,用于识别不同的策略后端。
生效方式
选择策略后端的生效方式。
- 满足任一条件:只要满足策略条件中的任意一项,API请求就会被转发到该策略后端。
- 满足全部条件:只有满足所有的策略条件,API请求才会被转发到该策略后端。
策略条件
单击“添加策略条件”,添加策略后端的生效条件。
- 条件来源:策略条件中判断条件的来源。
- 请求入参:以API请求的请求参数作为判断条件,入参需要在API的前端请求中已定义。
- 源地址:以发起API请求的源端地址作为判断条件。
- 系统参数:以系统参数作为策略条件来源。系统参数指API网关处理API请求时的系统运行时参数信息。
- COOKIE:以API请求的Cookie信息作为判断条件。
- 参数名称:仅当“条件来源”选择“请求入参”、“系统参数”、“COOKIE”时需要配置。
- 参数位置:仅在“条件来源”选择“请求入参”时,展示请求入参的参数位置。
- 条件类型:仅当“条件来源”选择“请求入参”、“系统参数”、“COOKIE”时需要配置,选择条件的判断类型。
- 相等:表示请求参数值为指定设置值时,条件成立。
- 枚举:表示请求参数值与枚举值中任何一个值相同,条件成立。
- 匹配:表示请求参数值的部分能匹配正则表达式,条件成立。
说明:当“条件来源”选择“系统参数”且“参数名称”选择“reqMethod”时,“条件类型”仅支持选择相等或枚举。
- 条件值:填写判断条件的值。
- “条件类型”为“相等”时,输入一个值。
- “条件类型”为“枚举”时,输入多个值,多个值之间以英文逗号隔开。
- “条件类型”为“匹配”时,输入一个正则表达式,例如:[0-5]。
- “条件来源”为“源地址”时,输入一个或多个IP地址,多个地址之间以英文逗号隔开。
例如,有3个“条件来源”为“请求入参”的策略条件,如表11所示。如果请求参数值为11,则满足策略A。如果请求参数值为5,则满足策略B。如果请求参数值为15,则满足策略C。
- 配置返回结果的响应示例,用于帮助API调用者了解API请求的响应信息。
表12 返回结果配置 参数
说明
成功响应示例
调用API成功时,返回的成功响应结果示例。
失败响应示例
调用API失败时,返回的失败响应结果示例。
- 单击“完成”,完成API的创建。