將資料傳入及傳出後端服務

當 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 Run 函式 
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 會指定已部署後端的 Google Cloud 區域。
  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 Run 函式通常會使用這個方法。

例如：

  • 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

將 path_translation 設為 x-google-backend 的一部分：

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。