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`	設定將要求代理至目標後端時的路徑轉譯策略。如果在頂層設定 `x-google-backend`，且未指定 `path_translation`，則預設 `pathTranslation` 為 `APPEND_PATH_TO_ADDRESS`。如果在作業層級設定 `x-google-backend`，且未指定 `path_translation`，則預設值為 `CONSTANT_ADDRESS`。
`deadline`	`double`	否	`15.0`	指定等待要求完整回應的秒數。超過這個期限的回應會逾時。在 SSE 或分塊傳輸端點上，期限仍會限制整個串流的時間長度；在 gRPC 或 WebSocket 端點上，期限則會限制訊息之間的間隔。請參閱「設定串流期限」，瞭解適用於各類要求的逾時時間。如要使用預設值，請省略這個欄位或設為 `0`。系統會拒絕負值。期限最長可設為 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 擴充功能會在安全性配置物件中定義驗證設定。

下表說明 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` 設為檔案的 URI，該檔案包含 base64url 編碼的金鑰字串。
`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)。
基本路徑：API 會使用伺服器上以 x-google-endpoint 設定的基本路徑。舉例來說，下列設定會將 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`