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 per le nuove funzionalità 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 tu possa definire più server, API Gateway prende in considerazione solo il server che contiene l'estensione x-google-endpoint e ne consente solo uno. Per API Gateway, non è necessario un URL del server, quindi puoi non definire alcun server 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 uno contiene un server con l'estensione x-google-endpoint, anche tutti gli altri file devono avere 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 basepath autonomi perché non è richiesto un nome host nella specifica. Questo comportamento è diverso da quello standard di OpenAPI, che risolve gli URL relativi rispetto al server che ospita la definizione OpenAPI. Ad esempio, API Gateway considera url: /v1 come basepath.

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 conteggio dei file di 50 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 conteggio degli 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 Server-Sent Events (SSE) delle chiamate di strumenti a esecuzione prolungata non è supportato.
Richieste batch: gli array batch JSON-RPC vengono rifiutati.
Payload multimodali: le risposte degli strumenti sono limitate al testo UTF-8. Le risposte binarie non sono supportate.
Assenza di stato: 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.
Limitazioni dell'autenticazione: il metodo tools/list supporta solo l'autenticazione JWT. L'autenticazione tramite chiave API non è supportata per questo metodo.
Nessuna annotazione dello strumento: suggerimenti come destructiveHint o readOnlyHint non vengono emessi nelle dichiarazioni degli strumenti.
Preflight CORS: la gestione automatica del preflight CORS (richieste OPTIONS) sul percorso /mcp non è gestita dal gateway.
Esclusione reciproca del routing dei modelli: non puoi utilizzare sia MCP che il routing dei modelli nella stessa configurazione API.
Risposte MCP non supportate: le operazioni che restituiscono corpi vuoti nella risposta, ad esempio le risposte HTTP 204, non sono supportate.
Rilevamento 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.

Limitazioni preesistenti

Questa sezione descrive le limitazioni riportate 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, non li controlla né li applica.

Più requisiti di sicurezza

Requisiti della chiave 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 lo supporta 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 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 le applica. API Gateway inoltra le richieste in entrata alla tua API indipendentemente da queste definizioni.

API Gateway supporta solo i 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.