Google Cloud API Gateway aggiunge lo streaming: cosa verificare prima della migrazione

Un backend in streaming mantiene aperta la connessione e trasmette i dati a blocchi: per esempio, SSE può inviare il testo della risposta di un modello man mano che viene generato, mentre WebSocket consente uno scambio bidirezionale. Il 22 ottobre 2026 Google ha annunciato l’anteprima pubblica dello streaming in Cloud API Gateway. Il gateway può inoltrare queste risposte e applicare alle richieste le consuete regole di autenticazione e gli strumenti di osservabilità; per fare una prova occorre creare un nuovo gateway con la modalità streaming attivata.

Il post di annuncio di Google elenca SSE, lo streaming delle risposte HTTP e il trasferimento chunked, WebSocket e lo streaming gRPC lato server e bidirezionale. Le risposte HTTP vengono trasmesse al client man mano che arrivano dal backend, anche in formato NDJSON. Questo permette di mantenere gli endpoint in streaming dietro lo stesso API Gateway che gestisce già le richieste ordinarie.

Cosa cambia nelle API e nell’infrastruttura

Per le operazioni in streaming non serve una descrizione API separata né estensioni speciali nella specifica. Nell’anteprima, la modalità streaming si imposta al momento della creazione del gateway con il flag --enable-streaming. Google dichiara che restano disponibili i controlli delle API key e dei JWT, l’autenticazione del backend tramite service account, il routing e l’integrazione con Cloud Logging e Cloud Monitoring.

L’anteprima introduce anche un nome host prevedibile, basato sull’ID del gateway, sul numero del progetto e sulla regione. Per esempio, il formato dell’indirizzo è GATEWAY_ID-PROJECT_NUMBER.REGION.gateway.dev. È possibile inserirlo in anticipo nella configurazione del client o della CI. Se il gateway viene ricreato con lo stesso ID, progetto e regione, l’indirizzo resta invariato.

Verifiche senza spostare il traffico di produzione

1. Scegliete un backend esistente. Iniziate da un endpoint che invia già SSE o una risposta HTTP in streaming: in questo modo sarà più facile distinguere il comportamento del gateway da eventuali modifiche all’applicazione.
2. Create un gateway separato. L’attivazione dello streaming viene stabilita al momento della creazione; non è possibile modificare la modalità di un gateway esistente. Usate un ID di test e una regione adatta.
3. Configurate il deadline del backend. Per SSE e lo streaming HTTP, il timeout predefinito della richiesta è di 15 secondi; il flusso si chiude allo scadere del tempo impostato. Nella configurazione OpenAPI, impostate per il backend un deadline adatto al vostro scenario: per un gateway in streaming, la documentazione consente un valore fino a 3600 secondi. Considerate anche il timeout del backend stesso: per esempio, Cloud Run potrebbe chiudere la connessione prima.
4. Verificate il protocollo del backend. gRPC richiede HTTP/2 (h2), mentre WebSocket richiede HTTP/1.1. SSE e lo streaming HTTP funzionano con HTTP/1.1 o HTTP/2; Google consiglia HTTP/2 per questi scenari.
5. Verificate l’arrivo dei dati. Assicuratevi che il client riceva i primi eventi prima che la risposta completa sia terminata. Per WebSocket, verificate lo scambio in entrambe le direzioni e valutate come far riconnettere i client dopo la chiusura della connessione.
6. Controllate policy e metriche. Verificate l’autenticazione, i log e i limiti delle richieste sull’endpoint in streaming. La metrica di latenza delle richieste misura l’intera durata del flusso: misurate quindi separatamente, sul client, il tempo al primo evento e gli intervalli tra gli eventi.

Per WebSocket e gRPC, la documentazione indica un intervallo predefinito senza messaggi di 300 secondi; per WebSocket non si applica un timeout inferiore a 300 secondi e la connessione termina comunque entro 3600 secondi. Per SSE e lo streaming HTTP si applica il deadline wall-clock configurato. Di conseguenza, un valore elevato della latenza delle richieste non indica da solo quanto rapidamente l’utente abbia visualizzato il primo frammento.

Limiti dell’anteprima pubblica

Al lancio, la modalità streaming non può essere attivata tramite Cloud Console o Terraform. Inoltre, i gateway con streaming abilitato non sono compatibili con HTTP(S) Load Balancing e Serverless NEG, quindi non sono disponibili i domini personalizzati che dipendono da questa configurazione. Google elenca queste funzionalità tra le possibili aggiunte future durante il periodo di anteprima. Prima di pianificare il routing in produzione e l’automazione, consultate la documentazione sulla configurazione dello streaming.

Un primo passo pratico consiste nell’indirizzare il nuovo gateway a un backend in streaming esistente, impostare esplicitamente il deadline e confrontare la connessione diretta con il percorso attraverso il gateway. Così il team può verificare la compatibilità del protocollo, l’autenticazione e il tempo effettivo al primo evento, senza modificare il contratto API né il traffico di produzione.