更新时间:2022-03-18 GMT+08:00
分享

创建API

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

创建API主要步骤:设置前端定义和安全配置后端配置

前提条件

设置前端定义和安全配置

  1. 登录ROMA API控制台。
  2. 在控制台单击,选择区域,在“ROMA API”下选择待操作的应用。
  3. 在左侧导航栏选择“API管理 > API服务”。
  4. 在当前应用关联的实例中,根据实际业务选择实例。
  5. 单击需要创建API的服务名称,进入服务详情页面。
  6. 在“API运行”页面,单击“创建API”。

    1. 根据下表参数信息,配置前端定义。
      表1 前端定义参数

      信息项

      描述

      API名称

      API名称,根据规划自定义。建议您按照一定的命名规则填写API名称,方便您快速识别和查找。

      URL

      前端地址由请求方法、请求协议、子域名和路径组成。

      • 请求方法:GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS、ANY,其中ANY表示该API支持任意请求方法。
      • 请求协议:HTTP、HTTPS、HTTP&HTTPS,传输重要或敏感数据时推荐使用HTTPS。
      • 子域名:系统默认分配的一个子域名。
      • 路径:接口请求的路径。请求路径可以包含请求参数,请求参数使用{}标识,例如/a/{b},也可以通过配置'+'号做前缀匹配,例如:/a/{b+}。

      网关响应

      网关响应指未能成功处理API请求,从而产生的错误响应。ROMA API提供默认的网关响应(default)。如需创建网关响应,请参考配置网关响应

      匹配模式

      分为两种模式:

      • 绝对匹配:调用的请求Path固定为创建时填写的API请求Path。
      • 前缀匹配:调用的请求Path将以创建时填写的API请求Path为前缀,支持接口定义多个不同Path。

        例如,请求路径为/test/AA,使用前缀匹配时,通过/test/AA/CC可以访问,但是通过/test/AACC无法访问。

      说明:

      使用前缀匹配时,匹配剩余的路径将透传到后端。

      例如,使用前缀匹配,前端请求路径定义为/test/,后端请求路径定义为/test2/,通过/test/AA/CC访问API,则后端收到的请求url为/test2/AA/CC。

      标签

      添加API的标签信息,用于快速过滤和查找API。

      描述

      填写API的描述信息。

    2. 根据下表参数定义,配置安全配置。
      表2 安全配置参数

      信息项

      描述

      安全认证

      API认证方式:

      • APP认证:表示由ROMA API服务负责接口请求的安全认证。
      • 华为IAM认证:表示借助IAM服务进行安全认证。
      • 自定义认证:用户有自己的认证系统或服务(如使用OAuth认证),可选择“自定义认证”。
      • 无认证:表示不需要认证。

      推荐使用APP认证方式。

      须知:
      • 认证方式为华为IAM认证时,任何ROMA API租户均可以访问此API,可能存在恶意刷流量,导致过量计费的风险。
      • 认证方式为无认证时,任何公网用户均可以访问此API,可能存在恶意刷流量,导致过量计费的风险。
      • 认证方式为自定义认证时,需要在函数服务中写一段函数,对接用户自己的认证系统或服务。如果当前Region没有上线函数服务,则不支持自定义认证。

      支持简易认证

      简易认证指APP认证方式下调用API时,在HTTP请求头部消息增加一个参数X-Apig-AppCode,而不需要对请求内容签名,ROMA API也仅校验AppCode,不校验请求签名,从而实现快速响应。

      注意仅支持HTTPS方式调用,不支持HTTP方式。具体使用请参考管理应用

      说明:

      如果首次创建API未开启简易认证,那么之后开启简易认证,需要重新发布API。请参考发布API发布。

      支持双重认证

      仅当“安全认证”选择“APP认证”或“华为IAM认证”时可配置。

      是否对API的调用进行双重安全认证。若选择启用,则在使用APP认证或IAM认证对API请求进行安全认证时,同时使用自定义的函数API对API请求进行安全认证。

      自定义认证

      自定义认证需要提前创建,单击“新建自定义认证”,请参考创建自定义认证

      支持跨域CORS

      CORS允许浏览器向跨域服务器,发出XMLHttpRequest请求,从而克服了AJAX只能同源使用的限制。

      CORS请求分为两类:

      • 简单请求:头信息之中,增加一个Origin字段。
      • 非简单请求:在正式通信之前,增加一次HTTP查询请求。

      开启CORS(非简单请求)时,您需要单独创建一个“Method”为“OPTIONS”的API,具体操作请参考开启跨域访问

    3. (可选)根据实际需要定义API的请求参数。当您定义了Path时,该参数需要在“路径”中同步定义。参数位置包含“Path变量”、“Query参数”和“Headers”,请求参数定义见表3
      图1 配置请求参数
      表3 请求参数

      信息项

      描述

      参数名

      参数的名称,如果参数在“Path”位置,那么参数名称需要和“路径”中的名称相同。

      说明:
      • 参数名不能是x-apig- 、x-sdk-开头,不能是x-stage,不区分大小写。
      • 参数位置为HEADER时,参数名不能是“Authorization”和“X-Auth-Token”,不区分大小写。

      参数类型

      字段的类型,包含STRING和NUMBER。

      必填

      请求API时,此参数是否为必填。如果选择“是”,ROMA API将校验请求中是否包含此参数,如果不包含,则拒绝该请求。

      透传

      请求参数是否透传到后端服务。

      枚举

      请求参数的枚举值,请求参数的值只能从枚举值中选择,多个枚举值间用英文逗号隔开。

      默认值

      “必填”为“否”时,默认值生效。请求中不包含此参数时,ROMA API自动增加默认值发送给后端服务。

      字节限制

      • 最大长度/最大值:“类型”为“STRING”时,设置参数值的最大字符串长度,“类型”为“NUMBER”时,设置参数值的最大值。
      • 最小长度/最小值:“类型”为“STRING”时,设置参数值的最小字符串长度,“类型”为“NUMBER”时,设置参数值的最小值。

      示例

      参数值的填写示例。

      描述

      对于此参数的描述。

  7. 单击“下一步”,进入后端配置

后端配置

ROMA API支持定义多个策略后端,即满足一定条件后转发给指定的API后端服务,用以满足不同的调用场景。例如为了区分普通调用与特殊调用,可以定义一个“策略后端”,通过调用方的源IP地址,为特殊调用方分配专用的后端服务。

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

  1. 定义默认后端。

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

    在“后端配置”页面,选择API后端服务类型。

    后端服务类型分HTTP&HTTPS、FunctionGraph和Mock三种,具体参数描述见表4表5表6

    表4 HTTP&HTTPS类型定义后端服务

    服务参数

    参数说明

    负载通道

    是否使用负载通道访问后端服务。若选择“使用”,您需要提前创建负载通道

    URL

    URL地址由请求方法、请求协议、负载通道/后端服务地址和路径组成。

    • 请求方法

      GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS、ANY,其中ANY表示该API支持任意请求方法。

    • 请求协议

      HTTP或HTTPS,传输重要或敏感数据时推荐使用HTTPS。

      说明:

      支持WebSocket通信。

    • 负载通道(可选)

      仅在使用VPC通道时,需要设置。选择已创建的负载通道名称。

      说明:

      VPC通道中,云服务器的安全组必须允许100.125.0.0/16网段访问,否则将导致健康检查失败及业务不通。

    • 后端服务地址(可选)

      仅在不使用负载通道时,需要设置

      格式:“主机:端口”,主机为IP地址/域名,未指定端口时,HTTP协议默认使用80端口,HTTPS协议默认使用443端口。

      端口范围:1 ~ 65535。

      如果需要创建变量标识,则填写“#变量名#”,如#ipaddress#。支持创建多个变量标识,如#ipaddress##test#。

    • 路径

      后端服务的路径,即服务的uri,可以包含路径参数,以{路径参数}形式表示,比如/getUserInfo/{userId}。

      如果请求路径中含有环境变量,则使用#变量名#的方式将环境变量定义到请求路径中,如/#path#。支持创建多个环境变量,如/#path##request#。

    自定义host头域(可选)

    仅在使用负载通道时,可设置

    在请求被发送到负载通道中主机前,允许您自定义请求的Host头域,默认将使用请求中原始的Host头域。

    后端超时

    请求超时时间,1 ~ 60000ms。

    如果在API调试过程中,遇到后端响应超时之类的错误,请适当调大后端超时时间,以便排查原因。

    TLS双向认证

    是否选择“使用backend_client_certificate配置的证书做客户端认证”,若选择,您需在实例详情的“配置参数”页签中提前配backend_client_certificate证书。

    后端认证

    当您的后端服务需要对API调用增加自己的认证,则开启后端认证。

    后端认证需要先添加一个自定义认证,自定义认证通过函数服务实现,在函数服务中编写一个函数,实现您的认证鉴权流程,或者使用函数调用您的统一鉴权服务。

    说明:

    后端认证依赖函数服务,此功能仅在部分区域开放。

    表5 FunctionGraph类型定义后端服务

    服务参数

    参数说明

    函数名

    添加函数后,函数名自动生成。

    函数URN

    函数请求唯一标识。

    单击“添加”,添加所需的函数URN。

    版本

    函数的版本。

    调用类型

    • Synchronous:同步调用。指后端函数服务收到调用请求后立即执行并返回调用结果,客户端发送请求后同步等待,收到后端响应后关闭连接。
    • Asynchronous:异步调用。客户端不关注请求调用的结果,服务端收到请求后将请求排队,排队成功后请求就返回,服务端在空闲的情况下会逐个处理排队的请求。

    后端超时

    请求超时时间,1 ~ 60000ms。

    后端认证

    当您的后端服务需要对API调用增加自己的认证,则开启安全认证。

    后端认证需要先添加一个自定义认证,自定义认证通过函数服务实现,在函数服务中编写一个函数,实现您的认证鉴权流程,或者使用函数调用您的统一鉴权服务。

    说明:

    后端认证依赖函数服务,此功能仅在部分区域开放。

    表6 Mock类型定义后端服务

    服务参数

    参数说明

    Mock状态码

    需升级高版本SHUBAO组件后,方可设置。

    Mock返回结果

    Mock一般用于开发调试验证。在项目初始阶段,后端服务没有搭建好API联调环境,可以使用Mock模式,将预期结果固定返回给API调用方,方便调用方进行项目开发。

    后端认证

    当您的后端服务需要对API调用增加自己的认证,则开启安全认证。

    后端认证需要先添加一个自定义认证,自定义认证通过函数服务实现,在函数服务中编写一个函数,实现您的认证鉴权流程,或者使用函数调用您的统一鉴权服务。

    说明:

    后端认证依赖函数服务,此功能仅在部分区域开放。

    • 在URL中配置了变量标识后,在API调试页面将无法调试。
    • 变量名严格区分大小写。
    • 如果在URL中设置变量,那么必须在待发布环境上配置变量名和变量值,否则变量无法赋值,API将无法正常调用。

  2. (可选)配置默认后端的后端服务参数,将调用API时传入的请求参数映射到后端服务请求的对应位置。若6.c中未定义请求参数,可直接跳过此步骤。

    1. 在“后端服务参数”下,可通过以下任意一种方法添加后端服务参数。
      • 单击“导入入参定义”,把所有已定义的API请求参数添加到后端服务参数。
      • 单击“添加后端参数映射”,按需逐个添加后端服务参数。
    2. 根据后端服务实际的参数名称和参数位置修改映射关系,如图2所示。
      图2 配置后端服务参数
      1. 后端参数在“PATH”位置,那么参数名称需要和“路径”中的名称相同。
      2. 调用API的请求参数名称、位置可以与后端参数名称、位置不同。
        • 参数名不能是x-apig- 、x-sdk-开头,不区分大小写。
        • 参数名不能是x-stage,不区分大小写。
        • 参数位置为HEADER时,参数名不区分大小写,也不支持下划线开头。
      3. 如上图,test01和test03在调用API时分别配置于PATH和QUERY位置,后端服务通过映射,将在HEADER位置接收test01和test03的值。test02在调用API时配置于HEADER位置,后端服务通过映射,将在PATH位置以参数名test05来接收test02的值。

        假设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 API向后端服务发送请求时,将常量参数添加到请求的指定位置,然后将请求发送给后端服务。

    在“常量参数”下,单击“添加常量参数”,添加后端服务请求的常量参数。
    表7 常量参数配置

    参数

    配置说明

    常量参数名

    填写常量参数的名称。“参数位置”为“PATH”时,参数名需要与“路径”中的参数名称一致。

    说明:

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

    参数位置

    选择常量参数在后端服务请求中的位置,可选择“PATH”、“HEADER”和“QUERY”。

    参数值

    填写常量参数的值。

    描述

    填写常量参数的描述信息。

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

  4. (可选)配置默认后端的系统参数。如果后端服务需要接收系统运行时产生的参数信息,如网关内置参数、前端认证参数和后端认证参数等,可以通过设置系统参数来实现。ROMA API向后端服务发送请求时,将系统参数添加到请求的指定位置,然后将请求发送给后端服务。

    1. 在“系统参数”下,单击“添加系统参数”,添加后端服务请求的系统参数。
      表8 系统参数配置

      配置说明

      系统参数类型

      选择系统参数的类型。

      • 网关内置参数:ROMA API支持配置的参数。
      • 前端认证参数:前端自定义认证返回结果中的参数。在设置前端定义和安全配置中,“安全认证”选择“自定义认证”时,才可以选择此参数。
      • 后端认证参数:后端自定义认证返回结果中的参数。在后端配置中,“后端认证”开启时,才可以选择此参数。

      系统参数名

      填写系统参数的名称。

      • 系统参数类型为“网关内置参数”时,选择系统支持获取的参数。
      • 系统参数类型为“前端认证参数”或“后端认证参数”时,支持自定义参数,但是此参数必须为自定义认证返回结果中的参数。

      后端参数名称

      填写系统参数需要映射的后端参数名称。

      说明:

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

      后端参数位置

      选择后端参数在后端服务请求中的位置,可选择“PATH”、“HEADER”和“QUERY”。

      描述

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

  5. (可选)添加后端策略。

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

    1. 单击添加策略后端。
    2. 后端策略增加的参数,具体如表9所示,其他参数说明参考表4表5表6
      表9 后端策略参数

      信息项

      描述

      后端策略名称

      您自定义的名称,用于识别不同的后端策略。

      生效方式

      • 满足任一条件:只要满足策略条件中的任意一项,此后端策略就可以生效。
      • 满足全部条件:只有满足所有的策略条件,此后端策略才生效。

      策略条件

      使后端策略生效的条件,具体如表10所示。

      表10 策略条件

      信息项

      描述

      条件来源

      • 源地址:以访问API的请求地址作为策略条件来源。
      • 请求入参:以请求入参参数作为策略条件来源。
        须知:

        选择“请求入参”作为策略条件时,入参需要在API前端请求中配置好,如在Header或请求参数中添加一个参数。

      参数名称

      仅在“条件来源”为“请求入参”时,需要设置。选择已创建的入参参数名称。

      条件类型

      仅在“条件来源”为“请求入参”时,需要设置。

      • 相等:请求参数值必须为输入值时,条件成立。
      • 枚举:请求参数值只需要和枚举值中任何一个值相同,条件成立。
      • 匹配:请求参数值只需要和正则表达式中任何一个值相同,条件成立。

      条件值

      • “条件类型”为“相等”时,输入一个值。
      • “条件类型”为“枚举”时,输入多个值,以英文逗号隔开。
      • “条件类型”为“匹配”时,输入一个范围,例如:[0-5]。
      • “条件来源”为“源地址”时,输入一个或多个IP地址,以英文逗号隔开。

  6. 单击“完成”,进入“API运行”页面,可查看API信息。

后续操作

API创建后,可单击“更多 > 调试”验证服务是否正常,具体操作请参考调试API

分享:

    相关文档

    相关产品