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

Este documento descreve as limitações de recursos ao usar a OpenAPI 3.x com o gateway de API.

Para mais informações sobre as versões da especificação OpenAPI com suporte, consulte Visão geral da OpenAPI.

Novas limitações da OpenAPI 3.x

Esta seção descreve as limitações dos recursos novos na OpenAPI 3.x.

Servidores

O 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, não é necessário um URL de servidor. Portanto, você pode 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 ele 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 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 começam com '/' para indicar um caminho de base.

Extensões não compatí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 aplica um limite de tamanho total de 10 MB e um limite de contagem de arquivos de 50 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 do Protocolo de Contexto de Modelo (MCP):

Limite de contagem de ferramentas: os clientes podem ter no máximo 1.000 ferramentas do 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: matrizes em lote JSON-RPC são rejeitadas.
Payloads multimodais: as respostas da ferramenta são limitadas a texto UTF-8. Respostas binárias não são aceitas.
Ausência de estado: a implementação não tem estado. Identificadores de sessão (como MCP-Session-Id) não são usados nem mantidos.
Métodos MCP indisponíveis: métodos especializados, como resources/*, prompts/*, sampling/*, completion/*, ping e logging/*, não são compatíveis e retornam um código de erro JSON-RPC -32601.
Restrições de autenticação: o método tools/list oferece suporte apenas à autenticação JWT. A autenticação de chave de API não é compatível com esse método.
Sem anotações de ferramentas: dicas como destructiveHint ou readOnlyHint não são emitidas em declarações de ferramentas.
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 do roteamento de modelos: não é possível usar o MCP e o roteamento de modelos na mesma configuração de API.
Respostas MCP indisponíveis: não há suporte para operações que retornam corpos vazios na resposta, como respostas HTTP 204.
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 tools/list devido a uma limitação conhecida no processamento de configuração.

Limitações pré-existentes

Esta seção descreve as limitações do OpenAPI 2.0 que também se aplicam ao OpenAPI 3.x.

Escopos ignorados

Embora o gateway de API aceite documentos 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 aceita requisitos de segurança alternativa (OR lógico) se um dos esquemas for uma chave de API. No entanto, o gateway de API aceita conjunções (AND lógico), o que permite exigir uma chave de API e um token OAuth2.
Requisitos do OAuth2: o gateway de API aceita requisitos de segurança alternativos (OR lógico) para diferentes esquemas de segurança do OAuth2. O gateway de API não aceita conjunções (AND lógico), a menos que o requisito de segurança adicional seja uma chave de API.
Segurança opcional: você pode 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 OAuth.

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

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

Modelos do caminho do URL

O gateway de API aceita apenas parâmetros de modelo de caminho do URL que representam segmentos de caminho inteiros, por exemplo, /items/{itemId}. O gateway de API não aceita nem 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 OpenAPI com várias definições de parâmetro e tipo (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 aceita 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.