Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

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

本頁說明 OpenAPI 規格 3.x 的 Google 專屬擴充功能。

雖然提供的範例採用 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 文件中定義的作業建立關聯。
`ai`	`AI`	否	空白	設定人工智慧功能，包括模型路徑。
`mcp`	`MCP`或`bool`	否	空白	啟用或設定 Model Context Protocol (MCP) 功能。

`Metric` 個物件

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

下表說明 Metric 的欄位：

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

`Quota` 個物件

Quota 物件會定義配額限制。

下表說明 Quota 的欄位：

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

`QuotaLimit` 個物件

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

下表說明 QuotaLimit 的欄位：

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

`Backends` 個物件

必要。

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

下表說明 Backends 的欄位：

欄位	類型	必填	預設	說明
`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`	指定等待要求完整回應的秒數。超過期限的回覆會逾時。在 SSE 或分塊傳輸端點上，期限仍會限制整個串流的持續時間；在 gRPC 或 WebSocket 端點上，期限則會限制訊息之間的間隔。如要瞭解適用於各類要求的逾時時間，請參閱「設定串流截止時間」。期限最長可設為 3600 秒。非串流閘道會強制執行較低的 600 秒上限，並在建立或更新閘道時拒絕較高的期限，而不是在建立 API 設定時拒絕。
`protocol`	`string`	否	`http/1.1`	設定將要求傳送至後端的通訊協定。支援的值包括 `http/1.1` 和 `h2`。通訊協定規定取決於串流類型： - gRPC：您必須將通訊協定設為 `h2`。 - WebSocket：您必須使用 `http/1.1`。 - 伺服器傳送事件 (SSE) 和增量回應傳送：您可以使用 `http/1.1` 或 `h2`。建議使用 `h2`，提升效能。

`AI` 個物件

AI 物件會為服務設定人工智慧功能，例如模型路徑。

下表說明 AI 的欄位：

欄位	類型	必填	預設	說明
`models`	`Models`	否	空白	設定 AI 模型整合。

`Models` 個物件

Models 物件會定義模型專屬的設定。

下表說明 Models 的欄位：

欄位	類型	必填	預設	說明
`routing`	`Routing`	否	空白	設定模型路徑設定。

`Routing` 個物件

Routing 物件會定義模型路徑規則和路由器。

下表說明 Routing 的欄位：

欄位	類型	必填	預設	說明
`routers`	`map[string]Router`	否	空白	定義已命名的模型路由器。

`Router` 個物件

Router 物件會定義具名模型路由器。

下表說明 Router 的欄位：

欄位	類型	必填	預設	說明
`defaultModel`	`DefaultModel`	是	空白	當傳入要求不符合任何明確規則時，系統會使用這個必要備用模型目的地。
`rules`	`[Rule]`	否	空白	明確模型轉送規則清單。

`DefaultModel` 個物件

DefaultModel 物件會指定備用目的地。

下表說明 DefaultModel 的欄位：

欄位	類型	必填	預設	說明
`backend`	`string`	是	空白	參照 `x-google-api-management.backends` 中宣告的後端。
`targetModel`	`string`	是	空白	以 `<provider>/<model-id>` 格式指定目標模型 ID。如果是相容於 OpenAI 的路徑，發生回溯時，這個值會以要求主體中的外送 `model` 屬性轉送。

`Rule` 個物件

Rule 物件會定義明確的模型路徑規則。

下表說明 Rule 的欄位：

欄位	類型	必填	預設	說明
`model`	`string`	是	空白	傳入的字串與用戶端 JSON 酬載中的 `model` 屬性相符。如果是相容於 OpenAI 的路徑，這個字串會轉送為要求主體中的外送 `model` 屬性，且必須是有效的 `<provider>/<model-id>` 字串。
`backend`	`string`	是	空白	參照 `x-google-api-management.backends` 中宣告的後端。
`targetModel`	`string`	是	空白	以 `<provider>/<model-id>` 格式指定目標模型 ID。這個值會選取供應商翻譯，並在回應的 `model` 欄位中回傳。

`MCP` 個物件

MCP 物件會為服務設定 Model Context Protocol (MCP) 功能。您可以將 mcp 設為布林值或物件。設為 true，即可為所有符合資格的作業啟用 MCP，並使用預設設定。

下表說明 MCP 物件的欄位：

欄位	類型	必填	預設	說明
`tools-list`	`ToolsList`	否	空白	設定 `tools/list` MCP 方法。

`ToolsList` 個物件

ToolsList 物件會設定 tools/list MCP 方法的設定。

下表說明 ToolsList 的欄位：

欄位	類型	必填	預設	說明
`security`	`map`	否	空白	啟用 `tools/list` 的驗證機制。強烈建議您設定這個選項，以確保安全性。必須為 `components.securitySchemes` 下定義的 JWT 安全性配置命名。公開測試版不支援 API 金鑰驗證。

`x-google-auth`

選用。

x-google-auth 擴充功能會在 Security Scheme Object 中定義驗證設定。

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

欄位	類型	必填	預設	說明
`issuer`	`string`	否	空白	指定憑證核發者。值可以是主機名稱或電子郵件地址。
`jwksUri`	`string`	否	空白	提供供應商公開金鑰集的 URI，以驗證 JSON Web Token 的簽章。API Gateway 支援這項 OpenAPI 擴充功能定義的兩種非對稱公開金鑰格式： JWK 集合格式。例如：`jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"` 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 擴充功能用於個別作業，可指定 x-google-api-management.metrics 中定義的哪些指標會受到該作業要求的影響。

x-google-quota 是包含鍵/值組合的物件，其中每個鍵都是指標名稱，值則是每個作業要求的整數費用。例如：

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

`x-google-backend`

必要。

x-google-backend 擴充功能會參照 x-google-api-management.backends 中定義的後端。使用時，其值必須是與 x-google-api-management.backends 中定義的後端名稱相符的字串。您必須為 API Gateway 設定這項擴充功能。您可以在 OpenAPI 文件的頂層定義這個擴充功能，也可以為個別作業定義，藉此覆寫頂層後端。

例如：

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

`x-google-model-router`

選用。

x-google-model-router 擴充功能會參照 x-google-api-management.ai.models.routing.routers 中定義的模型路由器。使用時，其值必須是與 x-google-api-management.ai.models.routing.routers 中定義的路由器名稱相符的字串。

這項擴充功能僅支援 OpenAPI 3.x 規格，無法搭配 OpenAPI 2.0 (Swagger) 規格使用。您只能在個別作業層級，為使用 POST HTTP 方法的作業定義這項擴充功能。您無法在同一項作業中同時指定 x-google-model-router 和 x-google-backend，也無法在同一項 API 規格中，混合使用不同路徑的模型路由和非模型路由作業。此外，您無法同時使用模型路徑和 Model Context Protocol (MCP)，啟用 x-google-api-management.mcp 會導致這項擴充功能無法使用。

例如：

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

`x-google-mcp-tool`

選用。

x-google-mcp-tool 擴充功能用於個別作業，可將作業公開為 MCP 工具，並視需要覆寫產生的工具名稱和說明。

這項擴充功能僅支援 OpenAPI 3.x 規格，無法搭配 OpenAPI 2.0 (Swagger) 規格使用。您只能在個別作業層級定義這項擴充功能。

接受布林值或物件。

布林值表單：設為 true 即可選擇啟用這項作業。設為 false 即可停用，並覆寫全域啟用設定。
物件表單：選擇加入並覆寫產生的工具設定。

下表說明 x-google-mcp-tool 做為物件時的欄位：

欄位	類型	必填	預設	說明
`name`	`string`	否	作業的 `operationId`	MCP 工具名稱。必須與 `[A-Za-z0-9_.-]{1,128}` 相符，且在規格中不得重複。
`description`	`string`	否	作業說明，如果沒有說明，則會改用摘要	MCP 工具說明。這是 LLM 選擇工具時使用的主要信號。

例如：

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

`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 功能限制」。

後續步驟

探索 OpenAPI 規格。
修改閘道，改用 OpenAPI 3.0。

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

x-google-api-management

Metric 個物件

Quota 個物件

QuotaLimit 個物件

Backends 個物件

AI 個物件

Models 個物件

Routing 個物件

Router 個物件

DefaultModel 個物件

Rule 個物件

MCP 個物件

ToolsList 個物件

x-google-auth

JwtLocations 個物件

x-google-quota

x-google-backend

x-google-model-router

x-google-mcp-tool

x-google-endpoint

x-google-parameter

瞭解 OpenAPI 擴充功能的限制

後續步驟

`x-google-api-management`

`Metric` 個物件

`Quota` 個物件

`QuotaLimit` 個物件

`Backends` 個物件

`AI` 個物件

`Models` 個物件

`Routing` 個物件

`Router` 個物件

`DefaultModel` 個物件

`Rule` 個物件

`MCP` 個物件

`ToolsList` 個物件

`x-google-auth`

`JwtLocations` 個物件

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-mcp-tool`

`x-google-endpoint`

`x-google-parameter`