API 网关使用指南

API 网关分成前后端服务,前端主要为接收客户端请求,并对其进行有效性校验及请求参数格式化后,再交给后端进行处理。

详细的控制台配置流程参考:点我直达

后端服务暂只支持云函数

云函数

云函数在被 API 网关作为后端服务时,其可以使用的传入参数及返回数据都与普通的云函数不一样。

需要注意,如 API 网关中 API 对应的云函数没有返回正确的数据格式时,该 API 则会响应失败。

云函数传入参数

传入参数在数据结构上没有改变,与云函数代码格式 中描述的一样。

其中变化的主要有以下几点:

  1. eventType 的取值为 api_gateway
  2. request.meta 中新增 API 网关请求相关的信息
  3. 由于 API 网关会配置自定义的认证、鉴权逻辑,所以 request.user 不再提供,如需在云函数中识别请求的用户,可从 request 携带的 headers 等参数,如 cookie、token 等获取相关信息后进行。

event.request.meta 对象数据结构说明

包含字段 类型 说明
request_method String 请求方法(始终为大写字母, 如 GET/POST 等)
query_string Object 请求中包含的 Query string
headers Object 请求中提交的自定义 Headers(预先在 API 的参数设置后才可以使用)
request_path String 请求路径(详细信息参见下文)
nested_arguments Array 请求路径中配置的位置参数(详细信息参见下文)
named_arguments Object 请求路径中配置的命名参数(详细信息参见下文)
ip_address String 调用客户端地址
user_agent String 调用客户端 User-Agent

示例:

{
    "request_method": "GET",
    "nested_arguments": [],
    "named_arguments": {},
    "request_path": "/hello-world/",
    "query_string": {"query": ["1", "2"], "string": ["1"]},
    "headers": {
        "customer-headers": "foo"
    },
    "ip_address": "127.0.0.1",
    "user_agent": "user-agent",
}

请求路径

API 网关在定义 API 路径时,支持使用符合正则表达式语法来定义请求路径及其参数,以便更好地构造成动态路径。

比如,在控制台设置路径(位置表达式):

/article/(\d+)/

或者,在控制台设置路径(命名表达式):

/article/(?P<article_id>\d+)/

客户端在请求时,云函数即可对路径及其参数进行获取,在客户端请求路径为:/article/123/ 时,event.request.meta 中通过 nested_arguments 或者 named_arguments 获取参数。

示例:

  • 位置参数

      {
          "request_method": "GET",
          "nested_arguments": ["123"],
          "named_arguments": {},
          "request_path": "/article/123/",
          "query_string": {},
          "headers": {},
          "ip_address": "127.0.0.1",
          "user_agent": "user-agent",
      }
    
  • 命名参数

      {
          "request_method": "GET",
          "nested_arguments": [],
          "named_arguments": {"article_id": "123"},
          "request_path": "/article/123/",
          "query_string": {},
          "headers": {},
          "ip_address": "127.0.0.1",
          "user_agent": "user-agent",
      }
    

更详细的说明及语法介绍,请查看API 网关定义 API 路径指南

event.data 对象说明

目前知晓云 API 网关支持接收以下格式的内容:

  • JSON(Content-Type: application/json
  • XML(Content-Type: application/xml)

API 网关会将 JSON/XML 内容转为 JavaScript 合法类型,使得云函数内部中无需再次解析,提升使用效率。

其中 XML 内容的会从字符串转为对象,如用户的请求内容为:

<xml>
  <return_code><![CDATA[SUCCESS]]></return_code>
  <return_msg><![CDATA[OK]]></return_msg>
</xml>

转换后可使用的内容则为:

{
    "xml": {
        "return_code": "SUCCESS",
        "return_msg": "OK"
    }
}

云函数返回结果

在 API 网关调用的云函数中,需要指定返回结果为以下对象结构,如:

{
    "content": "hello, world!",
    "content_type": "text/plain",
    "status_code": 200
}

对象说明

包含字段 类型 说明
content String 响应内容
content_type String 响应内容的类型
status_code Integer 响应状态码

响应内容类型支持以下几种:

  • text/plain
  • text/html
  • application/json
  • application/xml

状态码使用可阅读资料:https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

示例代码

返回内容为 text/plain 类型

exports.main = async function helloWorld (event) {

    var response_data = {
        content: "hello, world!",
        content_type: "text/plain",
        status_code: 200
    }

    // Do something...

    return response_data
}

返回内容为 text/html 类型

exports.main = async function helloWorld (event) {

    var response_data = {
        content: "<html><body><h1>hello, world!</h1></body></html>",
        content_type: "text/html",
        status_code: 200
    }

    // do something...

    return response_data
}

返回内容为 application/json 类型

exports.main = async function helloWorld (event) {

    var response_data = {
        content: "{\"hello\": \"world\"}",
        content_type: "application/json",
        status_code: 200
    }

    // do something...

    return response_data
}

返回内容为 application/xml 类型

exports.main = async function helloWorld (event) {

    var response_data = {
        content: "<xml><hello>world!</hello></xml>",
        content_type: "application/xml",
        status_code: 200
    }

    // do something...

    return response_data
}

认证方式

API 网关支持开发者选择以下几种认证方式:

  1. 免鉴权
  2. JWT

若开发者选择免鉴权的认证方式,则 API 网关在收到匿名请求时,也可以通过认证。

推荐开发者对信息较为敏感的网关请求采用 JWT 的认证方式。

JWT 认证

当开发者在控制台为网关 API 成功绑定所使用的 JWT 后,开发者即可使用该 JWT 完成接口认证。

在 API 请求中,传递如下 http headers -- Authorization: Bearer <token>,其中 token 通过当前路由绑定的 JWT 密钥生成。

token 生成方式如下:

  1. 首先指定使用算法 HS256;
  2. 不特别指定 JWT 签名所使用的 payload ,开发者可选择对一个空的 {} 进行签名,也可选择设置 JWT 提供的官方字段 exp(过期时间)/nbf(生效时间) 等规定 token 有效期;
  3. 使用 HS256 算法、JWT 签名所需 payload 以及路由绑定的 JWT 密钥,即可生成认证所需的 token。

服务器在收到 Authorization header 中的 token 之后,将校验其有效性,若 token 校验不通过则将返回 401 错误码。

自有域名

API 网关支持开发者使用自有域名作为网关请求域名。

使用自有域名时,需要先为您的二级域名在知晓云接入 API 域名备案点我直达

由于一个域名只能绑定一个 API 网关,建议在绑定网关时使用三级域名。

即,若开发者已在知晓云接入 example.com 的 API 域名备案,则开发者可使用形如 example.example.com 的域名进行 API 网关自有域名绑定。

在绑定 API 网关自有域名后,开发者需要在域名服务商处解析 CNAME

results matching ""

    powered by

    No results matching ""