创建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适合所有用户调用。
须知：Site实例中创建API不支持选择华为IAM认证。
支持简易认证
仅当“安全认证”选择“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的创建。
