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

當 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 functions	x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run	x-google-backend: address: https://[TAG---]SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
App Engine 標準環境	x-google-backend: address: https://PROJECT_ID.appspot.com

在這些範例中：

• GCP_REGION 指定已部署後端的 Google Cloud 區域。
• PROJECT_ID 指定 Google Cloud 專案 ID。
• TAG 是您要求 Cloud Run 修訂版本時的選用流量標記。另請參閱 Cloud Run 說明文件中的「確定性網址」。
• SERVICE_NAME 是 Cloud Run 服務的名稱。
• PROJECT_NUMBER 是 Google Cloud 專案編號。
• REGION 是區域名稱，例如 us-west1。

此外，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。