API 文档

创建通用 API

最近更新时间:2020-04-23 18:40:02

操作场景

该任务指导您通过 API 网关控制台创建通用 API,并对前端、后端、响应结果的配置方法进行了详细说明。

步骤1:新建通用 API

  1. 登录 API 网关控制台 ,在左侧导航栏单击【服务】。
  2. 在服务列表中,单击目标服务的服务名,查看该服务。
  3. 在服务信息中,单击【管理 API】标签页,根据后端业务类型选择创建【通用 API】。
  4. 单击【新建】,进行后续配置。

步骤2:前端配置

API 的前端配置指提供给外界访问的相关配置,包括 API 名称、前端类型、请求协议、HTTP 方法、URL 路径和入参的定义。

前端基础信息配置

  • API 名称:您创建的 API 的名称,在当前服务内具有唯一性,支持最长60个字符。
  • 前端类型:API 网关支持 HTTP、WEBSOCKET 两种前端类型。
    • HTTP:适用于后端对接 HTTP、对接 Mock、对接 cloud function 的情况。
    • WEBSOCKET:适用于业务使用 WEBSOCKET,后端对接 WEBSOCKET、cloud function 的情况。
  • 请求协议:API 网关支持 HTTP/HTTPS 协议,可选择仅 HTTP、仅 HTTPS、HTTP 和 HTTPS 三种支持方式。
  • HTTP 方法:可选择 GET、POST、PUT、DELETE、HEAD 方法。
  • URL 路径(Path):您可以按需求写入合法 URL 路径。如需要在路径中配置动态参数,请使用{}符号,并在其中填入参数名,例如/user/{userid}路径,申明了路径中的 userid 参数,此参数同时需要在入参中作为 Path 类型参数进行定义。Query 参数可以不用在 URL 路径中定义。
    路径支持正则表达式方式匹配,路径输入内容以/user为例:
    • =/user:代表精确匹配,当存在多个 API 接口都有/user时,优先匹配含有=/user的配置的 API 接口。
    • ^~/user:代表匹配 user 前缀,当存在多个 API 接口都有/user时,优先级第二匹配含有^~/user的配置的 API 接口。
    • /user/{id}:代表路径上存在动态参数,当存在多个 API 接口都有/user时,优先级第三匹配含有动态参数的配置的 API 接口。
    • /user:表示完全匹配或前缀匹配的方式访问,访问时/user/usertest/user/test/a都可以访问到/user路径的 API 接口。
    • 支持标准正则标识式,例如星号(*)匹配前面的子表达式零次或多次 、问号(?)匹配前面的子表达式零次或一次等。

前端参数配置

入参:入参包含了来源于 Header、Query、Path 的参数。其中 Path 参数对应于在 URL 路径中定义的动态参数。任一参数,均需要指定参数名,参数类型和参数数据类型;同时可以指明是否必填、默认值、示例数据和描述说明。利用这些配置,API 网关可以协助您完成入参的文档化和初步校验。

说明:

  • 请求协议为 HTTPS 时,需要请求中携带 SNI 标识,为了保障请求安全,API 网关会拒绝不携带 SNI 标识的请求。
  • SNI(Server Name Indication)是 TLS 的一个扩展协议,用于解决一个服务器拥有多个域名的情况,在 TLSv1.2 开始得到协议的支持。之前的 SSL 握手信息中没有携带客户端要访问的目标地址,如果一台服务器有多个虚拟主机,且每个主机的域名不一样,使用了不一样的证书,此时会无法判断返回哪一个证书给客户端,SNI 通过在 Client Hello 中补上 Host 信息解决该问题。

步骤3:后端配置

API 的后端配置,是指的实际提供真实服务的配置。API 网关会将前端请求,依据后端配置进行转换后,转发调用到实际的服务上。
API 网关提供的后端配置,根据前端类型的不同而略有不同,具体如下:

对接 HTTP

当您的业务部署在其他云,或者本地服务器用 HTTP 开放时,后端选用 HTTP 对接。

配置说明:

  1. 后端对接 HTTP 时,需要选择您的后端类型为 HTTP。
  2. 选择是否启用 VPC,如需启用 VPC,请根据控制台提示选择 VPC 资源。
  3. 输入后端域名,以http://https://开头,不包括后面的路径,例如http://api.myservice.comhttp://108.160.162.30
  4. 输入后端路径,以/开头,如/path/path/{petid}
  5. 选择请求方法,前后端选择的请求方法可不一致。
  6. 设置后端超时时间。超时时间的最大限制为30分钟。在 API 网关调用后端服务,未在超时时间内获得响应时,API 网关将终止此次调用,并返回相应的错误信息。
  7. 设置映射前端的后端参数。
  8. 单击【下一步】,配置响应结果。

API 网关后端对接 VPC 内的 CLB 资源

当用户在配置后端对接服务为 VPC 内的 CLB 时,前端配置与其他 API 配置方法相同,后端配置方法如下:

  1. 在后端配置中需要先选择所需对接的 VPC。
  2. 选择 VPC 内资源为 CLB。
    目前 API 网关仅支持对接 VPC 内的 CLB,后续还会陆续支持 VPC 内的其他云资源。
  3. 选择后端域名的 CLB 及对应监听器。
    如您选择 HTTP 或 HTTPS 监听器,请确保后端 CVM 开通了公网带宽,否则可能会出现网络请求不通的问题(此策略产生的流量不计入公网出流量)。
  4. 在后端域名处填写 http://vip+porthttps://vip+port, 这里根据您填写的不同我们发往 CLB 的请求会分别为 HTTP 请求或 HTTPS 请求。此处的 VIP 是 CLB 的 VIP,您可在应用型内网 CLB 的基本信息中查询到(参考步骤1截图)。
  5. 填写后端路径。
    • 如果您选择的是 HTTP/HTTPS 的 CLB 监听类型,在后端路径配置中,需要将后端路径配置为用户在 CLB 中监听器中配置的路径。
      CLB 中监听器配置的域名及路径:

      API 网关中的后端路径,需要和 CLB 中的路径一致。
      此外,还需要在常量参数处配置一个名为 host 的参数,放在 header 中,参数值为 CLB 监听器中配置的域名。
    • 如果您选择的是 TCP/UDP 的 CLB 监听类型,在后端配置中,需要将后端路径配置为 CLB 后端挂载 CVM 中业务所需的路径。
      如果您在 CVM 中配置了 host 校验,则如同使用七层监听器一样,需要在常量参数中配置名为 host 的参数,根据您自身的业务选择所需放置的地址。后续的配置与其他的 API 配置相同。
      注意:

      当后端对接 CLB 时,需要将后端挂载的 CVM 上的安全组放通100.64.0.0/10、9.0.0.0/8 网段。

对接 SCF

当您的业务实现在云函数 SCF 中,希望通过 API 网关将服务能力开放出来时,后端选用 SCF 对接。

后端对接 SCF 时,需要填写的参数如下表:

序号 参数名称 参数含义
1 命名空间 对接函数所在的命名空间,默认为 default
2 名称 对接函数的名称
3 版本 对接函数的版本,默认为 $LATEST
4 响应时间 响应时间,默认为15秒
5 响应集成 见下文

响应集成说明:

针对 API 网关发送到云函数的请求处理方式,和云函数响应给 API 网关的返回值处理方式,称为请求方法和响应方法。请求方法和响应方法规划和实现的分别有透传方式和集成方式:

  • 不开启集成响应,为透传方式。在 API 网关向 SCF 发送请求时,会以固定的结构体对 request 信息进行组合。SCF 收到的为此固定结构体,返回保持透传不做处理,响应格式仅支持 json。
  • 开启响应集成时,为集成方式。API 网关向 SCF 发送请求时会以固定结构体对 request 信息进行组合,SCF 返回的也需要为固定结构体。API 网关再将 SCF 返回的内容映射到 statusCode、header、body 等位置返回给客户端。

如果开启响应集成,用户必须配置SCF,以如下数据格式返回数据给 API 网关,以便 API 网关解析:

{ 
        "isBase64Encoded": false, //是否使用base64编码,值为 true 或者 false 
        "statusCode": 200, // http请求状态码 
        "headers": {"Content-Type":"text/html"}, 
        "body": "<html><body><h1>Heading</h1><p>Paragraph.</p></body></html>" 
}

API 网关发往 SCF 的结构体格式为:

{
  "requestContext": {
    "serviceId": "service-f94sy04v",
    "path": "/test/{path}",
    "httpMethod": "POST",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
    "identity": {
      "secretId": "abdcdxxxxxxxsdfs"
    },
    "sourceIp": "10.0.2.14",
    "stage": "release"
  },
  "headers": {
    "Accept-Language": "en-US,en,cn",
    "Accept": "text/html,application/xml,application/json",
    "Host": "service-3ei3tii4-251000691.ap-guangzhou.apigateway.myqloud.com",
    "User-Agent": "User Agent String"
  },
  "body": "{\"test\":\"body\"}",
  "pathParameters": {
    "path": "value"
  },
  "queryStringParameters": {
    "foo": "bar"
  },
  "headerParameters":{
    "Refer": "10.0.2.14"
  },
  "stageVariables": {
    "stage": "release"
  },
  "path": "/test/value",
  "queryString": {
    "foo" : "bar",
    "bob" : "alice"
  },
  "httpMethod": "POST"
}
说明:

您可以通过编写云函数 SCF 来实现 Web 后端服务,并通过 API 网关对外提供服务。API 网关会将请求内容以参数形式传递给函数,并将函数返回作为响应返回给请求方。详细内容请参考 API 网关触发器概述

对接 mock

mock 会对 API 请求返回固定配置的响应。mock 常用于测试开发,可以在后端服务还未完成的情况下预先完成 API 配置和响应。对接 mock 时,只需要配置您的返回数据,单击【完成】即可。

对接 WEBSOCKET

当用户的业务使用 WEBSOCKET 时,后端服务可选择对接 WEBSOCKET。对接 WEBSOCKET 的配置方式与 对接 HTTP 基本相同,但后端域名以ws://wss://开头,不包括后面的路径。

步骤4:响应配置

API 响应配置:包括 API 响应数据配置和 API 错误码配置。
API 响应数据配置:用于指明返回数据类型,包括成功调用的数据示例和失败调用的数据示例。
API 的错误码定义:用于指明额外的错误码、错误信息和描述。

说明:

目前 API 网关对于响应结果不做处理,直接透传给请求者。在生成 SDK 文档时,填写的响应示例也会一并展示在文档中,它将会更好的帮助使用者理解接口含义。

目录