Google Cloud API Gateway adiciona streaming: o que verificar antes da migração

Um backend de streaming mantém a conexão aberta e envia dados em partes: por exemplo, o SSE pode transmitir o texto da resposta de um modelo à medida que é gerado, enquanto o WebSocket permite comunicação nos dois sentidos. Em 22 de outubro de 2026, o Google anunciou a prévia pública de streaming no Cloud API Gateway. O gateway pode encaminhar essas respostas e aplicar às solicitações as regras habituais de autenticação e os recursos de observabilidade; para testar, será necessário criar um novo gateway com o modo de streaming ativado.

O anúncio do Google lista SSE, streaming de respostas HTTP e codificação de transferência em blocos (chunked transfer encoding), WebSockets, além de streaming gRPC do servidor e bidirecional. As respostas HTTP são entregues ao cliente à medida que chegam do backend, inclusive em NDJSON. Assim, é possível manter as rotas de streaming no mesmo API Gateway que já atende às solicitações comuns.

O que muda na API e na infraestrutura

As operações de streaming não exigem uma descrição de API separada nem extensões especiais na especificação. Na prévia, o modo de streaming é definido ao criar o gateway, com a flag --enable-streaming. O Google informa que continuam disponíveis as verificações de chave de API e JWT, a autenticação do backend por meio de uma conta de serviço, o roteamento e a integração com Cloud Logging e Cloud Monitoring.

A prévia também introduz um nome de host previsível, baseado no identificador do gateway, no número do projeto e na região. Por exemplo, o formato do endereço é GATEWAY_ID-PROJECT_NUMBER.REGION.gateway.dev. Ele pode ser incluído antecipadamente na configuração do cliente ou no CI. Recriar o gateway com o mesmo identificador, projeto e região mantém esse endereço.

Como testar sem redirecionar o tráfego de produção

1. Escolha um backend existente. Comece com um endpoint que já envie SSE ou uma resposta HTTP em streaming; assim, será mais fácil distinguir o comportamento do gateway de eventuais mudanças no aplicativo.
2. Crie um gateway separado. O streaming é ativado durante a criação; não é possível mudar o modo de um gateway existente. Use um identificador de teste e uma região adequada.
3. Configure o prazo limite do backend. Para SSE e streaming HTTP, o prazo padrão da solicitação é de 15 segundos; o fluxo é encerrado quando o prazo definido expira. Na configuração OpenAPI, defina deadline para o backend de acordo com o seu caso de uso: para um gateway de streaming, a documentação permite um valor de até 3600 segundos. Considere também o timeout próprio do backend — por exemplo, o Cloud Run pode encerrar a conexão antes.
4. Verifique o protocolo do backend. gRPC requer HTTP/2 (h2), e WebSockets requer HTTP/1.1. SSE e streaming HTTP funcionam com HTTP/1.1 ou HTTP/2; o Google recomenda HTTP/2 para esses casos.
5. Verifique a chegada dos dados. Confirme que o cliente recebe os primeiros eventos antes de a resposta completa terminar. Para WebSocket, teste a comunicação nos dois sentidos e planeje como os clientes se reconectarão após o término da conexão.
6. Confira as políticas e métricas. Verifique a autenticação, os registros e os limites de solicitações na rota de streaming. A métrica de latência da solicitação reflete a duração total do fluxo; por isso, meça separadamente, no cliente, o tempo até o primeiro evento e os intervalos entre eventos.

Para WebSockets e gRPC, a documentação define por padrão um intervalo de 300 segundos sem mensagens; no caso de WebSocket, não se aplica um prazo inferior a 300 segundos, e a conexão é encerrada, de qualquer forma, no máximo após 3600 segundos. Para SSE e streaming HTTP, aplica-se o prazo de relógio de parede configurado. Portanto, um valor alto no gráfico de latência da solicitação, por si só, não indica a rapidez com que o usuário recebeu o primeiro fragmento.

Limitações da prévia pública

No lançamento, não é possível ativar o modo de streaming pelo Cloud Console nem pelo Terraform. Além disso, gateways com streaming ativado não são compatíveis com HTTP(S) Load Balancing nem com Serverless NEG, o que inviabiliza domínios personalizados que dependam desse modelo. O Google lista esses recursos como possíveis adições futuras durante o período de prévia. Antes de planejar o roteamento de produção e a automação, consulte a documentação de configuração do streaming.

Um primeiro passo prático é direcionar o novo gateway a um backend de streaming existente, configurar explicitamente o prazo limite e comparar a conexão direta com a rota pelo gateway. Assim, a equipe pode verificar a compatibilidade do protocolo, a autenticação e o tempo real até o primeiro evento, sem alterar o contrato da API nem o tráfego de produção.