Coletas · GET /v1/collections/{id}/stream

Progresso ao vivo

Acompanhe a coleta numa só conexão aberta: os lugares conforme chegam, quanto ela já andou e as contagens finais.

Abra o stream

O stream usa server-sent events: uma resposta HTTP que fica aberta, e a cada novidade escrevemos nela um evento curto, em texto. Ele usa a sua chave como qualquer outra chamada e é de graça. No curl, o -N mostra cada evento assim que ele chega, em vez de esperar o fim:

curl -N https://api.gmaps.dev/v1/collections/8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31/stream \
  -H "Authorization: Bearer $GMAPS_API_KEY"

O que chega

Cada evento tem uma linha event com o tipo, uma linha data com JSON e, quase sempre, uma linha id. Uma coleta pequena fica assim, com o lugar encurtado:

event: plan
data: {"squaresTotal":3,"squaresCovered":1,"jobsTotal":2}
id: 1

event: status
data: {"status":"running"}
id: 2

event: place
data: {"place":{"id":"5b0c8e0a-2f4d-4c1e-9a57-3d2b8f6e1c90","identity":{"name":"Padaria Estrela do Centro"}},"cached":false,"cost":1}
id: 3

event: progress
data: {"jobsDone":1,"jobsTotal":2,"counts":{"placesDelivered":13,"placesFresh":1,"placesCached":12,"creditsCharged":1,"creditsRefunded":0}}
id: 4

event: heartbeat
data: {}

event: progress
data: {"jobsDone":2,"jobsTotal":2,"counts":{"placesDelivered":13,"placesFresh":1,"placesCached":12,"creditsCharged":1,"creditsRefunded":0}}
id: 5

event: done
data: {"status":"succeeded","counts":{"placesDelivered":13,"placesFresh":1,"placesCached":12,"creditsCharged":1,"creditsRefunded":0}}
id: 6

event	data	Quando chega
`plan`	`squaresTotal`, `squaresCovered`, `jobsTotal`	Primeiro. Como a região foi dividida, com os mesmos números da coleta.
`status`	`status`	Uma vez, quando a primeira busca começa.
`place`	`place`, `cached`, `cost`	A cada lugar que chega. O `cost` é quanto ele custou para você: 0 quando já tínhamos o lugar, 1 para um lugar novo e 2 quando também encontramos um e-mail dele.
`progress`	`jobsDone`, `jobsTotal`, `counts`	Depois de cada lote de quadrados, com o `counts` da coleta até ali.
`done`	`status`, `counts`	Por último. A coleta terminou, com o status e as contagens finais. O stream fecha logo em seguida.
`heartbeat`	Nada	Mais ou menos a cada 15 segundos, para que uma conexão parada não seja fechada no caminho. Não tem `id`. Pode ignorar.
`error`	`code`, `message`	Algo deu errado do nosso lado com o stream aberto. O stream fecha logo em seguida: conecte de novo a partir do seu último `id`.
`notice`	`messageKey`, `params`	Reservado para um aviso sobre a coleta. Ainda não mandamos.

Ignore os tipos de evento que você não conhece, para que um tipo novo nunca quebre o seu código.

Nem todo lugar chega como evento. Os lugares que já tínhamos quando a coleta começou estão nela desde o primeiro momento, então nunca chegam por aqui. Um lugar cuja empresa pediu para ficar de fora também não chega. Uma coleta grande também para de mandar eventos place depois de um certo número de lugares, e os eventos progress continuam contando. Quando ela terminar, leia todos os lugares na própria coleta, como mostra Coletas.

Continue de onde parou

Guardamos todo evento que tem id. Se a conexão cair, conecte de novo com o último id que você leu no cabeçalho Last-Event-ID, e só chegam os eventos depois dele. Se for difícil mandar um cabeçalho, ?lastEventId= no endereço também funciona. Sem nenhum dos dois, chegam todos os eventos desde o começo, então conectar tarde não perde nada:

curl -N https://api.gmaps.dev/v1/collections/8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31/stream \
  -H "Authorization: Bearer $GMAPS_API_KEY" \
  -H "Last-Event-ID: 4"

O SDK faz isso por você. Quando a conexão cai, ele conecta de novo a partir do último evento que entregou. Passe lastEventId para começar depois de um evento que você já tem, e um signal para parar de acompanhar.

Depois de maxRetries quedas, ele desiste e lança um GmapsError. O retryMs define quanto ele espera entre uma tentativa e outra. Uma recusa, como uma chave errada ou a coleta de outra conta, lança o erro na hora.

Quando termina

Depois do done, o stream fecha. Não há mais nada para acompanhar.

Também fechamos um stream depois de 15 minutos, mesmo com a coleta ainda rodando. Não é erro: conecte de novo com o seu último id.

Se a coleta já tinha terminado quando você conectou, os eventos dela até o done chegam de uma vez, e o stream fecha. Depois que os lugares dela são apagados, 30 dias após o início, chega um único evento done com as contagens finais.

Se o stream não abrir, vem um erro JSON comum: 404 COLLECTION_NOT_FOUND para um id errado ou de outra conta, 401 UNAUTHORIZED quando falta a chave e 401 INVALID_TOKEN quando ela está errada ou foi revogada. A página Erros lista todos.

Outras formas de acompanhar

Nem sempre você quer uma conexão aberta. Você também pode:

ler a coleta em GET /v1/collections/{id} de tempos em tempos. O status e o counts dizem o mesmo que os eventos, e nada precisa ficar aberto.
usar um webhook: nos planos pagos, mandamos uma requisição para o seu servidor quando uma coleta termina, a não ser que você a tenha cancelado.