O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Limitações de recursos da OpenAPI 3.x

Neste documento, descrevemos as limitações de recursos para usar a OpenAPI 3.x com o gateway de API.

Para mais informações sobre as versões de especificação da OpenAPI compatíveis, consulte Visão geral da OpenAPI.

Novas limitações da OpenAPI 3.x

Nesta seção, descrevemos as limitações dos novos recursos da OpenAPI 3.x.

Servidores

A OpenAPI 3.x é compatível com vários objetos server para definir hosts e caminhos de base. No entanto, o gateway de API depende de um único objeto de servidor, identificado pela extensão x-google-endpoint, para configurar o serviço.

Embora seja possível definir vários servidores, o gateway de API considera apenas o servidor que contém a extensão x-google-endpoint e permite apenas um servidor desse tipo. Para o gateway de API, um URL de servidor não é obrigatório. Portanto, é possível não ter servidores definidos ou ter um servidor com a extensão x-google-endpoint.

Por exemplo, as seguintes definições são válidas para o gateway de API:

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

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

A definição a seguir é inválida porque contém várias extensões x-google-endpoint:

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

A definição a seguir é válida para o gateway de API, mas o gateway de API ignora o objeto do servidor:

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

Servidores em vários arquivos

Se você fizer upload de vários arquivos OpenAPI e um deles tiver um servidor com a extensão x-google-endpoint, todos os arquivos também precisarão ter um servidor definido com uma extensão x-google-endpoint idêntica e um host idêntico no URL do servidor. O caminho base pode ser diferente entre os arquivos.

URL relativo

Para o gateway de API, os URLs relativos no objeto servers são tratados como um caminho de base por conta própria, porque um nome de host não é necessário na especificação. Isso é diferente do comportamento padrão da OpenAPI, que resolve URLs relativos em relação ao servidor que hospeda a definição da OpenAPI. Por exemplo, o gateway de API trata url: /v1 como um caminho base.

Os caminhos de base precisam começar com "/". O gateway de API rejeita URLs que não têm um esquema ou que começam com "/" para indicar um caminho de base.

Extensões incompatíveis

O gateway de API não é compatível com a extensão x-google-allow para OpenAPI 3.x.

Limites do tamanho do arquivo

O gateway de API impõe um limite de tamanho total de 10 MB e um limite de 50 arquivos para arquivos OpenAPI 3.x enviados.

Limitações do MCP

Durante o pré-lançamento público, as seguintes limitações se aplicam ao suporte ao Protocolo de Contexto de Modelo (MCP):

Limite de ferramentas: os clientes podem ter no máximo 1.000 ferramentas MCP por gateway.
Métodos HTTP: somente as operações GET, POST, PUT, PATCH e DELETE podem ser expostas como ferramentas do MCP. HEAD, OPTIONS e TRACE não são compatíveis.
Streaming: o streaming de eventos enviados pelo servidor (SSE) de chamadas de ferramentas de longa duração não é compatível.
Solicitações em lote: as matrizes em lote JSON-RPC são rejeitadas.
Payloads multimodais: as respostas da ferramenta são limitadas a texto UTF-8. Não há suporte para respostas binárias.
Ausência de estado: a implementação não tem estado. Os identificadores de sessão (como MCP-Session-Id) não são usados nem mantidos.
Métodos MCP não compatíveis: métodos especializados, como resources/*, prompts/*, sampling/*, completion/*, ping e logging/*, não são compatíveis e retornam um código do erro JSON-RPC -32601.
Sem anotações de ferramenta: dicas como destructiveHint ou readOnlyHint não são emitidas em declarações de ferramenta.
Simulação do CORS: o processamento automatizado de simulação do CORS (solicitações OPTIONS) no caminho /mcp não é gerenciado pelo gateway.
Exclusão mútua de roteamento de modelos: não é possível usar o MCP e o roteamento de modelos na mesma configuração de API.
Respostas MCP não compatíveis: operações que retornam corpos vazios na resposta, como respostas HTTP 204, não são compatíveis.
Descoberta de esquema: esquemas de objetos aninhados complexos derivados da sua especificação OpenAPI podem não ser renderizados de forma completa ou correta na resposta de descoberta do tools/list devido a uma limitação conhecida de processamento de configuração.
Sem notificações de mudança na lista de ferramentas: o gateway não emite notifications/tools/list_changed. Depois de implantar uma nova configuração de API, os clientes precisam chamar tools/list novamente. Consulte Atualizar as ferramentas do MCP expostas.

Limitações preexistentes

Nesta seção, descrevemos as limitações da OpenAPI 2.0 que também se aplicam à OpenAPI 3.x.

Escopos ignorados

Embora o gateway de API aceite documentos da OpenAPI com escopos definidos em um objeto de esquema de segurança, ele não verifica nem aplica esses escopos.

Vários requisitos de segurança

Requisitos de chave de API: o gateway de API não é compatível com requisitos de segurança alternativos (OR lógico) se um dos esquemas for uma chave de API. No entanto, o gateway de API é compatível com conjunções (AND lógico), o que permite exigir uma chave de API e um token OAuth2.
Requisitos do OAuth2: o gateway de API é compatível com requisitos de segurança alternativos (OR lógico) para diferentes esquemas de segurança do OAuth2. O gateway de API não é compatível com conjunções (AND lógico), a menos que o requisito de segurança adicional seja uma chave de API.
Segurança opcional: é possível usar um requisito de segurança vazio (- {}) para tornar a segurança opcional para uma chave de API, mas o gateway de API não oferece suporte a isso para o OAuth.

Validação da definição de segurança

O gateway de API vai rejeitar uma especificação OpenAPI 3.x que use um requisito de segurança sem uma definição correspondente na seção securityDefinitions.

Modelos do caminho do URL

O gateway de API só aceita parâmetros de modelo de caminho de URL que representam segmentos de caminho inteiros, por exemplo, /items/{itemId}. O gateway de API não aceita e rejeita parâmetros correspondentes a segmentos parciais, por exemplo, /items/prefix_{id}_suffix.

Parâmetros, esquemas, corpos de solicitação e tipos

O gateway de API aceita documentos da OpenAPI com várias definições de parâmetros e tipos (por exemplo, parâmetros required e formatos de matriz), mas não os aplica. O gateway de API encaminha as solicitações recebidas para sua API, independentemente dessas definições.

O gateway de API aceita apenas tipos primitivos em parâmetros de solicitação.

Referências de tipo externo

O gateway de API não é compatível com referências a tipos fora do documento da OpenAPI fornecido. Por exemplo, o gateway de API não permite e rejeita um $ref que aponta para um URL externo.

Porta personalizada no endereço do host

O gateway de API não permite portas personalizadas no campo servers.url de um documento da OpenAPI.

Limitações de alias do YAML

Um documento da OpenAPI enviado ao gateway de API pode ter no máximo 200 nós de alias YAML.