Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Limitaciones de las funciones de OpenAPI 3.x

En este documento, se describen las limitaciones de las funciones para usar OpenAPI 3.x con API Gateway.

Para obtener más información sobre las versiones compatibles de la especificación de OpenAPI, consulta Descripción general de OpenAPI.

Nuevas limitaciones de OpenAPI 3.x

En esta sección, se describen las limitaciones de las funciones nuevas en OpenAPI 3.x.

Servidores

OpenAPI 3.x admite varios objetos server para definir hosts y rutas de acceso base. Sin embargo, API Gateway se basa en un solo objeto de servidor, identificado por la extensión x-google-endpoint, para configurar el servicio.

Si bien puedes definir varios servidores, API Gateway solo considera el servidor que contiene la extensión x-google-endpoint y permite solo uno de esos servidores. Para API Gateway, no se requiere una URL de servidor, por lo que puedes no tener servidores definidos o tener un servidor con la extensión x-google-endpoint.

Por ejemplo, las siguientes definiciones son válidas para API Gateway:

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

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

La siguiente definición no es válida porque contiene varias extensiones x-google-endpoint:

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

La siguiente definición es válida para API Gateway, pero API Gateway ignora el objeto del servidor:

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

Servidores en varios archivos

Si subes varios archivos de OpenAPI y uno de ellos contiene un servidor con la extensión x-google-endpoint, todos los archivos también deben tener un servidor definido con una extensión x-google-endpoint idéntica y un host idéntico en la URL del servidor. La ruta de acceso base puede variar entre los archivos.

URL relativa

En el caso de API Gateway, las URLs relativas del objeto servers se tratan como una ruta de acceso base por sí solas, ya que no se requiere un nombre de host en la especificación. Esto es diferente del comportamiento estándar de OpenAPI, que resuelve las URLs relativas en función del servidor que aloja la definición de OpenAPI. Por ejemplo, API Gateway trata url: /v1 como una ruta de acceso base.

Las rutas de acceso base deben comenzar con "/". API Gateway rechaza las URLs que no tienen un esquema o que comienzan con "/" para indicar una ruta de acceso base.

Extensiones no admitidas

API Gateway no admite la extensión x-google-allow para OpenAPI 3.x.

Límites de tamaño de archivo

API Gateway aplica un límite de tamaño total de 10 MB y un límite de 50 archivos para los archivos OpenAPI 3.x subidos.

Limitaciones del MCP

Durante la versión preliminar pública, se aplican las siguientes limitaciones a la compatibilidad con el Protocolo de contexto del modelo (MCP):

Límite de cantidad de herramientas: Los clientes tienen un límite de 1,000 herramientas de MCP por puerta de enlace.
Métodos HTTP: Solo las operaciones GET, POST, PUT, PATCH y DELETE se pueden exponer como herramientas de MCP. No se admiten HEAD, OPTIONS ni TRACE.
Transmisión: No se admite la transmisión de eventos enviados por el servidor (SSE) de llamadas a herramientas de larga duración.
Solicitudes por lotes: Se rechazan los arrays por lotes de JSON-RPC.
Cargas útiles multimodales: Las respuestas de las herramientas se limitan a texto UTF-8. No se admiten las respuestas binarias.
Sin estado: La implementación no tiene estado; no se usan ni se mantienen los identificadores de sesión (como MCP-Session-Id).
Métodos de MCP no admitidos: No se admiten métodos especializados como resources/*, prompts/*, sampling/*, completion/*, ping y logging/*, y devuelven un código de error de JSON-RPC -32601.
Sin anotaciones de herramientas: No se emiten sugerencias como destructiveHint o readOnlyHint en las declaraciones de herramientas.
Verificación previa de CORS: La puerta de enlace no administra el control automatizado de la verificación previa de CORS (solicitudes OPTIONS) en la ruta de acceso /mcp.
Exclusión mutua del enrutamiento a modelos: No puedes usar el MCP y el enrutamiento a modelos en la misma configuración de la API.
Respuestas de MCP no compatibles: No se admiten las operaciones que devuelven cuerpos vacíos en la respuesta, como las respuestas HTTP 204.
Detección de esquemas: Es posible que los esquemas de objetos anidados complejos derivados de tu especificación de OpenAPI no se rendericen por completo o de forma correcta en la respuesta de descubrimiento de tools/list debido a una limitación conocida en el procesamiento de la configuración.
No hay notificaciones de cambio de lista de herramientas: La puerta de enlace no emite notifications/tools/list_changed. Después de implementar una nueva configuración de API, los clientes deben volver a llamar a tools/list. Consulta Cómo actualizar las herramientas de MCP expuestas.

Limitaciones preexistentes

En esta sección, se describen las limitaciones heredadas de OpenAPI 2.0 que también se aplican a OpenAPI 3.x.

Alcances ignorados

Aunque API Gateway acepta documentos de OpenAPI con permisos definidos en un objeto de esquema de seguridad, no los verifica ni los aplica.

Varios requisitos de seguridad

Requisitos de la clave de API: API Gateway no admite requisitos de seguridad alternativos (OR lógico) si uno de los esquemas es una clave de API. Sin embargo, API Gateway admite conjunciones (AND lógico), lo que te permite requerir una clave de API y un token de OAuth2.
Requisitos de OAuth2: API Gateway admite requisitos de seguridad alternativos (OR lógico) para diferentes esquemas de seguridad de OAuth2. API Gateway no admite conjunciones (AND lógico), a menos que el requisito de seguridad adicional sea una clave de API.
Seguridad opcional: Puedes usar un requisito de seguridad vacío (- {}) para que la seguridad sea opcional para una clave de API, pero API Gateway no admite esto para OAuth.

Validación de la definición de seguridad

API Gateway rechazará una especificación de OpenAPI 3.x que use un requisito de seguridad sin una definición correspondiente en la sección securityDefinitions.

Plantillas de ruta de URL

API Gateway solo admite parámetros de plantilla de ruta de URL que representen segmentos de ruta completos, por ejemplo, /items/{itemId}. API Gateway no admite y rechaza los parámetros que corresponden a segmentos parciales, por ejemplo, /items/prefix_{id}_suffix.

Parámetros, esquemas, cuerpos de solicitud y tipos

API Gateway acepta documentos de OpenAPI con varias definiciones de parámetros y tipos (por ejemplo, parámetros required y formatos de array), pero no los aplica. API Gateway reenvía las solicitudes entrantes a tu API, independientemente de estas definiciones.

API Gateway solo admite tipos primitivos en los parámetros de solicitud.

Referencias a tipos externos

API Gateway no admite referencias a tipos fuera del documento de OpenAPI proporcionado. Por ejemplo, API Gateway no permite y rechaza un $ref que apunta a una URL externa.

Puerto personalizado en la dirección del host

API Gateway no permite puertos personalizados en el campo servers.url de un documento de OpenAPI.

Limitaciones de los alias de YAML

Un documento de OpenAPI enviado a API Gateway puede tener un máximo de 200 nodos de alias de YAML.