Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Limitazioni delle funzionalità di OpenAPI 3.x

Questo documento descrive le limitazioni delle funzionalità per l'utilizzo di OpenAPI 3.x con API Gateway.

Per ulteriori informazioni sulle versioni supportate della specifica OpenAPI, consulta la panoramica di OpenAPI.

Nuove limitazioni di OpenAPI 3.x

Questa sezione descrive le limitazioni delle funzionalità nuove di OpenAPI 3.x.

Server

OpenAPI 3.x supporta più oggetti server per definire host e percorsi di base. Tuttavia, API Gateway si basa su un singolo oggetto server, identificato dall'estensione x-google-endpoint, per configurare il servizio.

Sebbene sia possibile definire più server, API Gateway considera solo il server che contiene l'estensione x-google-endpoint e consente un solo server di questo tipo. Per API Gateway, non è richiesto un URL del server, quindi puoi non avere server definiti o un server con l'estensione x-google-endpoint.

Ad esempio, le seguenti definizioni sono valide per API Gateway:

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

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

La seguente definizione non è valida perché contiene più estensioni x-google-endpoint:

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

La seguente definizione è valida per API Gateway, ma API Gateway ignora l'oggetto server:

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

Server in più file

Se carichi più file OpenAPI e un file contiene un server con l'estensione x-google-endpoint, tutti i file devono avere anche un server definito con un'estensione x-google-endpoint identica e un host identico nell'URL del server. Il percorso di base può variare tra i file.

URL relativo

Per API Gateway, gli URL relativi nell'oggetto servers vengono trattati come un percorso di base autonomo perché nella specifica non è richiesto un nome host. Questo comportamento è diverso da quello standard di OpenAPI, che risolve gli URL relativi in base al server che ospita la definizione OpenAPI. Ad esempio, API Gateway tratta url: /v1 come un percorso di base.

I percorsi di base devono iniziare con "/". API Gateway rifiuta gli URL che non hanno uno schema o che iniziano con "/" per indicare un percorso di base.

Estensioni non supportate

API Gateway non supporta l'estensione x-google-allow per OpenAPI 3.x.

Limiti di dimensione dei file

API Gateway applica un limite di dimensioni totali di 10 MB e un limite di 50 file per i file OpenAPI 3.x caricati.

Limitazioni di MCP

Durante l'Anteprima pubblica, al supporto del Model Context Protocol (MCP) si applicano le seguenti limitazioni:

Limite del numero di strumenti: i clienti possono utilizzare un massimo di 1000 strumenti MCP per Gateway.
Metodi HTTP: solo le operazioni GET, POST, PUT, PATCH e DELETE possono essere esposte come strumenti MCP. HEAD, OPTIONS e TRACE non sono supportati.
Streaming: lo streaming di Server-Sent Events (SSE) di chiamate di strumenti a lunga esecuzione non è supportato.
Richieste batch: gli array batch JSON-RPC vengono rifiutati.
Payload multimodali: le risposte dello strumento sono limitate al testo UTF-8. Le risposte binarie non sono supportate.
Stateless: l'implementazione è stateless; gli identificatori di sessione (come MCP-Session-Id) non vengono utilizzati o gestiti.
Metodi MCP non supportati: i metodi specializzati come resources/*, prompts/*, sampling/*, completion/*, ping e logging/* non sono supportati e restituiscono un codice di errore JSON-RPC -32601.
Nessuna annotazione dello strumento: i suggerimenti come destructiveHint o readOnlyHint non vengono emessi nelle dichiarazioni dello strumento.
Preflight CORS: la gestione automatica del preflight CORS (richieste OPTIONS) sul percorso /mcp non è gestita dal gateway.
Esclusione reciproca del routing del modello: non puoi utilizzare sia l'MCP sia il routing del modello nella stessa configurazione dell'API.
Risposte MCP non supportate: le operazioni che restituiscono corpi vuoti nella risposta, come le risposte HTTP 204, non sono supportate.
Rilevamento dello schema: gli schemi di oggetti nidificati complessi derivati dalla specifica OpenAPI potrebbero non essere visualizzati completamente o correttamente nella risposta di rilevamento di tools/list a causa di una limitazione nota dell'elaborazione della configurazione.
Nessuna notifica di modifica dell'elenco degli strumenti: il gateway non emette notifications/tools/list_changed. Dopo aver eseguito il deployment di una nuova configurazione API, i client devono chiamare nuovamente tools/list. Consulta Aggiorna gli strumenti MCP esposti.

Limitazioni preesistenti

Questa sezione descrive le limitazioni ereditate da OpenAPI 2.0 che si applicano anche a OpenAPI 3.x.

Ambiti ignorati

Sebbene API Gateway accetti documenti OpenAPI con ambiti definiti in un oggetto schema di sicurezza, API Gateway non controlla né applica questi ambiti.

Più requisiti di sicurezza

Requisiti delle chiavi API: API Gateway non supporta requisiti di sicurezza alternativi (OR logico) se uno degli schemi è una chiave API. Tuttavia, API Gateway supporta le congiunzioni (AND logico), che ti consentono di richiedere sia una chiave API sia un token OAuth2.
Requisiti OAuth2: API Gateway supporta requisiti di sicurezza alternativi (OR logico) per diversi schemi di sicurezza OAuth2. API Gateway non supporta le congiunzioni (AND logico), a meno che il requisito di sicurezza aggiuntivo non sia una chiave API.
Sicurezza facoltativa: puoi utilizzare un requisito di sicurezza vuoto (- {}) per rendere la sicurezza facoltativa per una chiave API, ma API Gateway non supporta questa opzione per OAuth.

Convalida della definizione di sicurezza

API Gateway rifiuterà una specifica OpenAPI 3.x che utilizza un requisito di sicurezza senza una definizione corrispondente nella sezione securityDefinitions.

Modelli di percorso dell'URL

API Gateway supporta solo i parametri del modello di percorso dell'URL che rappresentano interi segmenti di percorso, ad esempio /items/{itemId}. API Gateway non supporta e rifiuta i parametri corrispondenti a segmenti parziali, ad esempio /items/prefix_{id}_suffix.

Parametri, schemi, corpi delle richieste e tipi

API Gateway accetta documenti OpenAPI con varie definizioni di parametri e tipi (ad esempio, parametri required e formati di array), ma non li applica. API Gateway inoltra le richieste in entrata alla tua API indipendentemente da queste definizioni.

API Gateway supporta solo tipi primitivi nei parametri di richiesta.

Riferimenti a tipi esterni

API Gateway non supporta i riferimenti a tipi esterni al documento OpenAPI fornito. Ad esempio, API Gateway non consente e rifiuta un $ref che punta a un URL esterno.

Porta personalizzata nell'indirizzo host

API Gateway non consente porte personalizzate nel campo servers.url di un documento OpenAPI.

Limitazioni degli alias YAML

Un documento OpenAPI inviato ad API Gateway può avere un massimo di 200 nodi alias YAML.