Tragitti on demand

Questo documento descrive il servizio per le corse on demand di Fleet Engine. Si presume che tu abbia letto Che cos'è Fleet Engine? e che tu sia a conoscenza della funzionalità di servizio Fleet Engine specifica di cui hai bisogno.

Mentre leggi questa documentazione, tieni presente quanto segue:

  • Assegni i viaggi ai veicoli in modo da modellare l'associazione reale tra la corsa e il conducente che la completa. Leggi Introduzione ai veicoli per comprendere meglio come funzionano i veicoli in Fleet Engine.
  • Questo documento descrive anche alcuni elementi dei veicoli che si applicano solo alle corse on demand.
  • Fleet Engine per le corse on demand utilizza due risorse: Trip e Vehicle. Fleet Engine fornisce un servizio gRPC e interfacce REST:
    • TripService: gRPC e REST
    • VehicleService: gRPC e REST
    • Per semplicità, questo manuale utilizza esempi di gRPC.

Cos'è un viaggio on demand?

In Fleet Engine, una corsa rappresenta un percorso on demand che può raggiungere una serie di obiettivi di trasporto. Ad esempio:

  • Persone: trasporta una o più persone dal punto di prelievo al luogo di destinazione.
  • Cibo e prodotti alimentari: ritira uno o più ordini di cibo da una determinata sede dell'attività e consegnali a uno o più destinatari presso le loro sedi.

Elementi della corsa

L'illustrazione seguente mostra gli elementi di base di una corsa: l'ID del veicolo assegnato, lo stato della corsa e le tappe della corsa. I tipi di tappe variano a seconda della fase del viaggio: prelievo, intermedio e ritorno. In ogni viaggio, una destinazione o tappa intermedia è facoltativa. Nell'esempio di immagine, il veicolo è arrivato al punto di ritiro

Modello dei dati per i viaggi

Poiché il backend assegna viaggi ai veicoli, deve anche conoscere altre corse pianificate per il veicolo. Per questo motivo, i seguenti diagrammi illustrano il modello dei dati della risorsa Trip insieme al diagramma per la risorsa Vehicle associata. Puoi esaminare entrambi i diagrammi per esplorare le relazioni tra le due risorse, tenendo presente quanto segue:

  • Le corse vengono assegnate a un veicolo in base all'ID.
  • L'associazione con il veicolo di viaggio è di tipo one-to-one. In altre parole, un determinato viaggio potrebbe essere l'unico viaggio programmato per il veicolo o uno dei molti viaggi per il veicolo.
  • Gli oggetti Trip contengono due elenchi di tappe di viaggio, uno per il viaggio stesso e uno per il veicolo assegnato. Questa procedura è spiegata più dettagliatamente in questo documento.
  • Il veicolo on demand ha anche un elenco di tappe di viaggio, descritto più nel dettaglio in questo documento.

Modello dei dati di viaggio

Modello dei dati del veicolo

Tipi di viaggio

Quando il servizio crea una corsa, può impostare il campo tripType su uno dei seguenti valori: EXCLUSIVE o SHARED.

Viaggi esclusivi

Una corsa esclusiva è una corsa il cui viaggio non si sovrappone ad altre corse e che il veicolo completa prima o dopo altre corse della sua programmazione. Ciò significa che quando il tuo sistema assegna corse esclusive, può assegnarle solo a un veicolo da completare in sequenza, non contemporaneamente. Per spiegare meglio, puoi creare viaggi esclusivi con una qualsiasi delle seguenti caratteristiche:

  • Una corsa con un singolo prelievo e una sola consegna per un veicolo senza altre corse in programma.
  • Una corsa con punto di prelievo, tappa intermedia e discesa di un veicolo senza un'altra corsa in programma.
  • Una corsa con punto di partenza e arrivo aggiunti alla fine di una corsa già programmata per il veicolo. In questi casi, ogni corsa è esclusiva l'altra, ma le corse vengono ordinate in sequenza. Inoltre, queste corse possono includere destinazioni intermedie, se necessario.

Viaggi condivisi

Un viaggio condiviso è un viaggio il cui viaggio può sovrapporsi ad altre prenotazioni di viaggi. Per questi tipi di corse, il sistema può assegnarle in modo che si verifichino in concomitanza con le destinazioni tra interfoliazione. Ad esempio, l'abbandono per una corsa può avvenire dopo il prelievo per un'altra corsa. Inoltre, per le corse condivise non è consentito utilizzare tappe intermedie.

In genere, si utilizza una corsa condivisa per uno degli scenari di pooling condiviso illustrati nella sezione Scenari di viaggio.

Tappe del viaggio

Per Google Maps, una tappa è un luogo lungo un percorso, di solito definito da una coordinata di latitudine/longitudine. Per le corse on demand, una tappa è rappresentata da un oggetto TripWaypoint, che contiene informazioni aggiuntive come le seguenti:

  • L'ID viaggio
  • WaypointType, di ritiro, intermedio o consegna
  • Informazioni su percorso e distanza tra la tappa precedente e quella attuale
  • Condizioni del traffico lungo il percorso verso la tappa della corsa
  • Tempo di percorrenza e orario di arrivo stimato per raggiungere la tappa

Consulta i riferimenti:

Tipi di tappe del viaggio

Una tappa del viaggio è definita in relazione al ciclo di vita generale di un percorso con un veicolo:

  • Punto di arrivo del ritiro: utilizzato per l'origine o l'inizio di un viaggio, ad esempio quando un autista ritira un ordine di cibo per la consegna successiva o quando un autista prende una persona per farla scendere in un secondo momento.
  • Strade intermedia: destinazione intermedia che può essere utilizzata per vari scopi, ad esempio quando un conducente fa scendere un passeggero dello stesso utente che ha effettuato la prenotazione, ma la corsa in sé non è completa, in quanto rimangono più passeggeri. Questa tappa è facoltativa e può essere utilizzata solo per le corse esclusive.
  • Puntata di arrivo: da utilizzare per la posizione finale del viaggio, ad esempio quando il passeggero rimanente scende dal veicolo.

Elenchi di tappe dei viaggi

Un'entità Trip include due elenchi di tappe, ognuno dei quali è un campo ripetuto di tipo TripWaypoint. Un elenco descrive i campi necessari per la corsa e l'altro per descrivere tutte le tappe rimanenti per il veicolo associato alla corsa. In questo modo hai un quadro completo di tutti gli elementi del viaggio: la corsa e l'intero percorso del veicolo.

  • Tappe rimanenti per il veicolo: un campo chiamato vehicle_waypoints. Contiene tutte le tappe rimanenti per tutte le corse assegnate al veicolo.
  • Tappe rimanenti per la corsa: un campo chiamato remaining_waypoints. Contiene le tappe che il veicolo deve viaggiare in sequenza prima del punto di partenza finale della corsa. Vedi gli scenari in Scenari di viaggio.
    • Per un viaggio con una sola destinazione assegnato a un veicolo senza altre corse nel programma, verranno inclusi solo il punto di prelievo e la destinazione, supponendo che il veicolo non abbia lasciato la tappa di prelievo.
    • Per qualsiasi altro scenario di corsa in cui il veicolo è programmato anche per altre corse, le tappe rimanenti per qualsiasi corsa lungo l'itinerario includeranno tutte le tappe di altre corse che il veicolo deve attraversare prima di raggiungere la tappa di discesa per quella corsa. Ad esempio, in una corsa di andata e ritorno in cui il veicolo è diretto verso la discesa per la corsa A, le tappe rimanenti per la corsa B includeranno la tappa di discesa per la corsa A. Fleet Engine calcola queste informazioni utilizzando il campo vehicle_waypoints.

Consulta il riferimento per l'entità Trip: gRPC o REST.

Scenari di viaggio

I seguenti diagrammi illustrano una varietà di scenari di corsa supportati. In questi scenari, solo il viaggio di pooling condiviso è di tipo SHARED; tutti gli altri sono EXCLUSIVE. I diagrammi mostrano anche lo stato della corsa e le restanti tappe del veicolo che esegue la corsa, concetti descritti più avanti in questa guida.

Viaggio con una sola destinazione

Un viaggio con una sola destinazione è un viaggio EXCLUSIVE con un punto di prelievo e un punto di arrivo. Ad esempio, un autista prende un passeggero da un luogo e lo trasporta a un altro oppure un autista recupera un ordine di consegna di cibo da un ristorante e lo consegna a un cliente.

Viaggi con più destinazioni

Un viaggio con più destinazioni è un viaggio EXCLUSIVE che contiene una o più destinazioni intermedie tra le località di prelievo e destinazione. Ad esempio, tre clienti di ridesharing prenotano una corsa insieme dallo smartphone di una persona, ma ciascuno ha destinazioni distinte.

Corse consecutive

Le corse consecutive sono corse EXCLUSIVE che contengono una serie di corse indipendenti che si verificano una subito dopo l'altra. Ogni corsa nella catena può essere singola o più destinazioni. In questo scenario, un conducente si impegna a prendere un altro cliente prima di completare la corsa attuale.

Queste corse possono essere assegnate solo ai veicoli che consentono una pianificazione back to back. Consulta il riferimento Vehicle REST e gRPC.

Viaggi di raggruppamento condivisi

Una corsa in pool condivisa è diversa dagli altri tipi di corse. Innanzitutto, deve essere una corsa SHARED, non una corsa EXCLUSIVE. In questo caso, il veicolo esegue le corse contemporaneamente invece che in sequenza, come nelle corse esclusive. Mentre una corsa in pool condivisa condivide il suo viaggio con altri viaggi, non condivide le informazioni sui luoghi di partenza e arrivo tra le corse. Ogni viaggio è invece una prenotazione esclusiva, in modo che l'utente finale che ha prenotato un viaggio non possa vedere le informazioni su prelievo o destinazione per qualsiasi altro viaggio diverso dal proprio. Ad esempio:

  • Un servizio navetta aeroportuale prevede il trasferimento di vari clienti presso la loro residenza e il deposito presso i vari terminal aeroportuali lungo il percorso. La persona 2 potrebbe utilizzare la tua app consumer per monitorare l'avanzamento del viaggio, ma la sua app mostra solo la sua parte del percorso e non il luogo in cui è stata presa la persona 1 o il luogo in cui la persona 1 verrà lasciata, anche se due parti del percorso si sovrappongono.
  • Un corriere ritira tre ordini di cibo dallo stesso ristorante per farli consegnare a diverse residenze dei clienti. Utilizzando la tua app consumer, la persona 3 può vedere dove e quando è stato ritirato il cibo e vedere il percorso del conducente, ma non può vedere i punti di consegna del cibo per le persone 1 e 2.

Stato del viaggio e relativo ciclo di vita

Questa sezione descrive lo stato della corsa e il suo impatto sul veicolo, nonché i vari scenari che incontri quando assegni e gestisci le corse on demand.

In genere un viaggio prevede vari stati, dalla creazione al completamento. In generale, una corsa può essere attiva o non attiva, a seconda del suo stato. Lo stato del viaggio ha un impatto su una varietà di scenari d'uso con Fleet Engine, oltre alla possibilità di identificare lo stato di avanzamento del veicolo lungo il percorso. Il resto di questo documento illustra questi scenari.

La seguente tabella elenca lo stato delle corse in base ai tipi attivi e non attivi.

Stati percorsi attivi Stati percorsi inattivi
NEW
UNKNOWN_TRIP_STATUS
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF 		COMPLETE
CANCELED

Stato del viaggio e tappe rimanenti del veicolo

Quando assegni corse aggiuntive a un veicolo che sta già eseguendo una corsa, devi comprendere la relazione tra le tappe rimanenti per il veicolo e il modo in cui lo stato della corsa influisce su quelle restanti.

Ad esempio, potresti assegnare una nuova richiesta di ridesharing a un veicolo che supporta solo corse esclusive e si trova nel bel mezzo di una corsa. In questo caso, devi modellare la corsa come una corsa back-to-back. Quando assegni una corsa di questo tipo, il sistema deve garantire che le tappe per la nuova corsa avvengano dopo le tappe della corsa in corso.

Durante il viaggio del veicolo, Fleet Engine rimuove una tappa precedente del percorso dall'elenco delle tappe rimanenti del veicolo solo quando il veicolo segnala che si sta per raggiungere la destinazione successiva o è stata completata. ovvero:

  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETATO

Quando lo stato della corsa diventa COMPLETED, Fleet Engine rimuove la tappa finale della corsa dall'elenco di tappe rimanenti del veicolo.

Al contrario, i cambiamenti di stato che indicano l'arrivo a una tappa in genere non hanno alcun effetto sull'elenco delle tappe rimanenti per il veicolo:

  • ARRIVED_AT_PICKUP
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_DROPOFF

Esempio con una corsa on demand: supponiamo che l'autista prenda un cliente dalla sua residenza, lo trasporta in un luogo in cui attende che il cliente completi un'attività e poi lo riporta alla sua casa. Una volta creato, il percorso prevede tre tappe: PICKUP, INTERMEDIATE e DROPOFF. La tabella seguente illustra i risultati di una query per le tappe rimanenti in vari stati del percorso:

Stato del viaggio Tappe rimanenti
ARRIVED_AT_PICKUP PICKUP
INTERMEDIATE
DROPOFF
ENROUTE_TO_INTERMEDIATE_DESTINATION PICKUP
INTERMEDIATE
DROPOFF
ARRIVED_AT_INTERMEDIATE_DESTINATION PICKUP
INTERMEDIATE
DROPOFF
ENROUTE_TO_DROPOFF PICKUP
INTERMEDIATE
DROPOFF
ARRIVED_AT_DROPOFF PICKUP
INTERMEDIATE
DROPOFF
COMPLETE PICKUP
INTERMEDIATE
DROPOFF

Requisiti di stato per i viaggi riassegnati o annullati

Prima di eseguire una delle seguenti azioni, devi impostare lo stato della corsa su NEW o CANCELED.

  • Quando modifichi le assegnazioni dei veicoli per una corsa. Ad esempio, se un conducente rifiuta l'assegnazione di un veicolo per una corsa e quest'ultimo deve essere riassegnato a un altro veicolo.
  • Quando cancelli l'assegnazione di un veicolo per una corsa. Ad esempio, se un autista annulla una corsa lungo il percorso e vuoi annullare l'assegnazione del veicolo, lo stato deve essere NEW o CANCELED.

Risultati di ricerca basati sullo stato del viaggio

Quando utilizzi il servizio SearchTrips per un veicolo specifico, viene restituito l'elenco delle corse attive in SearchTripsResponse. Le corse attive vengono visualizzate anche nel campo active_trips dell'entità Vehicle. Per i dettagli, consulta il riferimento SearchTripsResponse: gRPC o REST.

Pertanto, tutte le corse con stato attivo vengono visualizzate nel campo active_trips, ma non tutte le corse completate o annullate.

Passaggi successivi