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 擴充功能的伺服器，且伺服器網址中的主機也必須相同。基本路徑可能因檔案而異。

相對網址

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

基本路徑必須以「/」開頭。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 探索回應中完整或正確顯示。
沒有工具清單變更通知：閘道不會發出 notifications/tools/list_changed。部署新的 API 設定後，用戶端必須再次呼叫 tools/list。請參閱「更新公開的 MCP 工具」。

既有限制

本節說明 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 Gateway 不支援連詞 (邏輯 AND)，除非額外的安全性需求是 API 金鑰。
選用安全性：您可以使用空白安全性需求 (- {})，將 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 別名節點。