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

OpenAPI 3.x 功能限制

本文說明在 API Gateway 中使用 OpenAPI 3.x 時的功能限制。

如要進一步瞭解支援的 OpenAPI 規格版本，請參閱「OpenAPI 總覽」。

OpenAPI 3.x 的新限制

本節說明 OpenAPI 3.x 新功能的限制。

伺服器

OpenAPI 3.x 支援多個 server 物件，可定義主機和基本路徑。不過，API Gateway 依賴單一伺服器物件 (由 x-google-endpoint 擴充功能識別) 來設定服務。

雖然您可以定義多個伺服器，但 API Gateway 只會考量包含 x-google-endpoint 擴充功能的伺服器，且只允許一個這類伺服器。API Gateway 不需要伺服器網址，因此您可以不定義伺服器，也可以定義一個含有 x-google-endpoint 擴充功能的伺服器。

舉例來說，下列定義對 API Gateway 而言是有效的：

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

下列定義無效，因為包含多個 x-google-endpoint 擴充功能：

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

下列定義適用於 API Gateway，但 API Gateway 會忽略伺服器物件：

servers:
  - url: https://example.com

多個檔案中的伺服器

如果您上傳多個 OpenAPI 檔案，且其中一個檔案包含 x-google-endpoint 擴充功能的伺服器，則所有檔案也必須定義具有相同 x-google-endpoint 擴充功能的伺服器，且伺服器網址中的主機相同。檔案間的 basepath 可能不同。

相對網址

對於 API Gateway，servers 物件中的相對網址會視為自己的 basepath，因為規格中不需要主機名稱。這與標準 OpenAPI 行為不同，後者會根據代管 OpenAPI 定義的伺服器解析相對網址。舉例來說，API Gateway 會將 url: /v1 視為 basepath。

基本路徑開頭必須為「/」。如果網址沒有配置或開頭為「/」來表示基本路徑，API Gateway 會拒絕這類網址。

不支援的擴充功能

API Gateway 不支援 OpenAPI 3.x 的 x-google-allow 擴充功能。

檔案大小限制

API Gateway 會對上傳的 OpenAPI 3.x 檔案強制執行總大小上限 (10 MB) 和檔案數量上限 (50 個)。

MCP 限制

公開測試期間，Model Context Protocol (MCP) 支援功能有以下限制：

工具數量限制：每個閘道最多只能有 1,000 個 MCP 工具。
HTTP 方法：只有 GET、POST、PUT、PATCH 和 DELETE 作業可以公開為 MCP 工具。不支援 HEAD、OPTIONS 和 TRACE。
串流：系統不支援長時間執行的工具呼叫，以伺服器傳送事件 (SSE) 串流。
批次要求：系統會拒絕 JSON-RPC 批次陣列。
多模態酬載：工具回覆內容僅限 UTF-8 文字。不支援二進位回應。
無狀態性：導入作業是無狀態的，不會使用或維護工作階段 ID (例如 MCP-Session-Id)。
不支援的 MCP 方法：不支援 resources/*、prompts/*、sampling/*、completion/*、ping 和 logging/* 等專用方法，且會傳回 JSON-RPC 錯誤代碼 -32601。
沒有工具註解：工具宣告中不會發出 destructiveHint 或 readOnlyHint 等提示。
CORS 預檢：閘道不會管理 /mcp 路徑上自動處理的 CORS 預檢 (OPTIONS 要求)。
模型路徑互斥：您無法在同一個 API 設定中同時使用 MCP 和模型路徑。
不支援的 MCP 回應：不支援在回應中傳回空白主體的作業，例如 HTTP 204 回應。
結構定義探索：由於已知的設定處理限制，從 OpenAPI 規格衍生的複雜巢狀物件結構定義，可能無法在 tools/list 探索回應中完整或正確地呈現。

既有限制

本節說明從 OpenAPI 2.0 沿用至 OpenAPI 3.x 的限制。

忽略的範圍

雖然 API Gateway 接受 OpenAPI 文件，其中定義了安全機制物件中的範圍，但 API Gateway 不會檢查或強制執行這些範圍。

多項安全性要求

API 金鑰規定：如果其中一個架構是 API 金鑰，API Gateway 就不支援替代 (邏輯 OR) 安全性規定。不過，API Gateway 支援連詞 (邏輯 AND)，因此您可以同時要求 API 金鑰和 OAuth2 權杖。
OAuth2 規定：API Gateway 支援不同 OAuth2 安全性配置的替代 (邏輯 OR) 安全性規定。除非額外的安全防護要求是 API 金鑰，否則 API Gateway 不支援連詞 (邏輯 AND)。
選用安全性：您可以使用空白安全性需求 (- {}) 將 API 金鑰的安全性設為選用，但 API Gateway 不支援 OAuth 的這項功能。

驗證安全性定義

如果 OpenAPI 3.x 規格使用安全性需求，但 securityDefinitions 區段中沒有對應的定義，API Gateway 就會拒絕該規格。

網址路徑範本

API Gateway 僅支援代表完整路徑區隔的網址路徑範本參數，例如 /items/{itemId}。API Gateway 不支援與部分區隔對應的參數，例如 /items/prefix_{id}_suffix，且會拒絕這類參數。

參數、結構定義、要求主體和型別

API Gateway 接受含有各種參數和型別定義 (例如 required 參數和陣列格式) 的 OpenAPI 文件，但不會強制執行這些定義。無論這些定義為何，API Gateway 都會將傳入要求轉送至 API。

API Gateway 僅支援要求參數中的原始型別。

外部類型參考資料

API Gateway 不支援參照所提供 OpenAPI 文件以外的型別。舉例來說，API Gateway 不允許指向外部網址的 $ref，並會拒絕這類要求。

主機位址中的自訂通訊埠

API Gateway 不允許在 OpenAPI 文件的 servers.url 欄位中使用自訂連接埠。

YAML 別名限制

提交至 API Gateway 的 OpenAPI 說明文件最多可有 200 個 YAML 別名節點。