文档首页 > > 用户指南(开放API)> API管理> 创建API

创建API

分享
更新时间: 2019/10/10 GMT+08:00

操作场景

API提供者把API接口配置在API网关中,开放后端能力。

创建API主要分为四个步骤:设置基本信息、定义API请求、定义后端服务和定义返回结果。

说明:
  • API网关服务基于REST的API架构,API的开放和调用需要遵循RESTful相关规范。
  • 每个用户最多可以创建200个API。

前提条件

  • 已创建API分组。如果未创建API分组,可在本操作页面中创建API分组。
  • 如果后端服务需要使用VPC通道,请先创建VPC通道,或在本操作页面中创建VPC通道。

设置基本信息

  1. 登录管理控制台。
  2. 在管理控制台左上角单击,选择区域。
  3. 在服务列表中,选择“应用服务 > API网关”,进入API网关服务管理页面。
  4. 单击“开放API > API管理”,进入到API列表信息页面。
  5. 单击“新建API”,进入“新建API”页面,如图1所示。填写如表1所示信息。

    图1 设置基本信息
    表1 基本信息

    信息项

    描述

    API名称

    API名称。

    所属分组

    API所属分组。

    如果尚未创建API分组,单击“新建分组”,为API新创建一个分组。

    类型

    API类型:

    • 公开:选择“公开”类型时,API支持上架。
    • 私有:选择“私有”类型时,当该API所在分组上架时,该API不会上架。

    安全认证

    API认证方式:

    • APP认证:表示由API网关服务负责接口请求的安全认证。
    • 华为IAM认证:表示借助IAM服务进行安全认证。
    • 无认证:表示不需要认证。

    各种认证方式下的API调用稍有不同,具体请参考《API网关开发指南》。

    推荐使用APP认证方式。

    注意:
    • 认证方式为华为IAM认证时,任何API网关租户均可以访问此API,可能存在恶意刷流量,导致过量计费的风险。
    • 认证方式为无认证时,任何公网用户均可以访问此API,可能存在恶意刷流量,导致过量计费的风险。

    描述

    API的描述。

  6. 单击“下一步”,进入“定义API请求”页面。

定义API请求

  1. 在“定义API请求”页面,填写如表2所示信息。

    图2 定义API请求
    表2 定义API请求

    信息项

    描述

    域名

    系统默认分配的一个子域名。

    请求协议

    分为三种类型:

    • HTTP
    • HTTPS
    • HTTP&HTTPS

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

    请求Path

    接口请求的路径。

    格式如:/{serviceName}/{interfaceName}

    • {}中的内容区分大小写。
    • 请求Path中包含请求参数时,必须设置对应的入参定义。

    匹配模式

    分为两种模式:

    • 绝对匹配:调用的请求Path固定为创建时填写的API请求Path。
    • 前缀匹配:调用的请求Path将以创建时填写的API请求Path为前缀,支持接口定义多个不同Path。
      例如,请求路径为/test/AA,使用前缀匹配时,通过/test/AA/CC可以访问,但是通过/test/AACC无法访问。
      说明:

      前缀匹配不支持“+”字符。

    Method

    接口调用方式:GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS、ANY

    其中ANY表示该API支持任意请求方法。

    支持CORS

    是否开启跨域访问CORS(cross-origin resource sharing)。

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

    CORS请求分为两类:

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

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

  2. (可选)设置入参定义。

    入参定义是指您调用API时,需要传入的参数的说明。
    1. 单击“添加入参定义”,弹出“添加入参定义”对话框。
    2. 输入如表3所示信息。
      图3 添加入参定义
      表3 入参定义

      信息项

      描述

      参数名

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

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

      参数位置

      选择参数在请求中的位置。

      参数位置有如下三种:PATH、HEADER、QUERY

      类型

      字段的类型,包含String和Number。

      必填

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

      默认值

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

      示例

      参数值的填写示例。

      描述

      对于此参数的描述。

    3. 单击“确定”,完成入参定义的设置。

  3. 当“Method”为“POST”/“PUT”/“PATCH”/“ANY”时,您可以在“请求体内容描述”中增加对于请求体的描述信息。
  4. 单击“下一步”,进入“定义后端服务”页面。

定义后端服务

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

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

  1. 定义默认后端。

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

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

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

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

    服务类型

    服务参数

    参数说明

    HTTP/HTTPS

    协议

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

    说明:

    支持WebSocket通信。

    请求方式

    接口调用方式,包括GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS、ANY。

    其中ANY表示该API支持任意请求方法。

    使用VPC通道

    是否使用VPC通道。

    包括使用和不使用。

    后端服务地址(可选)

    仅在不使用VPC通道时,需要设置。

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

    端口范围:1 ~ 65535。

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

    VPC通道(可选)

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

    自定义host头域(可选)

    在请求被发送到VPC通道中主机前,允许您自定义请求的Host头域,默认将使用请求中原始的Host头域。仅在使用VPC通道时,需要设置。

    后端请求Path

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

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

    后端超时

    请求超时时间,1 ~ 60000ms。默认为5000ms。

    FunctionGraph

    functionURN

    函数请求唯一标识。

    单击“添加”,添加所需的functionURN。

    版本

    函数的版本。

    调用类型

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

    后端超时

    请求超时时间,1 ~ 60000ms。默认为5000ms。

    Mock

    Mock返回结果

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

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

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

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

    1. 单击“添加策略后端”。
    2. 后端策略增加的参数,具体如表5所示,其他参数说明参见表4
      图5 后端策略新增参数
      表5 后端策略参数

      信息项

      描述

      后端策略名称

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

      生效方式

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

      策略条件

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

      表6 策略条件

      信息项

      描述

      条件来源

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

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

      参数名称

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

      条件类型

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

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

      条件值

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

  3. (可选)配置后端服务参数。

    将调用API时传入的参数映射到后端服务对应的位置。

    1. 在“后端服务参数”右侧单击,通过以下任意一种方法配置后端服务参数。
      • 单击“导入入参定义”,系统自动添加已创建的所有入参参数。
      • 单击“添加后端参数映射”,按照需求添加您所需要的后端参数映射。
    2. 根据后端服务实际的参数名称和参数位置修改映射关系,如图6所示。
      图6 配置后端服务参数
      1. 参数在“PATH”位置,那么参数名称需要和“后端请求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为abc,test02为def,test03为xyz。

        调用API请求:

        curl -ik -H 'test02:def' -X GET https://myhwclouds.com/v1.0/abc?test03=xyz

        后端服务请求:

        curl -ik -H 'test01:abc' -H 'test03:xyz' -X GET https://myhwclouds.com/v1.0/def

  4. (可选)设置常量参数。

    如果后端服务需要接收API调用者不可见的常量,可以通过设置常量参数来实现。API网关在请求后端服务时,将常量参数增加到指定请求位置,并将请求发送给后端服务。

    1. 在“常量参数”右边单击,显示常量参数列表。
    2. 单击“添加常量参数”,输入如表7所示信息。
      图7 添加常量参数
      表7 常量参数

      信息项

      描述

      常量参数名

      常量参数的名称,如果参数在“PATH”位置,那么参数名称需要和“后端请求Path”中的名称相同。

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

      参数位置

      选择参数在请求中的位置。

      参数位置有如下三种:PATH、QUERY、HEADER

      参数值

      输入参数的值。

      描述

      对于此常量参数的描述。

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

  5. 单击“下一步”,进入“返回结果基础定义”页面。

定义返回结果

  1. 在“返回结果基础定义”页面,填写如表8所示信息。

    表8 定义返回结果

    信息项

    描述

    成功响应示例

    成功调用API时,返回的响应信息示例。

    失败响应示例

    调用API失败时,返回的响应信息示例。

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

    API创建完成后,在API列表页面单击API名称,查看API详细信息。

使用API方式创建API

您还可以使用API的方式创建API,具体操作请查看以下链接。

注册API

后续操作

您创建完API后,通过调试API,验证服务是否正常。

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

跳转到云社区