API Gateway 中的 OpenAPI 3.x 擴充功能

API Gateway 接受一組 Google 專屬的 OpenAPI 規格擴充功能，這些擴充功能可設定閘道的行為。您可以在 OpenAPI 文件中直接指定 API 管理設定、驗證方法、配額限制和後端整合。瞭解這些擴充功能有助於調整服務行為，並與 API Gateway 功能整合。

這個頁面將說明 Google 專屬的 OpenAPI 規格 3.x 擴充功能。

雖然以下提供的範例為 YAML 格式，但也支援 JSON 格式。

x-google-api-management

必要。

x-google-api-management 擴充功能會定義服務的頂層 API 管理設定。將這個擴充功能放在 OpenAPI 文件的根目錄。

下表說明 x-google-api-management 的欄位：

欄位 類型 必填 預設 說明
metrics map[string]Metric 否 空白 定義要強制執行配額限制的指標。
quota map[string]Quota 否 空白 為服務指定配額限制。
backends map[string]Backend 是 空白 設定後端服務。
apiName string 否 空白 將名稱與 OpenAPI 文件中定義的作業建立關聯。

Metric 物件

Metric 物件會定義用於強制執行配額的指標。

下表說明 Metric 的欄位：

欄位 類型 必填 預設 說明
displayName string 否 空白 指標的顯示名稱。

Quota 物件

Quota 物件會定義配額限制。

下表說明 Quota 的欄位：

欄位 類型 必填 預設 說明
limits map[string]QuotaLimit 否 空白 指定配額限制。

Quota Limit 物件

QuotaLimit 物件會定義特定配額限制。

下表說明 QuotaLimit 的欄位：

欄位 類型 必填 說明
metric string 是 參照這份 OpenAPI 文件中宣告的指標。
values int64 是 設定指標可達到的最大值，超過這個值就會拒絕用戶端要求。

Backend 物件

Backend 物件會設定後端服務。您必須設定 jwtAudience 或 disableAuth。

下表說明 Backend 的欄位：

欄位 類型 必填 預設 說明
address string 否 空白 指定後端網址。
jwtAudience string 否 空白 根據預設，API Gateway 會建立執行個體 ID 權杖，並使用與位址欄位相符的 JWT 目標對象。只有在目標後端使用以 JWT 為基礎的驗證機制，且預期目標對象與地址欄位中指定的值不同時，才需要手動指定 jwt_audience。如果是部署在 App Engine 或使用 IAP 的遠端後端，您必須覆寫 JWT 目標對象。App Engine 和 IAP 會使用其 OAuth 用戶端 ID 做為預期目標對象。
disableAuth bool 否 False 防止資料平面 Proxy 取得執行個體 ID 權杖，並將其附加至要求。
pathTranslation string 否 APPEND_PATH_TO_ADDRESS或CONSTANT_ADDRESS 在將要求 Proxy 至目標後端時，設定路徑轉譯策略。如果在頂層設定 x-google-backend，且未指定 path_translation，則預設 pathTranslation 為 APPEND_PATH_TO_ADDRESS。如果在作業層級設定 x-google-backend，但未指定 path_translation，則預設為 CONSTANT_ADDRESS。
deadline double 否 15.0 指定等待要求完整回應的秒數。超過期限的回覆會逾時。
protocol string 否 http/1.1 設定將要求傳送至後端的通訊協定。支援的值包括 http/1.1 和 h2。

x-google-auth

選填。

x-google-auth 擴充功能會在安全機制物件中定義驗證設定。

下表說明 x-google-auth 的欄位：

欄位 類型 必填 預設 說明
issuer string 否 空白 指定憑證核發機構。值可以是主機名稱或電子郵件地址。
jwksUri string 否 空白

提供者公開金鑰的 URI，用於驗證 JSON Web Token 的簽名。API Gateway 支援此 OpenAPI 擴充功能定義的兩種非對稱公開金鑰格式：

  1. JWK 集格式。例如：jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. X509。例如：jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

如果您使用對稱金鑰格式，請將 jwksUri 設為含有 base64url 編碼金鑰字串的檔案 URI。
audiences [string] 否 空白 列出 JWT 驗證期間，JWT aud 欄位必須相符的目標對象。
jwtLocations [JwtLocations] 否 空白 自訂 JWT 權杖的位置。根據預設，JWT 會在 Authorization 標頭 (以「Bearer 」為前置字元)、X-Goog-Iap-Jwt-Assertion 標頭或 access_token 查詢參數中傳遞。

JwtLocations 物件

JwtLocations 物件會提供 JWT 權杖的自訂位置。

下表說明 JwtLocations 的欄位：

欄位 類型 必填 預設 說明
header | query string 是 不適用 指定含有 JWT 的標頭名稱，或含有 JWT 的查詢參數名稱。
valuePrefix string 否 空白 僅限標頭。設定後，其值必須與包含 JWT 的標頭值前置字串相符。

x-google-quota

選填。

x-google-quota 擴充功能會定義配額限制。您可以在 OpenAPI 文件的頂層或個別作業中定義這項擴充功能。

下表說明 x-google-quota 的欄位：

欄位 類型 必填 說明
self map[string]int64 是 quota 物件 (self) 會參照物件中定義的任何指標。在本例中，請將指標 (例如 read-requests) 對應至要遞增指標的金額。當指標值達到配額限制時，系統會拒絕要求。

x-google-backend

必要。

x-google-backend 擴充功能會參照 x-google-api-management 中定義的後端。您必須為 API Gateway 設定這項擴充功能。您可以在 OpenAPI 文件的頂層或個別作業中定義這項擴充功能。

下表說明 x-google-backend 的欄位：

欄位 類型 必填 說明
self string 是 參照 x-google-api-management 中定義的後端 ID。

x-google-endpoint

選填。

x-google-endpoint 擴充功能用於設定 OpenAPI 3.x 文件 servers 陣列中定義的伺服器屬性。OpenAPI 文件中只能有一個伺服器項目使用 x-google-endpoint 擴充功能。

擴充功能也會定義其他後端功能，包括：

  • CORS：您可以將 allowCors 屬性設為 true，啟用跨源資源共享 (CORS)。

  • 基本路徑：伺服器上以 x-google-endpoint 設定的基本路徑會用於您的 API。舉例來說，下列設定會將 v1 設為基本路徑：

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

下表說明 x-google-endpoint 的欄位：

欄位 類型 必填 預設 說明
allowCors bool 否 false 允許 CORS 要求。

x-google-parameter

選填。

x-google-parameter 擴充功能是在 parameter 項目中定義，如果路徑使用路徑範本，指定應使用雙萬用字元比對行為，則可使用這項屬性。

下表說明 x-google-parameter 的欄位：

欄位 類型 必填 說明
pattern string 是 這必須設為 **。

瞭解 OpenAPI 擴充功能限制

這些 OpenAPI 擴充功能有特定限制。詳情請參閱「OpenAPI 3.x 功能限制」。

後續步驟