Google Cloud API Gateway sai suoratoiston: mitä tarkistaa ennen siirtymää

Suoratoistava backend pitää yhteyden auki ja lähettää dataa osissa: esimerkiksi SSE voi välittää mallin vastaustekstiä sitä mukaa kuin sitä tuotetaan, ja WebSocket mahdollistaa kaksisuuntaisen viestinnän. Google julkisti 22. lokakuuta 2026 Cloud API Gatewayn suoratoiston julkisen esikatselun. Yhdyskäytävä voi välittää tällaisia vastauksia ja soveltaa pyyntöihin tuttuja todennus- ja havainnointisääntöjä; testausta varten on luotava uusi yhdyskäytävä, jonka suoratoistotila on käytössä.

Googlen ilmoituksessa luetellaan SSE, HTTP-vastausten suoratoisto ja chunked transfer encoding, WebSocketit sekä gRPC:n palvelimelta asiakkaalle ja kaksisuuntainen suoratoisto. HTTP-vastaukset välitetään asiakkaalle sitä mukaa kuin ne saapuvat backendiltä, myös NDJSON-muodossa. Näin suoratoistoreitit voidaan pitää saman API Gatewayn takana, joka palvelee jo tavallisia pyyntöjä.

Mitä API:ssa ja infrastruktuurissa muuttuu

Suoratoistotoiminnot eivät edellytä erillistä API-kuvausta tai määrityksen erityislaajennuksia. Esikatselussa suoratoistotila asetetaan yhdyskäytävää luotaessa lipulla --enable-streaming. Googlen mukaan API-avaimen ja JWT:n tarkistukset, backendin service account -todennus, reititys sekä Cloud Logging- ja Cloud Monitoring -integraatiot säilyvät.

Esikatselussa otetaan käyttöön myös ennakoitava isäntänimi, joka muodostuu yhdyskäytävän tunnisteesta, projektin numerosta ja alueesta. Osoitteen muoto on esimerkiksi GATEWAY_ID-PROJECT_NUMBER.REGION.gateway.dev. Sen voi lisätä etukäteen asiakkaan tai CI:n määrityksiin. Kun yhdyskäytävä luodaan uudelleen samalla tunnisteella, projektilla ja alueella, osoite säilyy samana.

Testaa muuttamatta tuotantoliikenteen reititystä

1. Valitse olemassa oleva backend. Aloita endpointista, joka lähettää jo SSE:tä tai HTTP-suoratoistovastauksen. Näin yhdyskäytävän toimintaa on helpompi arvioida erillään sovellukseen tehdyistä muutoksista.
2. Luo erillinen yhdyskäytävä. Suoratoisto otetaan käyttöön luontivaiheessa, eikä olemassa olevan yhdyskäytävän tilaa voi muuttaa. Käytä testiympäristöön sopivaa tunnistetta ja aluetta.
3. Määritä backendin aikaraja. SSE:n ja HTTP-suoratoiston oletusarvoinen pyyntöaikaraja on 15 sekuntia, ja suoratoisto suljetaan määritetyn ajan umpeutuessa. Aseta OpenAPI-määrityksessä backendille deadline, joka sopii käyttötapaukseesi: suoratoistoyhdyskäytävän dokumentaatiossa sallitaan enintään 3 600 sekunnin arvo. Huomioi myös backendin oma aikakatkaisu — esimerkiksi Cloud Run voi sulkea yhteyden aiemmin.
4. Tarkista backendin protokolla. gRPC edellyttää HTTP/2:ta (h2), WebSocketit HTTP/1.1:tä. SSE ja HTTP-suoratoisto toimivat HTTP/1.1:llä tai HTTP/2:lla; Google suosittelee näihin käyttötapauksiin HTTP/2:ta.
5. Varmista datan saapuminen. Tarkista, että asiakas saa ensimmäiset tapahtumat ennen koko vastauksen valmistumista. Testaa WebSocketilla viestintä molempiin suuntiin ja suunnittele, miten asiakkaat muodostavat yhteyden uudelleen yhteyden päätyttyä.
6. Tarkista käytännöt ja mittarit. Varmista suoratoistoreitin todennus, lokit ja pyyntörajoitukset. Request latency -mittari kuvaa koko suoratoiston kestoa, joten mittaa asiakkaalla erikseen aika ensimmäiseen tapahtumaan ja tapahtumien väliset viiveet.

WebSocketien ja gRPC:n oletusarvoinen viestitön aikaväli on dokumentaation mukaan 300 sekuntia. WebSocketissa alle 300 sekunnin aikarajaa ei sovelleta, ja yhteys suljetaan joka tapauksessa viimeistään 3 600 sekunnin kuluttua. SSE:hen ja HTTP-suoratoistoon sovelletaan määritettyä seinäkelloaikaa mittaavaa aikarajaa. Siksi pitkä request latency -aika ei yksin kerro, kuinka nopeasti käyttäjä näki ensimmäisen osan.

Julkisen esikatselun rajoitukset

Julkaisun yhteydessä suoratoistotilaa ei voi ottaa käyttöön Cloud Consolen tai Terraformin kautta. Suoratoistoa käyttävät yhdyskäytävät eivät myöskään ole yhteensopivia HTTP(S) Load Balancingin ja Serverless NEG:n kanssa, joten tähän ratkaisuun perustuvat mukautetut verkkotunnukset eivät ole käytettävissä. Google luettelee nämä ominaisuudet esikatselujakson tuleviksi lisäyksiksi. Tarkista suoratoiston määritysdokumentaatio ennen tuotantoreitityksen ja automaation suunnittelua.

Käytännöllinen ensimmäinen askel on ohjata uusi yhdyskäytävä olemassa olevaan suoratoistavaan backendiin, määrittää aikaraja selvästi ja verrata suoraa yhteyttä yhdyskäytävän kautta kulkevaan reittiin. Näin tiimi voi tarkistaa protokollan yhteensopivuuden, todennuksen ja todellisen ajan ensimmäiseen tapahtumaan muuttamatta API-sopimusta tai tuotantoliikennettä.