更新时间:2024-10-28 GMT+08:00

创建API

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

前提条件

  • 每个API都要归属到某个集成应用下,在创建API前您需要有可用的集成应用,否则请提前创建集成应用
  • 每个API都要归属到某个API分组下,在创建API前您需要有可用的API分组,否则请提前创建API分组
  • 如果需要使用负载通道访问后端服务所在的服务器,请提前创建负载通道
  • 如果需要使用自定义认证方式进行API的安全认证,请提前创建前端自定义认证
  • 在创建API前,请确保ROMA Connect实例与您的后端服务所在网络互通。
    • 若ROMA Connect实例与后端服务在相同VPC内时,可直接访问后端服务。
    • 若ROMA Connect实例与后端服务在同一区域的不同VPC内时,可通过创建VPC对等连接,将两个VPC的网络打通,实现同一区域跨VPC访问后端服务。具体步骤请参考VPC对等连接说明
    • 若ROMA Connect实例与后端服务在不同区域的不同VPC内时,可通过创建云连接实例并加载需要互通的VPC,将两个VPC的网络打通,实现跨区域跨VPC访问后端服务。具体步骤请参考跨区域VPC互通
    • 若ROMA Connect实例与后端服务通过公网互通,请确保ROMA Connect实例已绑定弹性IP。
  • 若ROMA Connect实例跨VPC内网访问后端服务时,需要完成实例到后端服务所在子网的路由配置
  • 使用FunctionGraph作为API的后端服务时,用户需要具备FunctionGraph Administrator角色权限。
  • 在同一实例内,无法创建两个所属分组、请求方法、请求路径和匹配模式都一样的API。

定义API请求

  1. 登录ROMA Connect控制台,在“实例”页面单击实例上的“查看控制台”,进入实例控制台。
  2. 在左侧的导航栏选择“服务集成 APIC > API列表”,在页面右上角单击“创建API”。
  3. 在创建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请求。

  4. 配置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

  5. 配置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",不区分大小写,且名称重复时不区分大小写。
    • 建议不要设置敏感信息,防止泄露。
  6. 完成后单击“下一步”,定义后端配置

定义后端配置

  1. 选择默认后端的“后端服务类型”,可选择“HTTP&HTTPS”、“FunctionGraph”和“Mock”类型。

    FunctionGraph依赖于函数工作流服务FunctionGraph,若当前环境中未部署FunctionGraph服务,则后端服务类型FunctionGraph不可用。

  2. 配置默认后端基础定义,默认后端配置根据选择的“后端服务类型”不同有所差异。
    • 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参数。

  3. (可选)配置后端服务参数,将调用API时传入的请求参数映射到后端服务请求的对应位置。若API请求中未定义请求参数,可直接跳过此步骤。
    1. 在“后端服务参数”下,可通过以下任意一种方法添加后端服务参数。
      • 单击“导入入参定义”,把所有已定义的API请求参数添加到后端服务参数。
      • 单击“添加后端参数映射”,按需逐个添加后端服务参数。
    2. 修改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
  4. (可选)配置后端常量参数。如果后端服务需要接收固定的常量信息,可以通过设置常量参数来实现。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的字符。
  5. (可选)配置后端系统参数。如果后端服务需要接收系统运行时产生的参数信息,如网关内置参数、前端认证参数和后端认证参数等,可以通过设置系统参数来实现。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”。

    描述

    填写系统参数的描述信息。

  6. (可选)添加策略后端。您可以根据需要为API添加多个策略后端,通过设置不同的策略条件,API请求被转发到不同的后端服务中。
    1. 单击“策略后端”旁的“”,为API添加一个策略后端。
    2. 配置策略后端的相关信息。
      策略后端的部分基础定义参数与默认后端一致,可参见配置默认后端基础定义中的参数配置说明,表10中仅提供策略后端特有参数的说明。
      表10 策略后端配置

      参数

      说明

      后端策略名称

      填写策略后端的名称,用于识别不同的策略后端。

      生效方式

      选择策略后端的生效方式。

      • 满足任一条件:只要满足策略条件中的任意一项,API请求就会被转发到该策略后端。
      • 满足全部条件:只有满足所有的策略条件,API请求才会被转发到该策略后端。

      策略条件

      单击“添加策略条件”,添加策略后端的生效条件。

      • 条件来源:策略条件中判断条件的来源。
        • 请求入参:以API请求的请求参数作为判断条件,入参需要在API的前端请求中已定义。
        • 源地址:以发起API请求的源端地址作为判断条件。
        • 系统参数:以系统参数作为策略条件来源。系统参数指API网关处理API请求时的系统运行时参数信息。
        • COOKIE:以API请求的Cookie信息作为判断条件。
      • 参数名称:仅当“条件来源”选择“请求入参”、“系统参数”、“COOKIE”时需要配置
        • 当“条件来源”为“请求入参”时,选择已定义的API请求参数。
        • 当“条件来源”为“系统参数”时,需要选择系统参数名称。

          - reqPath:请求URL,如“/a/b/c”。

          - reqMethod:请求方法,如“GET”。

        • 当“条件来源”为“COOKIE”时,填写Cookie中的参数名称。
      • 参数位置:仅在“条件来源”选择“请求入参”时,展示请求入参的参数位置。
      • 条件类型:仅当“条件来源”选择“请求入参”、“系统参数”、“COOKIE”时需要配置,选择条件的判断类型。
        • 相等:表示请求参数值为指定设置值时,条件成立。
        • 枚举:表示请求参数值与枚举值中任何一个值相同,条件成立。
        • 匹配:表示请求参数值的部分能匹配正则表达式,条件成立。
        说明:

        当“条件来源”选择“系统参数”且“参数名称”选择“reqMethod”时,“条件类型”仅支持选择相等或枚举。

      • 条件值:填写判断条件的值。
        • “条件类型”为“相等”时,输入一个值。
        • “条件类型”为“枚举”时,输入多个值,多个值之间以英文逗号隔开。
        • “条件类型”为“匹配”时,输入一个正则表达式,例如:[0-5]。
        • “条件来源”为“源地址”时,输入一个或多个IP地址,多个地址之间以英文逗号隔开。

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

    表11 策略信息

    策略

    条件类型

    条件值

    策略A

    相等

    11

    策略B

    枚举

    1,2,5,8

    策略C

    匹配

    [13-20]

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

    参数

    说明

    成功响应示例

    调用API成功时,返回的成功响应结果示例。

    失败响应示例

    调用API失败时,返回的失败响应结果示例。

  8. 单击“完成”,完成API的创建。