Envío agrupado (batch)¶
La aplicación Driver envía sus solicitudes de escritura una a una mientras la red lo permite, y por lotes cuando se ha acumulado una cola: posiciones, transiciones de parada, eventos de servicio. Un lote sale en una sola llamada, que el servidor ejecuta solicitud tras solicitud antes de responder a todas a la vez.
| Endpoint | Función |
|---|---|
POST /nav-data-processor-api/batch |
Ejecuta un lote de subsolicitudes y responde a cada una |
El endpoint no está versionado y solo existe en la especificación interna: la aplicación Driver es su único cliente.
La solicitud¶
El cuerpo va en multipart/form-data o en application/x-www-form-urlencoded. Cada subsolicitud es un grupo de campos que comparten el mismo prefijo antes de su último punto. La aplicación Driver nombra sus grupos request[0], request[1]… El servidor ejecuta los grupos en el orden en que aparece su primer campo.
| Campo | Función |
|---|---|
method |
Método HTTP de la subsolicitud (obligatorio) |
path |
Ruta completa, prefijo incluido, por ejemplo /nav-data-processor-api/v1/groups/<group_id>/devices/<device_id>/location (obligatorio) |
queryString |
Parámetros de consulta, sin el ? inicial |
contentType, body |
Tipo y contenido del cuerpo, como campo de texto o como parte de archivo |
id |
Identificador que se repite en la respuesta; por defecto, la posición del grupo en el lote, a partir de 0 |
continueOnError, continueOnErrorStatus |
Continuar el lote tras una respuesta fuera de 2xx: siempre (true), o para los estados indicados, separados por comas |
idempotencyKey |
Clave de idempotencia de la subsolicitud, transmitida a su ruta como la cabecera Idempotency-Key (consulte Los reintentos) |
Una subsolicitud hereda las cabeceras del lote (Authorization, User-Agent…), salvo Content-Type, Content-Length, Connection, Idempotency-Key y x-pysae-api-request-id: estas dos últimas designan una única solicitud y, compartidas por todo el lote, harían que la segunda subsolicitud respondiera con la respuesta de la primera. Su ruta de destino la autoriza como una llamada directa, versión mínima de Driver incluida: el lote no exige ningún rol por sí mismo.
Un cuerpo ausente, ilegible o de otro tipo recibe un 400 INVALID_BATCH_REQUEST, cuyo campo accepted_content_types enumera los tipos aceptados.
El presupuesto del lote¶
El parámetro timeout indica, en segundos, el plazo a partir del cual el cliente abandona la llamada. Vale 60 por defecto, el plazo de la aplicación Driver. Un valor que no sea un número positivo finito vuelve a este valor por defecto.
El servidor dedica el 75 % de este plazo a las subsolicitudes, es decir, 45 s por defecto, y reserva el resto para devolver la respuesta. Antes de lanzar una subsolicitud, estima su duración: la de la subsolicitud más larga del lote hasta ese momento, incrementada en un 50 %. Si el tiempo ya transcurrido más esta estimación supera el presupuesto, no lanza ni esa subsolicitud ni las siguientes. La primera subsolicitud siempre se ejecuta, a falta de medición.
Una subsolicitud lanzada se espera como máximo hasta el final del presupuesto. Si dura más, el servidor responde sin ella y no lanza las siguientes. Sin embargo, no se cancela: llega a su fin en segundo plano, y su efecto se aplica una sola vez.
La respuesta¶
La respuesta es siempre un 200 en multipart/form-data, con un grupo de campos por subsolicitud, con el prefijo response[<id>].
| Campo | Función |
|---|---|
id |
Identificador de la subsolicitud |
status, contentType, body |
Respuesta de una subsolicitud ejecutada; body no aparece para un estado sin cuerpo (204, 304…) |
skipped |
true para una subsolicitud cuya respuesta el servidor no devuelve: el cliente la reenvía |
skipReason |
Causa de una subsolicitud skipped (consulte más abajo) |
Una subsolicitud skipped no lleva ni status, ni contentType, ni body. Su campo skipReason indica la causa:
skipReason |
Causa | ¿Aplicada? |
|---|---|---|
budget |
No lanzada, por falta de presupuesto | No |
previous_error |
No lanzada, tras una subsolicitud anterior que respondió fuera de 2xx sin continueOnError ni su estado en continueOnErrorStatus |
No |
interrupted |
Lanzada, pero no terminada dentro del presupuesto | Quizá: termina en segundo plano |
En los tres casos, el cliente mantiene la subsolicitud en cola y la reenvía en el siguiente envío. Una subsolicitud interrupted quizá se haya aplicado: una ruta que declara la idempotencia devuelve entonces su respuesta original al reenvío, o un error IDEMPOTENCY_KEY_IN_PROGRESS si aún se está ejecutando (consulte Los reintentos).
Una respuesta enviada después del plazo del cliente se registra como error en el servidor, con el detalle de cada subsolicitud. El cliente no la lee y reenvía el lote completo.
Los reintentos¶
Un lote reenviado contiene subsolicitudes que el servidor ya ha aplicado. Las rutas que declaran la idempotencia las reconocen y devuelven su respuesta original sin volver a procesarlas: son todas las rutas de escritura que Driver pone en cola y vuelve a enviar.
Una solicitud se reconoce por su clave:
- la clave de idempotencia enviada por el cliente, en la cabecera
Idempotency-Keyde una llamada directa, o en el campoidempotencyKeyde una subsolicitud. Se genera una vez por solicitud, al ponerla en cola, y se mantiene igual de un intento a otro; - en su defecto, una clave que la ruta obtiene de la solicitud, cuando dispone de una. Una marca de tiempo se redondea en ella al milisegundo.
Las rutas de servicio a demanda aceptan también la clave de idempotencia en la cabecera x-pysae-api-request-id, leída cuando Idempotency-Key está ausente.
Prefijo de las rutas: /nav-data-processor-api/<v>/groups/<group_id>/devices/<device_id>.
| Ruta | Clave obtenida de la solicitud |
|---|---|
PUT …/location |
El dispositivo y ts |
POST …/passenger-count |
El dispositivo, trip, stop_sequence y passenger_count: un nuevo recuento con otras cifras se aplica |
POST …/duties |
El dispositivo y el identificador _id de la toma de servicio, generado por Driver |
POST …/duties/<duty_id>/checkout |
La toma de servicio y ts |
POST …/trip-events |
El dispositivo, plan_id, trip_id, trip_date, event_type, date y content, solo cuando el cliente envía date |
POST …/on-demand-stop-events |
El dispositivo, route_id, stop_id, type y ts |
POST …/on-demand-passenger-counts |
Ninguna: la clave de idempotencia es obligatoria, ya que dos recuentos idénticos en el mismo paso son legítimos |
PUT y DELETE …/current-trip, PUT …/current-trip/details, PUT y DELETE …/trip-filter, PUT …/location-metadata, PUT …/system-metadata, PUT …/vehicle-load |
Ninguna: su contenido no distingue un reenvío de una vuelta a un estado anterior. Sin clave de idempotencia, la solicitud se ejecuta como antes |
Según el estado de la clave, la ruta responde:
| Caso | Respuesta |
|---|---|
| Clave nueva | La de la ruta, que se ejecuta |
| Solicitud ya ejecutada con éxito | El estado y el cuerpo originales, con la cabecera Idempotent-Replayed: true en una llamada directa |
| Solicitud en ejecución | IDEMPOTENCY_KEY_IN_PROGRESS, con una cabecera Retry-After: reenvíela más tarde. El estado es 423 para una aplicación Driver que la vuelve a enviar, a partir de 6.2.11 en la rama 6.2 y de 6.5.4 después, y 503 para cualquier otro cliente |
| Clave de idempotencia reutilizada con otro contenido | 422 IDEMPOTENCY_KEY_MISMATCH |
Solo se memoriza una respuesta 2xx: una solicitud que ha fallado, o que ha sido interrumpida, se vuelve a ejecutar al reenviarse. Una solicitud se reconoce durante 24 h. Las claves residen únicamente en Redis: una copia que llega después de la pérdida de su clave se vuelve a ejecutar.
Las cabeceras Idempotent-Replayed y Retry-After no aparecen en la respuesta de una subsolicitud: el lote solo transmite su estado, su tipo y su cuerpo. El plazo se lee en payload.retry_after_seconds.
Una posición que no es más reciente que la del dispositivo, tanto si se reenvía tras la pérdida de su clave como si nunca se ha visto, no desplaza el dispositivo ni contabiliza ningún kilómetro.