创建API

概述

您可以通过创建API，把已有后端服务封装成标准的RESTful API，并开放给其他用户使用。

前提条件

• 每个API都要归属到某个集成应用下，在创建API前您需要有可用的集成应用，否则请提前创建集成应用。
• 每个API都要归属到某个API分组下，在创建API前您需要有可用的API分组，否则请提前创建API分组。
• 如果需要使用负载通道访问后端服务所在的服务器，请提前创建负载通道。
• 如果需要使用自定义认证方式进行API的安全认证，请提前创建自定义认证。

配置基本信息

1. 登录ROMA Connect控制台，在“实例”页面单击实例上的“查看控制台”，进入实例控制台。
2. 在左侧的导航栏选择“服务集成 APIC > API管理”，在“API列表”页签中单击“创建API”。
3. 在新建API页面配置API的基本信息。

   表1 基本信息配置

   参数	配置说明
   API名称	填写API的名称，根据规划自定义。建议您按照一定的命名规则填写API名称，方便您快速识别和查找。
   集成应用	选择API所属的集成应用。若没有可用的集成应用，可单击右侧的“新建集成应用”，创建一个集成应用。
   所属分组	选择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认证”时可配置。 是否对API的调用进行双重安全认证。若选择启用，则在使用APP认证或IAM认证对API请求进行安全认证时，同时使用自定义的函数API对API请求进行安全认证。
   自定义认证	仅当“安全认证”选择“APP认证”或“IAM认证”且“支持双重认证”开启时，或者“安全认证”选择“自定义认证”时需要配置。 选择已创建的前端类型自定义认证。若没有可用的自定义认证，可单击右侧的“新建自定义认证”，创建一个前端类型的自定义认证。
   标签	添加API的标签信息，用于快速过滤和查找API。
   描述	填写API的描述信息。

4. 完成后单击“下一步”，定义API请求。

定义API请求

1. 定义API的请求信息。

   表2 API请求配置

   参数	配置说明
   请求协议	选择API使用的请求协议，可选择“HTTP”、“HTTPS”和“HTTP&HTTPS”，传输重要或敏感数据时推荐使用HTTPS。
   请求Path	填写API的请求路径，格式如：/getUserInfo/{userId}。请求路径中可包含Path参数，以{参数名}形式表示。 Path参数应匹配"/"之间的一整段，不支持匹配"/"之间的一部分，例如不支持/abc{userId}。若匹配模式为绝对匹配，则尾部的Path参数可以添加+号，例如/users/{p+}，其中变量p匹配1或多段"/"之间的部分。 请求路径中包含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。
   Method	选择API的请求方法。“ANY”表示该API支持任意请求方法。
   支持CORS	是否支持跨域访问API。 浏览器出于安全性考虑，限制从页面脚本内发起的跨域请求，此时页面只能访问同源的资源。而CORS允许浏览器向跨域服务器发送XMLHttpRequest请求，从而实现跨域访问。跨域访问API请参见配置跨域访问API。
   入参定义（可选）	根据实际需要定义API的请求参数。请求路径中包含请求参数时，必须配置对应的入参定义。 在“入参定义”下单击“添加入参定义”，添加API的请求参数。 参数名：请求参数的名称。参数位置为“PATH”时，参数名需要与“请求Path”中的参数名称一致。 参数位置：请求参数在API请求中的位置，可选择“PATH”、“HEADER”和“QUERY”。 类型：选择请求参数的数据类型，可选择“STRING”和“NUMBER”。 必填：在API请求中，请求参数是否必填。 透传：请求参数是否透传到后端服务。 默认值：仅当“必填”为“否”时可配置请求参数的默认值。 枚举：请求参数的枚举值，请求参数的值只能从枚举值中选择，多个枚举值间用英文逗号隔开。 最大长度/最大值：“类型”为“STRING”时，设置参数值的最大字符串长度，“类型”为“NUMBER”时，设置参数值的最大值。 最小长度/最小值：“类型”为“STRING”时，设置参数值的最小字符串长度，“类型”为“NUMBER”时，设置参数值的最小值。 示例：请求参数值的填写示例。 描述：请求参数的描述信息。 说明： 参数名不能以x-apig- 、x-sdk-开头，不能是x-stage，不区分大小写。 参数位置为HEADER时，参数名不能是Authorization和X-Auth-Token，不区分大小写，不支持下划线。
   请求体内容描述	仅当“Method”选择“POST”、“PUT”、“PATCH”或“ANY”时可配置。 填写API请求中请求体的描述信息，用于帮助API调用者理解如何正确封装API请求。

2. 完成后单击“下一步”，定义后端服务。

定义后端服务

1. 配置默认后端的基础定义。

   表3 API后端服务配置

   后端服务类型	参数	配置说明
   HTTP/HTTPS	协议	选择后端服务使用的请求协议，支持WebSocket通信。传输重要或敏感数据时推荐使用HTTPS。
   	请求方式	选择后端服务的请求方法。“ANY”表示该后端服务支持任意请求方法。
   	使用负载通道	是否使用负载通道访问后端服务。若选择“使用”，您需要提前创建负载通道。
   	后端服务地址	仅当“使用负载通道”选择“不使用”时需要配置。 填写后端服务的访问地址，格式为“主机:端口”。主机为后端服务的访问IP或域名，未指定端口时，HTTP协议默认使用80端口，HTTPS协议默认使用443端口。 如果后端服务地址中需要携带环境变量，则使用“#变量名#”的形式将环境变量添加到后端服务地址中，如#ipaddress#。支持添加多个环境变量，如#ipaddress##test#。 如果通过自定义后端的“后端请求地址”调用自定义后端，还需要在系统参数中添加两个网关内置参数： apiId：后端参数名称设置为“x-auth-app”，后端参数位置为“HEADER”。 providerAppId：后端参数名称设置为“x-ld-appid”，后端参数位置为“HEADER”。
   	负载通道	仅当“使用负载通道”选择“使用”时需要配置。 选择访问后端服务所使用的负载通道。
   	自定义host头域	仅当“使用负载通道”选择“使用”时可配置。 自定义后端服务请求中的Host头域。
   	后端请求Path	填写后端服务的请求路径，格式如：/getUserInfo/{userId}。请求路径中可包含Path参数，以{参数名}形式表示。 如果请求路径中需要携带环境变量，则使用“#变量名#”的形式将环境变量添加到请求路径中，如/#path#。支持添加多个环境变量，如/#path##request#。
   	后端超时	后端服务请求的超时时间，默认为5000ms。
   	双向认证	仅当“协议”选择“HTTPS”时可配置。 选择是否在ROMA Connect和后端服务间启用双向认证。若选择启用，则还需要配置用于客户端认证的证书。
   	后端认证	选择是否启用后端认证。若选择启用，则使用自定义的函数API对后端服务请求进行安全认证。
   	自定义认证	仅当“后端认证”选择启用时需要配置。 选择已创建的后端类型自定义认证。若没有可用的自定义认证，可单击右侧的“新建自定义认证”，创建一个后端类型的自定义认证。
   Mock	Mock返回结果	在后端服务还不具备的场景下，可以使用Mock模式，将预期结果固定返回给API调用方，方便调用方进行调试验证。例如，Mock返回结果配置为“Successful Info”，则用户在调用该API时，无论设置什么请求参数，API都固定返回“Successful Info”作为响应结果。Mock模式一般用于API的开发调试阶段。
   	后端认证	选择是否启用后端认证。若选择启用，则使用自定义的函数API对后端服务请求进行安全认证。
   	自定义认证	仅当“后端认证”选择启用时需要配置。 选择已创建的后端类型自定义认证。若没有可用的自定义认证，可单击右侧的“新建自定义认证”，创建一个后端类型的自定义认证。

   

   • 如果“后端请求Path”中设置了环境变量，在API调试页面将无法调试API。
   • 如果“后端请求Path”中设置了环境变量，则必须在待发布环境上配置变量名和变量值，否则变量无法赋值，API将无法正常调用。
   • 环境变量名严格区分大小写。
2. （可选）配置默认后端的后端服务参数，将调用API时传入的请求参数映射到后端服务请求的对应位置。若API请求中未定义请求参数，可直接跳过此步骤。
   1. 在“后端服务参数”下，可通过以下任意一种方法添加后端服务参数。
      • 单击“导入入参定义”，把所有已定义的API请求参数添加到后端服务参数。
      • 单击“添加后端参数映射”，按需逐个添加后端服务参数。
   2. 修改API请求参数和后端服务参数的映射关系。
      • 后端服务参数的名称、位置可以与传入的API请求参数名称、位置不同。
      • 后端参数位置为“PATH”时，后端参数名称需要与“后端请求Path”中的参数名称一致。
      • 后端参数名称不能以x-apig- 、x-sdk-开头，不能是x-stage，不区分大小写。
      • 后端参数位置为“HEADER”时，参数名不支持下划线，不区分大小写。

   以下表的参数和后端请求Path为例进行说明。test01和test03分别在API请求中的PATH和QUERY位置，通过参数映射，后端服务将在HEADER位置接收test01和test03的值。test02在API请求中的HEADER位置，通过参数映射，后端服务将在PATH位置以参数名test05来接收test02的值。

   入参名称	入参位置	后端参数名称	后端参数位置
   test01	PATH	test01	HEADER
   test02	HEADER	test05	PATH
   test03	QUERY	test03	HEADER
   后端请求Path：/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://example.com/v1.0/bbb

3. （可选）配置默认后端的常量参数。如果后端服务需要接收固定的常量信息，可以通过设置常量参数来实现。ROMA Connect向后端服务发送请求时，将常量参数添加到请求的指定位置，然后将请求发送给后端服务。
   在“常量参数”下，单击“添加常量参数”，添加后端服务请求的常量参数。

   表4 常量参数配置

   参数	配置说明
   常量参数名	填写常量参数的名称。“参数位置”为“PATH”时，参数名需要与“后端请求Path”中的参数名称一致。 说明： 参数名不能以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的字符。
4. （可选）配置默认后端的系统参数。如果后端服务需要接收系统运行时产生的参数信息，如网关内置参数、前端认证参数和后端认证参数等，可以通过设置系统参数来实现。ROMA Connect向后端服务发送请求时，将系统参数添加到请求的指定位置，然后将请求发送给后端服务。
   在“系统参数”下，单击“添加系统参数”，添加后端服务请求的系统参数。

   表5 系统参数配置

   参数	配置说明
   系统参数类型	选择系统参数的类型。 网关内置参数：ROMA Connect支持配置的参数。 前端认证参数：前端自定义认证返回结果中的参数。在配置基本信息中，“安全认证”选择“自定义认证”时，才可以选择此参数。 后端认证参数：后端自定义认证返回结果中的参数。在配置默认后端的基础定义中，“后端认证”开启时，才可以选择此参数。
   系统参数名称	填写系统参数的名称。 系统参数类型为“网关内置参数”时，选择系统支持获取的参数。 系统参数类型为“前端认证参数”或“后端认证参数”时，支持自定义参数，但是此参数必须为自定义认证返回结果中的参数。
   后端参数名称	填写系统参数需要映射的后端参数名称。 说明： 参数名不能以x-apig- 、x-sdk-开头，不能是x-stage，不区分大小写。 参数位置为HEADER时，参数名不支持下划线，不区分大小写。
   后端参数位置	选择后端参数在后端服务请求中的位置，可选择“PATH”、“HEADER”和“QUERY”。
   描述	填写系统参数的描述信息。

5. （可选）添加策略后端。您可以根据需要为API添加多个策略后端，通过设置不同的策略条件，API请求被转发到不同的后端服务中。
   1. 单击“添加策略后端”，为API添加一个策略后端。
   2. 配置策略后端的相关信息。

      表6 策略后端配置

      参数	配置说明
      后端策略名称	填写策略后端的名称，用于识别不同的策略后端。
      生效方式	选择策略后端的生效方式。 满足任一条件：只要满足策略条件中的任意一项，API请求就会被转发到该策略后端。 满足全部条件：只有满足所有的策略条件，API请求才会被转发到该策略后端。
      策略条件	添加策略后端的生效条件。 条件来源：策略条件中判断条件的来源。 源地址：表示以发起API请求的源端地址作为判断条件。 请求入参：表示以API请求的请求参数作为判断条件。 参数名称：仅当“条件来源”选择“请求入参”时需要配置，选择已定义的API请求参数。 条件类型：仅当“条件来源”选择“请求入参”时需要配置，选择条件的判断类型。 相等：表示请求参数值为指定设置值时，条件成立。 枚举：表示请求参数值与枚举值中任何一个值相同，条件成立。 匹配：表示请求参数值与正则表达式中任何一个值相同，条件成立。 条件值：填写判断条件的值。 “条件类型”为“相等”时，输入一个值。 “条件类型”为“枚举”时，输入多个值，多个值之间以英文逗号隔开。 “条件类型”为“匹配”时，输入一个正则表达式，例如：[0-5]。 “条件来源”为“源地址”时，输入一个或多个IP地址，多个地址之间以英文逗号隔开。

   例如，有3个“条件来源”为“请求入参”的策略条件，如下表所示。如果请求参数值为11，则满足策略A。如果请求参数值为5，则满足策略B。如果请求参数值为15，则满足策略C。

   表7 策略信息

   策略	条件类型	条件值
   策略A	相等	11
   策略B	枚举	1，2，5，8
   策略C	匹配	[13-20]

6. 完成后单击“下一步”，定义返回结果示例。

定义返回结果示例

1. 配置返回结果的响应示例，用于帮助API调用者了解API请求的响应信息。

   表8 返回结果配置

   参数	配置说明
   成功响应示例	调用API成功时，返回的成功响应结果示例。
   失败响应示例	调用API失败时，返回的失败响应结果示例。

2. 完成后单击“完成”，完成API的创建。