Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

OpenAPI 3.x 功能限制

本文档介绍了将 OpenAPI 3.x 与 API Gateway 搭配使用时的功能限制。

如需详细了解支持的 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 文件强制执行 10MB 的总大小限制和 50 个文件的数量限制。

MCP 限制

在公开试用功能期间，Model Context Protocol (MCP) 支持存在以下限制：

工具数量限制：每个网关最多只能有 1,000 个 MCP 工具。
HTTP 方法：只有 GET、POST、PUT、PATCH 和 DELETE 操作可以作为 MCP 工具公开。不支持 HEAD、OPTIONS 和 TRACE。
流式传输：不支持对长时间运行的工具调用进行服务器发送事件 (SSE) 流式传输。
批量请求：JSON-RPC 批量数组会被拒绝。
多模态载荷：工具响应仅限于 UTF-8 文本。不支持二进制响应。
无状态：实现是无状态的；不使用或维护会话标识符（例如 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 执行此操作。

安全定义验证

API Gateway 将拒绝使用安全要求的 OpenAPI 3.x 规范，而不会在 securityDefinitions 部分中提供相应的定义。

网址路径模板

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 别名节点。