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

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: APP_URL x-google-backend: address: DETERMINISTIC_URL
App Engine 標準環境	x-google-backend: address: https://PROJECT_ID.appspot.com

在下列範例中：

• APP_URL 指定 Cloud Run 服務的實際網址 (所呼叫 API 的完整路徑)，也稱為非確定性網址。例如：https://hello-abc1def2gh-uc.a.run.app。
• DETERMINISTIC_URL 是 Cloud Run 服務後端的確定性網址。

注意：如果您打算使用確定性網址來建立 Cloud Run 服務後端的版本，則必須指定下列其中一項：

• OpenAPI 2.0：x-google-backend 區段中 address 旁的 jwt_audience 欄位
• OpenAPI 3.x：x-google-api-management.backends 下方後端定義中的 jwtAudience 欄位和 address

將 jwt_audience 或 jwtAudience 欄位設為 Cloud Run 服務主機名稱。例如，OpenAPI 2.0：

...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...

如果沒有 jwt_audience 或 jwtAudience 欄位，系統會將 JWT 目標對象宣告的 address 欄位值設為預設值。如果修訂版本標記網址用於 address，且未指定 jwt_audience 或 jwtAudience，Cloud Run 可能會出現非預期的 JWT 目標對象宣告。

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

在設定 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 的位置：

• 在 OpenAPI 規格的頂層使用 x-google-backend 時，path_translation 預設為 APPEND_PATH_TO_ADDRESS。

• 在 OpenAPI 規格的作業層級使用 x-google-backend 時，path_translation 預設為 CONSTANT_ADDRESS。