将数据传入和传出后端服务

当 API 客户端向部署在 API Gateway 上的 API 发出请求时，客户端可以在请求中传递以下部分或全部信息：

  • 请求标头
  • 查询参数
  • 表单数据
  • XML 或 JSON 载荷
  • 请求路径

在构建其对 API 请求的响应时，后端服务可以将数据返回到 API 客户端，其中包括：

  • 响应标头
  • XML 或 JSON 载荷

本文档介绍了如何将此数据传入和传出后端服务。

如何向后端服务器传递请求数据？

来自 API 客户端的请求中的所有数据都会按原样传递给后端服务。然后，由后端服务负责在处理请求时解析请求数据。

如何将响应数据返回到 API 客户端？

从后端服务响应中收到的所有数据都会按原样传递给 API 客户端。然后，由 API 客户端负责处理响应中返回的任何数据。

如何将请求网址传递到后端服务？

用于向后端服务发出请求的网址由 x-google-backend 扩展程序控制。本部分介绍用于配置后端服务网址的选项。

在 OpenAPI 规范中设置后端服务地址和路径

在用于创建 API 配置的 OpenAPI 规范中，使用 x-google-backend 扩展程序指定后端服务的网址。例如，您可以按以下形式指定后端服务：

后端 x-google-backend
Cloud Functions 

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run 

x-google-backend:
  address: https://hello-HASH.a.run.app
App Engine 标准环境 

x-google-backend:
  address: https://PROJECT_ID.appspot.com

在这些示例中：

  1. GCP_REGION 指定已部署的后端的 GCP 地区。
  2. PROJECT_ID 指定 Google Cloud 项目 ID。
  3. HASH 指定在创建 Cloud Run 服务时生成的唯一哈希代码。

此外，OpenAPI 规范中的 path 参数指定 API 支持的端点或资源。您可以指定绝对路径或使用路径参数的路径：

路径 包含参数的路径 

paths:
  /hello:
 

paths:
  /hello/{name}:

通过 API 请求生成后端服务网址

当 API Gateway 处理来自 API 客户端的请求时，它会接受 API 客户端发送的请求网址，并将其转换为用于向后端服务发出请求的网址。至于这种转换具体是如何发生的，则取决于您所使用的路径转换策略。

x-google-backend 扩展程序的 path_translation 选项支持两种路径转换策略：

  • APPEND_PATH_TO_ADDRESS：后端服务网址是通过将客户端请求中的资源路径附加到 x-google-backend 扩展程序的 address 网址来生成的。

    大多数后端服务使用 APPEND_PATH_TO_ADDRESS，因为这意味着后端会接收 API 客户端指定的同一资源路径。

  • CONSTANT_ADDRESS：后端服务网址是常量，由 x-google-backend 扩展程序的 address 网址定义。如果客户端请求包含资源路径，则系统会使用查询参数将资源路径添加到后端服务网址。

    此方法通常由 Cloud Functions 使用。

例如：

  • APPEND_PATH_TO_ADDRESS
    • address：https://PROJECT_ID.appspot.com
    • 不带 OpenAPI 路径参数：
      • OpenAPI 路径：/hello
      • API 客户端请求资源路径：/hello
      • 后端服务请求网址：https://PROJECT_ID.appspot.com/hello
    • 带 OpenAPI 路径参数：
      • OpenAPI 路径：/hello/{name}
      • API 客户端请求资源路径：/hello/Dave
      • 后端服务请求网址：https://PROJECT_ID.appspot.com/hello/Dave
  • CONSTANT_ADDRESS
    • address：https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
    • 不带 OpenAPI 路径参数
      • OpenAPI 路径：/hello
      • API 客户端请求资源路径：/hello
      • 后端服务请求网址：https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
    • 带 OpenAPI 路径参数
      • OpenAPI 路径：/hello/{name}
      • API 客户端请求资源路径：/hello/Dave
      • 后端服务请求网址：https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

设置 path_translation

在设置 x-google-backend 的过程中设置 path_translation：

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]`

默认值 path_translation 取决于您在 OpenAPI 规范中设置 x-google-backend 的位置：

  • 当 x-google-backend 在 OpenAPI 规范的顶层使用时，path_translation 默认为 APPEND_PATH_TO_ADDRESS。

  • 当 x-google-backend 在 OpenAPI 规范的操作级层使用时，path_translation 默认为 CONSTANT_ADDRESS。