Recopilaciones · GET /v1/collections/{id}/stream
Progreso en vivo
Mira cómo se llena una recopilación en una sola conexión abierta: los lugares a medida que llegan, cuánto avanzó y los conteos finales.
Abre el stream
El stream usa server-sent events: una respuesta HTTP que se mantiene abierta, y cada vez que pasa algo escribimos en ella un evento corto de texto. Se abre con tu clave, igual que cualquier otra llamada, y es gratis. Con curl, -N muestra cada evento en cuanto llega, en lugar de esperar al final:
curl -N https://api.gmaps.dev/v1/collections/8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31/stream \
-H "Authorization: Bearer $GMAPS_API_KEY"Qué llega
Cada evento tiene una línea event con su tipo, una línea data con JSON y, casi siempre, una línea id. Una recopilación pequeña se ve así, con el lugar recortado:
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 | Cuándo llega |
|---|---|---|
plan | squaresTotal, squaresCovered, jobsTotal | Primero. Cómo se dividió la zona, con los mismos números que tiene la recopilación. |
status | status | Una vez, cuando empieza la primera búsqueda. |
place | place, cached, cost | Cada vez que llega un lugar. cost es lo que te costó: 0 si ya lo teníamos, 1 si es un lugar nuevo y 2 si además encontramos un correo electrónico para él. |
progress | jobsDone, jobsTotal, counts | Después de cada lote de cuadros, con los counts de la recopilación hasta ese momento. |
done | status, counts | Al final. La recopilación terminó, con su estado y sus conteos finales. El stream se cierra justo después. |
heartbeat | Nada | Más o menos cada 15 segundos, para que una conexión inactiva no se cierre por el camino. No tiene id. Puedes ignorarlo. |
error | code, message | Algo falló de nuestro lado mientras el stream estaba abierto. El stream se cierra justo después: vuelve a conectarte desde tu último id. |
notice | messageKey, params | Reservado para una nota sobre la recopilación. Todavía no lo enviamos. |
Ignora los tipos de evento que no conozcas, para que uno nuevo nunca rompa tu código.
No todos los lugares llegan como evento. Los lugares que ya teníamos cuando empezó la recopilación están en ella desde el primer momento, así que nunca llegan por aquí. Tampoco llega un lugar cuyo negocio pidió que lo excluyéramos. Además, una recopilación grande deja de enviar eventos place después de cierto número de lugares, mientras sus eventos progress siguen contando. Cuando termina, lee todos los lugares en la propia recopilación, como muestra Recopilaciones.
Continúa donde te quedaste
Guardamos todos los eventos que tienen id. Si la conexión se cae, vuelve a conectarte con el último id que leíste en un encabezado Last-Event-ID, y recibes solo los eventos posteriores. Si es difícil enviar un encabezado, también sirve ?lastEventId= en la dirección. Sin ninguno de los dos, recibes todos los eventos desde el principio, así que conectarte tarde no te hace perder 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"El SDK lo hace por ti. Cuando la conexión se cae, se conecta de nuevo desde el último evento que te entregó. Pasa lastEventId para empezar después de un evento que ya tienes, y un signal para dejar de seguirla.
Después de maxRetries caídas, se rinde y lanza un GmapsError. retryMs define cuánto espera entre un intento y otro. Un rechazo, como una clave incorrecta o la recopilación de otra cuenta, lanza el error de inmediato.
Cuándo termina
Después de done, el stream se cierra. No hay nada más que seguir.
También cerramos un stream después de 15 minutos, aunque la recopilación siga en curso. No es un error: vuelve a conectarte con tu último id.
Si la recopilación ya había terminado cuando te conectas, recibes de golpe sus eventos hasta done, y luego el stream se cierra. Cuando sus lugares se eliminan, 30 días después de que empezó, recibes un solo evento done con los conteos finales.
Si el stream no puede abrirse, recibes un error JSON normal: 404 COLLECTION_NOT_FOUND si el id es incorrecto o es de otra cuenta, 401 UNAUTHORIZED cuando falta la clave y 401 INVALID_TOKEN cuando es incorrecta o fue revocada. Errores los lista todos.
Otras formas de seguir una recopilación
No siempre quieres mantener una conexión abierta. También puedes:
- leer la recopilación en
GET /v1/collections/{id}cada cierto tiempo. Sustatusy suscountsdicen lo mismo que los eventos, y no hace falta dejar nada abierto. - usar un webhook: en los planes de pago, enviamos una solicitud a tu servidor cuando termina una recopilación, salvo que la hayas cancelado.