Modella le attività del parco risorse relative al primo e all'ultimo chilometro di consegne con l'API Fleet Engine Deliveries. Puoi utilizzare questa API con l'SDK Driver per Android e iOS oppure direttamente tramite chiamate REST HTTP o gRPC.
Configurazione iniziale
Puoi configurare l'API Fleet Engine Deliveries nella console Google Cloud.
Per informazioni sui passaggi da eseguire all'interno della console e su come creare un token web JSON per l'autorizzazione, consulta Autenticazione e autorizzazione.
Per maggiori dettagli sull'utilizzo della console, consulta la documentazione della console Google Cloud.
Verificare la configurazione
Dopo aver creato gli account di servizio, verifica che la configurazione sia completa e di poter creare un veicolo per la consegna. La verifica immediata della configurazione assicura che siano stati risolti i problemi di autorizzazione comuni che possono sorgere durante la configurazione del progetto. Puoi verificare la configurazione in due modi:
Testa due parti chiave della tua configurazione: la firma del token di autorizzazione e la creazione di un veicolo di consegna di prova con l'utilità a riga di comando
gcloud. Per maggiori dettagli, consulta la guida Verifica della configurazione.Testa la tua configurazione con gli script di esempio di Fleet Engine Auth.
Librerie client
Per una migliore esperienza degli sviluppatori rispetto a gRPC o REST non elaborati, utilizza le librerie client in diversi linguaggi di programmazione comuni. Per istruzioni su come ottenere le librerie client per la tua applicazione server, consulta Librerie client.
Gli esempi Java in questa documentazione presuppongono che tu abbia familiarità con gRPC.
Strutture di dati
L'API Fleet Engine Deliveries utilizza due strutture di dati per modellare il ritiro e la consegna delle spedizioni:
- Il veicolo per la consegna utilizzato per il trasporto della spedizione.
- Le attività di ritiro e consegna della spedizione.
Puoi usare le attività anche per modellare le interruzioni del conducente e le fermate pianificate durante la giornata.
Veicoli per la consegna
I mezzi di consegna trasportano le spedizioni da un deposito a un punto di consegna e da un punto di prelievo al deposito. In alcuni casi, possono anche trasportare una spedizione direttamente dal punto di ritiro a quella di consegna.
Utilizza l'SDK Driver per creare un oggetto DeliveryVehicle in Fleet Engine
e inviare aggiornamenti sulla posizione per il monitoraggio della spedizione e della flotta.
Attività
Per le azioni compiute da un veicolo durante il giorno, assegni attività in base al tipo di azione:
- Per ritiri e consegne, assegna l'opzione Attività di spedizione.
- Se i conducenti non sono disponibili, ad esempio le interruzioni richieste, assegna le attività di indisponibilità.
- Per le attività non in grado di guidare in caselle personali o posizioni dei clienti, assegna attività di interruzione programmata.
Ogni attività assegnata deve avere un ID attività univoco, ma le attività possono condividere lo stesso ID monitoraggio. Quando Fleet Engine calcola le finestre dell'orario di arrivo stimato per ogni attività, utilizza tutte le attività e l'ordine in cui sono pianificate per effettuare le stime. Per maggiori informazioni sugli ID attività, consulta le linee guida per gli ID attività.
Per creare attività in Fleet Engine, utilizza il Task Manager dell'SDK Driver.
Attività di spedizione
Crea attività di spedizione sia per il ritiro che per la consegna di una spedizione e includere le seguenti informazioni:
- Il luogo di ritiro o consegna.
- Un ID o un numero di riferimento.
- Un tempo di attesa per calcolare il tempo aggiuntivo per completare l'attività, cercare un parcheggio o raggiungere a piedi il punto di consegna.
- Un ID attività univoco. Consulta le linee guida per gli ID attività.
Per ulteriori informazioni, consulta i seguenti argomenti:
Android
iOS
Attività di indisponibilità
Le attività di indisponibilità coprono i periodi di tempo in cui un veicolo non è disponibile per il ritiro o le consegne, come le pause per il rifornimento del veicolo o le pause per il riposo del conducente.
Crea un'attività di indisponibilità con le seguenti informazioni:
- La durata della pausa.
- Facoltativamente, il luogo dell'interruzione. Non devi indicare una località specifica, ma così facendo ottieni finestre di orario di arrivo più precise durante la giornata.
Per ulteriori informazioni, consulta i seguenti argomenti:
Android
iOS
Attività di interruzione pianificate
Creare attività di soste programmate per modellare le fermate che un veicolo per le consegne deve fare. Ad esempio, crea un'attività di interruzione pianificata per una fermata di raccolta giornaliera pianificata in un luogo specifico, indipendentemente da altre consegne o ritiri nella stessa posizione. Puoi anche creare attività di interruzione pianificate per le raccolte dalle caselle personali o per i trasferimenti o le fermate del modello presso i centri assistenza e i punti di assistenza.
Per ulteriori informazioni, consulta i seguenti argomenti:
Android
iOS
Linee guida per gli ID attività
Quando crei ID attività, segui queste linee guida per i contenuti e la formattazione:
- Crea ID attività univoci
- Non esporre informazioni che consentono l'identificazione personale (PII) o dati di testo chiari.
- Utilizza stringhe Unicode valide.
- Utilizza al massimo 64 caratteri.
- Non includere nessuno dei seguenti caratteri ASCII: "/", ":", "\", "?" o "#".
- Normalizza in base al modulo di normalizzazione Unicode C.
Di seguito sono riportati alcuni esempi di ID attività validi:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
La tabella seguente mostra esempi di ID attività non supportati:
| ID attività non supportati | Motivo |
|---|---|
| 8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | Viola le informazioni personali e i requisiti dei caratteri: virgole, punti, due punti e barre. |
| JohnDoe-577b484da26f-Cupertino-SantaCruz | Viola i requisiti relativi alle PII. |
| 4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a | Viola i requisiti di PII e caratteri: spazi vuoti, virgole e virgolette. Più di 64 caratteri. |
Altre risorse
Per visualizzare i campi specifici contenuti in ogni struttura dati, consulta la documentazione di riferimento delle API per DeliveryVehicle
(gRPC, REST)
e Task (gRPC, REST).
La vita di un veicolo
L'oggetto DeliveryVehicle rappresenta un veicolo per la consegna primo o ultimo miglio.
Puoi creare un oggetto DeliveryVehicle utilizzando:
- L'ID del progetto Google Cloud che contiene l'account di servizio utilizzato per chiamare le API Fleet Engine.
- Un ID veicolo di proprietà del cliente.
Utilizza ID veicolo univoci per ciascun veicolo. Non riutilizzare un ID veicolo, a meno che non ci siano attività attive per il veicolo originale.
Fleet Engine elimina automaticamente DeliveryVehicle oggetti che non sono stati aggiornati utilizzando UpdateDeliveryVehicle dopo sette giorni. Per
controllare se un veicolo esiste:
- Chiama il numero
UpdateDeliveryVehicle. - Se ricevi un errore NOT_FOUND, chiama
CreateDeliveryVehicleper ricreare il veicolo. Se la chiamata restituisce un veicolo, è ancora disponibile per l'aggiornamento.
Tipi di veicoli
L'entità VehicleType contiene un campo facoltativo di VehicleType, che contiene un
enum Category che puoi specificare come AUTO, TWO_WHEELER, BICYCLE o
PEDESTRIAN. Se non configuri il campo, il valore predefinito è AUTO.
Tutti i percorsi per i veicoli utilizzano il valore RouteTravelMode
corrispondente per il tipo di veicolo.
Attributi veicolo
L'entità DeliveryVehicle contiene un campo ripetuto di DeliveryVehicleAttribute. L'API ListDeliveryVehicles include un campo filter che può limitare le entità DeliveryVehicle restituite a quelle con gli attributi specificati. DeliveryVehicleAttribute non influisce sul comportamento
del routing di Fleet Engine.
Non includere negli attributi informazioni che consentono l'identificazione personale (PII) o informazioni sensibili, poiché questo campo potrebbe essere visibile agli utenti.
La vita di un'attività
Puoi creare, aggiornare ed eseguire query su attività in Fleet Engine con le interfacce gRPC o REST dell'API Deliveries.
Un oggetto Task dispone di un campo di stato per monitorare l'avanzamento durante il ciclo di vita. I valori passano da OPEN (APERTO) a CHIUSO. Le nuove attività vengono create
nello stato APERTO, il che indica che:
- L'attività non è stata ancora assegnata a un veicolo per le consegne.
- Il veicolo per le consegne non ha ancora superato la fermata del veicolo assegnata all'attività.
Linee guida per le attività
Puoi assegnare un'attività a un veicolo solo quando è nello stato APERTO.
Puoi annullare un'attività rimuovendola dall'elenco delle fermate del veicolo, il che imposta automaticamente lo stato dell'attività su CHIUSA.
Quando il veicolo dell'attività completa l'arresto del veicolo:
Aggiorna il campo dei risultati dell'attività impostandolo su SUCCEEDED o FAILED.
Specifica il timestamp dell'evento.
La libreria JavaScript per il monitoraggio della spedizione indica quindi il risultato dell'attività e lo stato dell'attività viene impostato automaticamente su CHIUSA. Per ulteriori informazioni, consulta la pagina Tracciare la spedizione con la libreria JavaScript per il monitoraggio della spedizione.
Come per i veicoli, Fleet Engine elimina le attività che non sono state aggiornate dopo sette giorni e, se provi a creare un'attività con un ID già esistente, viene restituito un errore.
Nota: Fleet Engine non supporta l'eliminazione esplicita di un'attività. Il servizio elimina automaticamente le attività dopo sette giorni senza aggiornamenti. Se vuoi conservare i dati delle attività per più di sette giorni, devi implementare questa funzionalità autonomamente.
Attributi attività
L'entità Task contiene un campo ripetuto di TaskAttribute, che può avere un valore di uno di questi tre tipi: stringa, numero e bool. L'API ListTasks include un campo filter che può limitare le entità Task restituite a quelle con gli attributi specificati. Gli attributi delle attività non
influiscono sul comportamento di routing di Fleet Engine.
Non includere informazioni che consentono l'identificazione personale (PII) o altre informazioni sensibili negli attributi, poiché questi attributi potrebbero essere visibili agli utenti.
Gestisci il ciclo di vita del veicolo e delle attività
Promemoria: il tuo sistema interno funge da fonte attendibile dei dati che l'API Fleet Engine Deliveries aumenta per tuo conto.
Per gestire i cicli di vita dei veicoli e delle attività nel tuo sistema, utilizza l'API Fleet Engine Deliveries per creare, aggiornare e monitorare i veicoli e le attività associate.
Allo stesso tempo, l'applicazione driver comunica direttamente con Fleet Engine per aggiornare la posizione del dispositivo e le informazioni sul percorso. Questo modello consente a Fleet Engine di gestire in modo efficiente la posizione in tempo reale. Invia la posizione direttamente alla libreria di monitoraggio, che puoi utilizzare per aggiornare i consumatori sullo stato dell'ordine.
Ad esempio, supponiamo che tu abbia il seguente scenario:
- Un autista si avvicina a una fermata di consegna. L'applicazione driver invia la sua posizione a Fleet Engine.
- Fleet Engine invia la posizione del dispositivo alla libreria di monitoraggio, che l'applicazione consumer utilizza per avvisare il consumatore della vicinanza del pacco.
- Dopo aver completato la spedizione, il corriere fa clic sul pulsante "Spedizione consegnata" nell'applicazione del conducente.
- L'azione "Spedizione consegnata" invia le informazioni al tuo sistema di backend, che esegue le fasi necessarie di convalida e verifica dell'attività.
- Il sistema conferma che l'attività è RIUSCITA e aggiorna Fleet Engine utilizzando l'API Deliveries.
Il seguente diagramma illustra questi processi a livello generico. Mostra anche la relazione standard tra il tuo sistema, il client e Fleet Engine.
Gestisci token client
Gli aggiornamenti della posizione provenienti dall'applicazione driver e inviati direttamente a Fleet Engine richiedono token di autorizzazione. Ecco l'approccio consigliato per gestire gli aggiornamenti dal client a Fleet Engine:
Genera il token utilizzando il ruolo dell'account di servizio Fleet Engine Delivery Untrusted Driver User.
Fornisci all'applicazione driver un token di ambito limitato. Questo ambito consente di aggiornare solo la posizione del dispositivo in Fleet Engine.
Questo approccio garantisce che le chiamate provenienti da dispositivi mobili, considerati ambienti a bassa attendibilità, rispettino il principio del privilegio minimo.
Altri ruoli dell'account di servizio
Se invece vuoi autorizzare le applicazioni conducente ad apportare aggiornamenti diretti di Fleet Engine oltre a quelli limitati al ruolo di conducente non attendibile, ad esempio per determinati aggiornamenti di attività, puoi utilizzare il ruolo Driver attendibile. Per informazioni su un modello che utilizza il ruolo "Driver attendibile", vedi Modello di conducente attendibile.
Per maggiori informazioni sugli utilizzi dei ruoli dei conducenti non attendibili e attendibili, consulta Configurazione del progetto Cloud.
Modella una giornata di lavoro
La tabella seguente descrive l'aspetto di una giornata lavorativa per i conducenti del primo o dell'ultimo miglio per un'azienda di consegne e logistica. La tua azienda potrebbe differire nei dettagli, ma puoi vedere come puoi modellare una giornata di lavoro.
| Tempo | Attività | Definizione del modello |
|---|---|---|
| Entro 24 ore dall'inizio della giornata | Il supervisore assegna le spedizioni ai veicoli per la consegna o ai percorsi. | Puoi creare in anticipo attività per consegne, ritiri, interruzioni e altro in Fleet Engine. Ad esempio, puoi creare un'attività di ritiro della spedizione, un'attività di consegna della spedizione, un'indisponibilità pianificata o un interruzione pianificata.
Assegna attività a un veicolo una volta finalizzati l'insieme di pacchetti di consegna e l'ordine in cui devono essere consegnati. |
| Inizio giornata | Il conducente inizia la giornata al deposito accedendo all'app Driver. | Inizializza l'API Delivery Driver. Crea il veicolo per la consegna in Fleet Engine secondo le necessità. |
| L'autista carica le spedizioni sul veicolo per la consegna, scansionando le spedizioni. | Se le attività di consegna della spedizione non sono state create in anticipo, crea attività di consegna della spedizione al momento della scansione. | |
| Il conducente conferma l'ordine delle attività da eseguire. | Se non sono state create in anticipo, crea attività di ritiro della spedizione, non disponibilità programmata e interruzioni pianificate. | |
| Il conducente lascia il deposito e si impegna a completare il numero successivo di attività. | Assegna tutte le attività o un sottoinsieme di attività al veicolo eseguendone l'ordine di completamento. | |
| Il corriere consegna una spedizione. | Una volta arrivati alla fermata di consegna, esegui le azioni relative a un veicolo che arriva a una fermata. Dopo aver consegnato la spedizione, chiudi l'attività di consegna e, facoltativamente, lo stato della spedizione in negozio e altre meta informazioni. Dopo aver completato tutte le attività alla fermata e prima di iniziare a guidare fino alla fermata successiva, esegui azioni relative al veicolo che completa una fermata e al veicolo che sta per raggiungere la fermata successiva. | |
| Il conducente incontra un veicolo con alimentatore per trasferire ulteriori spedizioni sul veicolo per la consegna. | Il punto d'incontro per un trasferimento tra l'alimentatore e i veicoli per la consegna deve essere modellato come una fermata pianificata.
Dopo aver trasferito e analizzato le spedizioni, crea attività di consegna, se non sono già state create. Quindi, aggiorna l'ordine di completamento delle attività assegnando attività a un veicolo e aggiornando l'ordine delle attività. |
|
| Il conducente riceve la notifica di una richiesta di ritiro. | Dopo aver accettato la richiesta di ritiro, crea un'attività di ritiro della spedizione. Quindi, aggiorna l'ordine di esecuzione delle attività assegnando attività a un veicolo e aggiornando l'ordine delle attività. | |
| Mezzogiorno | Il conducente fa la pausa pranzo. | Se una località è associata all'attività di indisponibilità, considerala come qualsiasi altra attività. Eseguire azioni relative a un veicolo che arriva a una fermata, completa una fermata e quello che sta andando alla fermata successiva.
In caso contrario, non sono necessarie ulteriori azioni fino al termine dell'interruzione. Rimuovi l'attività confermando le attività successive e rimanenti e aggiornando l'ordine delle attività. |
| Il corriere ritira una spedizione. | Questo è modellato proprio come una fermata di consegna. Eseguire azioni relative a un veicolo che arriva a una fermata e chiudere un'attività e, facoltativamente, memorizzare lo stato di spedizione e altre meta informazioni. Dopo aver completato tutte le attività dalla fermata e prima di iniziare a guidare fino alla fermata successiva, esegui le azioni relative al veicolo che completa una fermata e al veicolo che sta per raggiungere la fermata successiva. Nota: per garantire la corretta fatturazione, tutti i ritiri devono avere un'attività di consegna corrispondente. Se il ritiro deve essere consegnato in un'altra località sullo stesso percorso del corriere quel giorno, ti consigliamo di modellare questa attività di consegna come qualsiasi altra attività di consegna lungo il percorso. Se l'autista riporta il ritiro in deposito, ti consigliamo di creare un'attività di consegna presso la destinazione del deposito. | |
| L'autista si ferma a un appuntamento per ritirare le spedizioni da una casella di posta. | Questo modello è modellato come qualsiasi altra tappa per il ritiro. Eseguire azioni correlate a un veicolo che arriva a una fermata e chiudere un'attività. Dopo aver completato tutte le attività nella fermata e aver iniziato a guidare fino alla fermata successiva, esegui le azioni relative al veicolo che completa una fermata e al veicolo che sta per raggiungere la fermata successiva. | |
| Il conducente riceve la notifica di deviazione della spedizione in una località alternativa. | Imposta lo stato dell'attività di consegna della spedizione originale su COMPLETATO e crea una nuova attività di consegna della spedizione per la nuova località di consegna. Per maggiori informazioni, consulta la sezione Reindirizzare una spedizione. | |
| Il driver ha tentato di consegnare un pacchetto, ma non è riuscito a farlo. | Questo è un modello simile a un'interruzione di consegna riuscita, contrassegnando l'attività di consegna come completata. Eseguire azioni correlate a un veicolo che arriva a una fermata. Se non riesci a consegnare la spedizione, chiudi l'attività e, facoltativamente, lo stato di spedizione del negozio e altre meta informazioni. Dopo aver completato tutte le attività dalla fermata e prima di iniziare a guidare fino alla fermata successiva, esegui le azioni relative al veicolo che completa una fermata e al veicolo che sta per raggiungere la fermata successiva. | |
| Al conducente è stato comunicato di trattenere (non consegnare) una spedizione. | Dopo aver ricevuto e confermato la notifica, imposta lo stato dell'attività su COMPLETATA. | |
| Il conducente è stato informato della prossima consegna di una determinata spedizione, con la modifica dell'ordine di consegna impegnato. | Aggiorna l'ordine delle attività. | |
| Il conducente sceglie di consegnare una spedizione non ordinata. | Aggiorna l'ordine delle attività, quindi procedi normalmente. | |
| Il corriere consegna più spedizioni in un'unica località. | Si tratta di un modello simile a quello di una singola tappa di consegna della spedizione. Una volta arrivati alla fermata, esegui azioni correlate a un veicolo che arriva a una fermata. Dopo aver consegnato ogni spedizione, chiudi ogni attività e, facoltativamente, lo stato di spedizione in negozio e altre meta informazioni. Dopo aver completato tutte le attività dalla fermata e prima di iniziare a guidare fino alla fermata successiva, esegui le azioni relative al veicolo che completa una fermata e al veicolo che sta per raggiungere la fermata successiva. | |
| Fine giornata | Il conducente torna al deposito. | Se il corriere torna in deposito con le spedizioni ritirate durante il percorso, devi anche creare e chiudere ogni pacco come attività di consegna per garantire la corretta fatturazione. Puoi farlo modellando il deposito come qualsiasi altra fermata di consegna. Se il deposito non viene utilizzato come fermata di consegna, puoi comunque modellarlo come fermata pianificata. La modellazione della fermata consente ai conducenti di vedere il percorso per tornare al deposito e fornire visibilità sull'orario di arrivo previsto. |
Come funzionano gli aggiornamenti della posizione
Per ottenere le migliori prestazioni con Fleet Engine, fornisci un flusso di aggiornamenti sulla posizione dei veicoli. Per fornire questi aggiornamenti, utilizza uno dei seguenti metodi:
- Utilizza Driver SDK - Android, iOS, l'opzione più semplice.
- Utilizza codice personalizzato, utile se le posizioni vengono inoltrate attraverso il backend o se usi dispositivi diversi da Android o iOS.
Indipendentemente da come fornisci gli aggiornamenti della posizione del veicolo, il backend è responsabile dell'aggiornamento di Fleet Engine quando un veicolo per le consegne è in viaggio verso una fermata (incluso il deposito) e quando arriva a una fermata. Fleet Engine non rileva automaticamente questi eventi.
Fermate dei veicoli e luoghi di consegna
Un veicolo di sosta è il luogo in cui un veicolo di consegna completa un'attività di spedizione o un'altra attività. Si tratta di un punto di accesso, ad esempio un molo di carico, o di un punto agganciato alla strada.
La località di consegna è il luogo in cui viene consegnata o ritirata la spedizione. Per raggiungere e tornare da un luogo di consegna potrebbe essere necessario camminare un po' prima della fermata.
Ad esempio, quando un corriere consegna un pacco a un negozio in un centro commerciale, il veicolo per la consegna si ferma nel parcheggio del centro commerciale vicino all'ingresso più vicino al negozio. Questa è la fermata del veicolo. L'autista poi cammina dalla fermata del veicolo alla posizione all'interno del centro commerciale in cui si trova il negozio. Questo è il luogo di consegna.
Per una migliore esperienza di monitoraggio della spedizione per i tuoi utenti, considera come vengono assegnate le attività di spedizione ai arresti dei veicoli e tieni presente che il numero di fermate rimanenti dei veicoli per le attività di spedizione viene segnalato agli utenti per aiutarli a visualizzare lo stato di avanzamento della spedizione.
Ad esempio, se un conducente effettua molte consegne in un singolo edificio per uffici, valuta la possibilità di assegnare tutte le attività di consegna a un'unica fermata del veicolo. Se ogni attività di consegna è assegnata a una fermata del veicolo, l'esperienza di monitoraggio della spedizione sarebbe meno utile per gli utenti, in quanto il monitoraggio è disponibile solo quando il veicolo si trova entro un numero limitato di fermate prima della destinazione. Il completamento di molte soste del veicolo in breve tempo non offre all'utente molto tempo da utilizzare per monitorare l'avanzamento della consegna.
Utilizzare gli SDK per dispositivi mobili
Prima di effettuare chiamate all'SDK del driver, assicurati di inizializzarlo.
Inizializzare l'API Delivery Driver
Prima di inizializzare l'API Delivery Driver nell'SDK Driver, assicurati di inizializzare l'SDK di navigazione. Quindi inizializza l'API Delivery Driver come mostrato nell'esempio seguente:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
Casi d'uso
Questa sezione descrive come utilizzare l'API Deliveries per creare modelli di casi d'uso comuni.
Identificatori di entità univoci
Il formato e il valore degli identificatori di entità univoci utilizzati nelle chiamate REST sono opaci per Fleet Engine. Evita di utilizzare ID con incrementi automatici e assicurati che l'identificatore non contenga informazioni che consentono l'identificazione personale (PII), come il numero di telefono del conducente.
Crea un veicolo
Puoi creare un veicolo tramite l'SDK Driver o da un ambiente server utilizzando gRPC o REST.
gRPC
Per creare un nuovo veicolo, effettui una chiamata CreateDeliveryVehicle a Fleet Engine.
Utilizza l'oggetto CreateDeliveryVehicleRequest per definire gli attributi del nuovo veicolo per la consegna. Tieni presente che qualsiasi valore specificato per il campo Name viene ignorato, secondo le indicazioni dell'API per gli ID specificati dall'utente.
Devi utilizzare il campo DeliveryVehicleId per impostare l'ID del veicolo.
Quando crei un DeliveryVehicle, puoi specificare facoltativamente questi campi:
- Attributi
- LastLocation
- Tipo
Non impostare altri campi. In questo caso, Fleet Engine restituisce un errore perché questi campi sono di sola lettura o possono essere aggiornati solo con una chiamata a UpdateDeliveryVehicle.
Per creare un veicolo senza impostare campi facoltativi, puoi lasciare il campo DeliveryVehicle non configurato in CreateDeliveryVehicleRequest.
L'esempio seguente mostra come utilizzare la libreria Java gRPC per creare un veicolo:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per creare un veicolo da un ambiente server, effettua una chiamata REST HTTP a CreateDeliveryVehicle:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
L'<id> è un identificatore univoco di un veicolo da consegnare del tuo parco risorse.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo del POST rappresenta l'entità DeliveryVehicle da creare. Puoi specificare i seguenti campi facoltativi:
- attributes
- lastLocation
- Tipo
Esempio di comando curl:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"attributes": [{"key": "model", "value": "sedan"}],
"lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM
Fleet Engine ignora il campo name dell'entità DeliveryVehicle in base alle indicazioni dell'API per gli ID specificati dall'utente.
Non impostare altri campi. In questo caso, Fleet Engine restituisce un errore perché questi campi sono di sola lettura o possono essere aggiornati solo mediante una chiamata a UpdateDeliveryVehicle.
Per creare un veicolo senza impostare alcun campo, lascia vuoto il corpo della richiesta POST. Il veicolo appena creato estrae quindi un ID veicolo dal
parametro deliveryVehicleId nell'URL POST.
Esempio di comando curl:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}"
Crea un'attività di ritiro della spedizione
Puoi creare un'attività di ritiro della spedizione dall'SDK Driver o da un ambiente server utilizzando gRPC o REST.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per creare un'attività di ritiro della spedizione:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per creare un'attività di ritiro della spedizione da un ambiente server, effettua una chiamata REST HTTP a CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> è un identificatore univoco dell'attività. Non deve essere il numero di riferimento della spedizione. Se non hai ID attività nel tuo sistema, puoi generare un UUID universalmente univoco.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità Task:
Campi obbligatori:
Campo Valore Tipo Type.PICKUP state State.OPEN trackingId Il numero o l'identificatore che stai utilizzando per tracciare una spedizione. plannedLocation La località in cui deve essere completata l'attività, in questo caso il luogo di ritiro della spedizione. taskDuration Il tempo previsto, in secondi, necessario per ritirare la spedizione presso il punto di ritiro. Campi facoltativi:
Campo Valore targetTimeWindow L'intervallo di tempo durante il quale deve essere completata l'attività. Questo non influisce sul comportamento di routing. attributes Un elenco di attributi personalizzati delle attività. Ogni attributo deve avere una chiave univoca.
Tutti gli altri campi dell'entità vengono ignorati per la creazione. Fleet Engine genera
un'eccezione se la richiesta include un elemento deliveryVehicleId assegnato. Per assegnare le attività, devi utilizzare UpdateDeliveryVehicleRequest. Per maggiori informazioni, vedi
Assegnare attività a un veicolo e UpdateDeliveryVehicleRequest.
Esempio di comando curl:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Creare un'attività di consegna della spedizione
Crea un'attività di consegna della spedizione dall'SDK Driver o da un ambiente server utilizzando gRPC o REST.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per creare un'attività di consegna della spedizione:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per creare un'attività di consegna della spedizione da un ambiente server utilizzando gRPC o REST, effettua una chiamata REST HTTP a CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> è un identificatore univoco dell'attività. Non deve essere il numero di riferimento della spedizione. Se non hai ID attività nel tuo sistema, puoi generare un UUID universalmente univoco.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità Task:
Campi obbligatori:
Campo Valore Tipo Type.DELIVERY state State.OPEN trackingId Il numero o l'identificatore che stai utilizzando per tracciare una spedizione. plannedLocation Il luogo in cui deve essere completata l'attività, in questo caso la località di consegna per questa spedizione. taskDuration Il tempo previsto, in secondi, necessario per consegnare la spedizione presso la località di consegna. Campi facoltativi:
Campo Valore targetTimeWindow L'intervallo di tempo durante il quale deve essere completata l'attività. Questo non influisce sul comportamento di routing. attributes Un elenco di attributi personalizzati delle attività. Ogni attributo deve avere una chiave univoca.
Tutti gli altri campi dell'entità vengono ignorati per la creazione. Fleet Engine genera
un'eccezione se la richiesta include un deliveryVeicoliId assegnato. Per assegnare le attività, devi utilizzare UpdateDeliveryVehicleRequest. Per maggiori informazioni, vedi
Assegnare attività a un veicolo e UpdateDeliveryVehicleRequest.
Esempio di comando curl:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Attività di creazione in batch
Puoi creare un batch di attività da un ambiente server utilizzando gRPC o REST.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per creare due attività, una per la consegna e una per il ritiro nella stessa località:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Delivery Task settings
Task deliveryTask = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("delivery-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header or parent fields
.setTaskId("task-8312508") // Task ID assigned by the Provider
.setTask(deliveryTask) // Initial state
.build();
// Pickup Task settings
Task pickupTask = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("pickup-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header or parent fields
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(pickupTask) // Initial state
.build();
// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;
// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
BatchCreateTasksRequest.newBuilder()
.setParent(parent)
.addRequests(createDeliveryTaskRequest)
.addRequests(createPickupTaskRequest)
.build();
// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.
try {
BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per creare un'attività di consegna e di ritiro da un ambiente server, effettua una chiamata REST HTTP a BatchCreateTasks:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token di Fleet Engine.
Il corpo della richiesta deve contenere un'entità BatchCreateTasksRequest:
Campi obbligatori:
Campo Valore richieste Array< CreateTasksRequest>Campi facoltativi:
Campo Valore intestazione "DeliveryRequestHeader"
Ogni elemento CreateTasksRequest in requests deve superare le stesse regole di convalida di una richiesta CreateTask, ad eccezione del fatto che i campi parent e header sono facoltativi. Se impostati, devono essere identici ai rispettivi campi nell'BatchCreateTasksRequest di primo livello. Consulta la pagina Creare un'attività di ritiro della spedizione e Creare un'attività di consegna della spedizione per conoscere le regole di convalida specifiche per ciascuna attività.
Per ulteriori informazioni, consulta la documentazione di riferimento delle API per BatchCreateTasks
(gRPC, REST).
Esempio di comando curl:
# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"requests" : [
{
"taskId": "${DELIVERY_TASK_ID}",
"task" : {
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${DELIVERY_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
},
{
"taskId": "${PICKUP_TASK_ID}",
"task" : {
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${PICKUP_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
}
]
}
EOM
Indisponibilità pianificata
Puoi creare un'attività che indica l'indisponibilità (ad esempio, per interruzioni del conducente o rifornimento di veicoli) dall'SDK Driver o da un ambiente server utilizzando gRPC o REST. Un'attività di indisponibilità pianificata non deve includere un ID monitoraggio. Se vuoi, puoi fornire una località.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per creare un'attività di indisponibilità:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per creare un'attività di indisponibilità da un ambiente server, effettua una chiamata REST HTTP a CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> è un identificatore univoco dell'attività. Se nel tuo sistema non sono presenti ID attività, puoi generare un identificatore univoco universale (UUID).
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità Task:
Campi obbligatori:
Campo Valore Tipo Type.UNAVAILABLE state State.OPEN taskDuration La durata dell'interruzione in secondi. Campi facoltativi:
Campo Valore plannedLocation Il luogo della pausa, se deve essere scattata in un luogo specifico.
Tutti gli altri campi dell'entità vengono ignorati per la creazione. Fleet Engine genera
un'eccezione se la richiesta include un deliveryVeicoliId assegnato. Per assegnare le attività, devi utilizzare UpdateDeliveryVehicleRequest. Per maggiori informazioni, vedi
Assegnare attività a un veicolo e UpdateDeliveryVehicleRequest.
Esempio di comando curl:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "UNAVAILABLE",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "300s"
}
EOM
Fermate programmate
Puoi creare un'attività di interruzione pianificata dall'SDK Driver o da un ambiente server utilizzando gRPC o REST. Un'attività di interruzione pianificata potrebbe non includere un ID monitoraggio.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per creare un'attività di interruzione pianificata:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per creare un'attività di interruzione pianificata da un ambiente server, effettua una chiamata REST HTTP a CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> è un identificatore univoco dell'attività. Se nel tuo sistema non sono presenti ID attività, puoi generare un UUID universalmente univoco.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità Task:
Campi obbligatori:
Campo Valore Tipo Type.SCHEDULED_STOP state State.OPEN plannedLocation La posizione della fermata. taskDuration La durata prevista della fermata in secondi. Campi facoltativi:
- Nessun valore
Tutti gli altri campi dell'entità vengono ignorati per la creazione. Fleet Engine genera
un'eccezione se la richiesta include un deliveryVeicoliId assegnato. Per assegnare le attività, devi utilizzare UpdateDeliveryVehicleRequest. Per maggiori informazioni, vedi
Assegnare attività a un veicolo e UpdateDeliveryVehicleRequest.
Esempio di comando curl:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "SCHEDULED_STOP",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "600s"
}
EOM
Imposta finestra temporale di destinazione
La finestra temporale di destinazione è la TimeWindow durante la quale deve essere completata l'attività. Ad esempio, se comunichi una finestra temporale di consegna ai destinatari della consegna, puoi utilizzare la finestra temporale di destinazione dell'attività per acquisire questa finestra temporale e generare avvisi o analizzare le prestazioni a seguito della corsa utilizzando il campo.
La finestra temporale di destinazione è composta da un'ora di inizio e un'ora di fine e può essere impostata su qualsiasi tipo di attività. La finestra temporale di destinazione non influisce sul comportamento di routing.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per impostare una finestra temporale per l'attività:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per impostare una finestra temporale per le attività utilizzando HTTP, chiama UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<id> è un identificatore univoco dell'attività.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità Task:
Campi obbligatori:
Campo Valore targetTimeWindow L'intervallo di tempo durante il quale deve essere completata l'attività. Questa impostazione non influisce sul comportamento di routing Campi facoltativi:
- Nessun valore
Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Imposta la configurazione della visibilità del monitoraggio delle attività
La visibilità dei dati nella libreria Monitoraggio della spedizione e di questi
dati restituiti da una chiamata a GetTaskTrackingInfo può essere controllata in base all'attività
impostando un
TaskTrackingViewConfig
per l'attività. Per ulteriori informazioni, vedi
Attività attive del veicolo. Questa operazione può essere eseguita durante la creazione
o l'aggiornamento dell'attività. Di seguito è riportato un esempio di aggiornamento dell'attività con questa configurazione:
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per impostare la configurazione della visualizzazione del monitoraggio delle attività:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskTrackingViewConfig(
TaskTrackingViewConfig.newBuilder()
.setRoutePolylinePointsVisibility(
VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
.setEstimatedArrivalTimeVisibility(
VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
.setRemainingStopCountVisibility(
VisibilityOption.newBuilder().setNever(true)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per impostare la finestra della configurazione della visualizzazione del monitoraggio delle attività utilizzando HTTP, chiama UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<id> è un identificatore univoco dell'attività.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità Task:
Campi obbligatori:
Campo Valore taskTrackingViewConfig La configurazione per il monitoraggio delle attività che specifica quali elementi dei dati sono visibili agli utenti finali in quali circostanze. Campi facoltativi:
- Nessun valore
Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"estimatedArrivalTimeVisibility": {
"remainingDrivingDistanceMetersThreshold": 5000
},
"remainingStopCountVisibility": {
"never": true
}
}
}
EOM
Assegnare attività a un veicolo
Puoi assegnare attività a un veicolo per le consegne aggiornando l'ordine delle attività per il veicolo. L'ordine delle attività per un veicolo è determinato dall'elenco delle fermate per il veicolo di consegna e puoi assegnare una o più attività a ciascuna fermata. Per maggiori dettagli, vedi Aggiornare l'ordine delle attività.
Per modificare una spedizione da un veicolo all'altro, chiudi l'attività originale e ricreala prima di assegnarle il nuovo veicolo. Se aggiorni l'ordine per un'attività già assegnata a un altro veicolo, viene visualizzato un errore.
Aggiorna l'ordine delle attività
Puoi aggiornare le attività dell'ordine assegnate a un veicolo che vengono eseguite dall'SDK Driver o dall'ambiente server. Non usare entrambi i metodi per evitare le condizioni di gara e mantenere un'unica fonte attendibile.
Quando aggiorni l'ordine delle attività per un veicolo, si verifica anche quanto segue:
- Assegna attività nuove al veicolo.
- Chiude tutte le attività assegnate in precedenza al veicolo, ma che non sono nell'ordine aggiornato.
Per modificare una spedizione da un veicolo all'altro, chiudi l'attività originale e ricreala prima di assegnarla al nuovo veicolo. Se aggiorni l'ordine per un'attività già assegnata a un altro veicolo, viene visualizzato un errore.
Puoi aggiornare l'ordine delle attività in qualsiasi momento.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per aggiornare l'ordine delle attività per il veicolo:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.NEW)))
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per aggiornare l'ordine delle attività per un veicolo da un ambiente server, effettua una chiamata REST HTTP a UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
L'<id> è un identificatore univoco di un veicolo da consegnare nel tuo parco risorse per il quale intendi aggiornare l'ordine delle attività. È l'identificatore che hai specificato durante la creazione del veicolo.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità DeliveryVehicle:
Campi obbligatori:
Campo Valore remainingVehicleJourneySegments Un elenco di segmenti di percorso per le attività nell'ordine in cui devono essere eseguite. La prima attività dell'elenco viene eseguita per prima. SegmentiJourneyJourney rimanenti[i].stop L'interruzione per l'attività i nell'elenco. SegmentiJourneyJourney rimanenti[i].stop.plannedLocation Il luogo pianificato per la fermata. SegmentiVeicoliJourneySegments[i].stop.tasks rimanenti Un elenco di attività da eseguire in corrispondenza di questa fermata del veicolo. remainingVehicleJourneySegments[i].stop.state State.NEW Campi facoltativi:
- Nessun valore
Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.
Esempio di comando curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Il veicolo è in viaggio verso la prossima fermata
Fleet Engine deve essere avvisata quando un veicolo parte da una fermata o inizia la navigazione. Puoi inviare una notifica a Fleet Engine dall'SDK Driver o da un ambiente server utilizzando gRPC o REST. Non usare entrambi i metodi per evitare le condizioni di gara e per mantenere un'unica fonte attendibile.
gRPC
L'esempio seguente mostra come utilizzare la libreria gRPC Java per notificare a Fleet Engine che un veicolo è in viaggio verso la fermata successiva.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per notificare Fleet Engine che un veicolo è in viaggio verso la fermata successiva da un ambiente server, effettua una chiamata REST HTTP a UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
L'<id> è un identificatore univoco del veicolo da consegnare del tuo parco risorse per il quale intendi aggiornare l'ordine delle attività. È l'identificatore che hai specificato durante la creazione del veicolo.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità DeliveryVehicle:
Campo obbligatorio:
Campo Valore remainingVehicleJourneySegments Elenco delle fermate del veicolo rimanenti con i relativi stati contrassegnati come Stato.NEW. Lo stato della prima fermata nell'elenco deve essere State.ENROUTE. Campi facoltativi:
- Nessun valore
Tutti gli altri campi dell'entità vengono ignorati per la notifica.
Esempio di comando curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ENROUTE",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Aggiorna la posizione del veicolo
Se non utilizzi l'SDK Driver per aggiornare la posizione del veicolo, puoi chiamare direttamente Fleet Engine indicando la posizione del veicolo. Per qualsiasi veicolo attivo, Fleet Engine si aspetta un aggiornamento della posizione almeno una volta al minuto e al massimo una volta ogni 5 secondi.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per aggiornare la posizione di un veicolo in Fleet Engine:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
.setLastLocation(DeliveryVehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(myDeliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per aggiornare la posizione di un veicolo in Fleet Engine utilizzando REST HTTP, effettua una chiamata a
UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`
L'<id> è un identificatore univoco del veicolo da consegnare nel tuo parco veicoli o di cui intendi aggiornare la località. È l'identificatore che hai specificato durante la creazione del veicolo.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità DeliveryVehicle:
Campo obbligatorio:
Campo Valore lastLocation.supplementalLocation La posizione del veicolo. lastLocation.supplementalLocationTime L'ultimo timestamp noto in cui si trovava il veicolo in questa posizione. lastLocation.supplementalLocationSensor Deve essere compilato con CUSTOMER_SUPPLIED_LOCATION. Campi facoltativi:
Campo Valore lastLocation.supplementalLocationAccuracy Precisione della posizione fornita, in metri.
Esempio di comando curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"lastLocation": {
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
}
EOM
Il veicolo arriva a una fermata
Fleet Engine deve essere avvisata quando un veicolo arriva a una fermata. Puoi inviare una notifica a Fleet Engine tramite l'SDK Driver o da un ambiente server utilizzando gRPC o REST. Non usare entrambi i metodi per evitare le condizioni di gara e per mantenere un'unica fonte attendibile.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per notificare a Fleet Engine che un veicolo è arrivato a una fermata:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Marking the arrival at stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per informare Fleet Engine dell'arrivo di un veicolo a una fermata da un ambiente server, esegui una chiamata REST HTTP a UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
L'<id> è un identificatore univoco del veicolo da consegnare del tuo parco risorse per il quale intendi aggiornare l'ordine delle attività. È l'identificatore che hai specificato durante la creazione del veicolo.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità DeliveryVehicle:
Campi obbligatori:
Campo Valore remainingVehicleJourneySegments La fermata alla quale hai raggiunto lo stato impostato su State.ARRIVED, seguito da un elenco delle fermate dei veicoli rimanenti con i relativi stati contrassegnati come State.NEW. Campi facoltativi:
- Nessun valore
Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.
Esempio di comando curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ARRIVED",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Il veicolo completa una fermata
Fleet Engine deve essere avvisata quando un veicolo completa un arresto. In questo modo tutte le attività associate alla fermata vengono impostate sullo stato CHIUSA. Puoi inviare una notifica a Fleet Engine tramite l'SDK Driver o da un ambiente server utilizzando gRPC o REST. Non usare entrambi i metodi per evitare le gare e per mantenere un'unica fonte di riferimento.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per notificare a Fleet Engine che un veicolo ha completato una fermata.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per notificare a Fleet Engine il completamento di un'interruzione da un ambiente server, esegui una chiamata REST HTTP a UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
L'<id> è un identificatore univoco del veicolo da consegnare del tuo parco risorse per il quale intendi aggiornare l'ordine delle attività. È l'identificatore che hai specificato durante la creazione del veicolo.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità DeliveryVehicle:
Campi obbligatori:
Campo Valore remaining_vehicle_journey_segments La fermata completata non deve più essere nell'elenco delle fermate del veicolo rimanenti. Campi facoltativi:
- Nessun valore
Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.
Esempio di comando curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Aggiorna un'attività
La maggior parte dei campi delle attività sono immutabili. Tuttavia, puoi modificare lo stato, il risultato dell'attività, l'ora del risultato dell'attività, la posizione del risultato dell'attività e gli attributi aggiornando direttamente l'entità dell'attività. Ad esempio, nei casi in cui un'attività non sia stata assegnata a un veicolo, puoi chiuderla aggiornando direttamente lo stato.
gRPC
Questo è un esempio di aggiornamento di un'attività tramite gRPC.
REST
Questo è un esempio di aggiornamento di un'attività tramite REST.
Chiudere un'attività
Per chiudere un'attività assegnata a un veicolo, informa Fleet Engine che il veicolo ha completato la fermata in cui si svolge l'attività oppure rimuovila dall'elenco delle fermate del veicolo. A questo scopo, puoi impostare l'elenco delle fermate rimanenti del veicolo, proprio come faresti con l'aggiornamento dell'ordine delle attività per un veicolo.
Se un'attività non è ancora stata assegnata a un veicolo e deve essere chiusa, aggiornala impostandola su CHIUSA. Tuttavia, non puoi riaprire un'attività CHIUSA.
La chiusura di un'attività non indica se l'attività è riuscita o meno. Indica che l'attività non è più considerata in corso. Per il monitoraggio della spedizione, è importante indicare il risultato effettivo di un'attività in modo da poter mostrare il risultato della consegna.
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setState(Task.State.CLOSED) // You can only directly CLOSE a
.build(); // task that is NOT assigned to a vehicle.
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("state"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per contrassegnare un'attività come chiusa da un ambiente server, effettua una chiamata REST HTTP a
UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`
<id> è un identificatore univoco dell'attività.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Devi includere un'entità Task nel corpo della richiesta:
Campi obbligatori:
Campo Valore state State.CLOSED Campi facoltativi:
Campo Valore taskOutcome Risultato.SUCCEEDED o Risultato.NON RIUSCITO taskOutcomeTime L'ora in cui è stata completata l'attività. taskOutcomeLocation Il luogo in cui è stata completata l'attività. Per impostazione predefinita, Fleet Engine viene impostata sull'ultima posizione del veicolo, a meno che non venga sostituito manualmente dal fornitore.
Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"state": "CLOSED",
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)"
}
EOM
Imposta l'esito dell'attività e la località dei risultati
La chiusura di un'attività non indica se l'attività è riuscita o meno, ma indica che l'attività non è più considerata in corso. Per il monitoraggio della spedizione, è importante indicare il risultato effettivo di un'attività in modo che sia possibile mostrare l'esito della consegna e garantire la fatturazione corretta per i servizi. Una volta impostato, non puoi modificare il risultato dell'attività. Tuttavia, puoi modificare l'ora e la località dei risultati delle attività dopo che sono state impostate.
Il risultato delle attività in stato CHIUSO può essere impostato su SUCCEEDED o FAILED. Fleet Engine addebita solo le attività di consegna con lo stato SUCCEEDED.
Quando contrassegna il risultato di un'attività, Fleet Engine compila automaticamente la posizione dei risultati dell'attività con l'ultima posizione nota del veicolo. Puoi ignorare questo comportamento.
gRPC
Hai la possibilità di impostare la località dei risultati dell'attività quando definisci il risultato. L'impostazione della posizione impedisce a Fleet Engine di impostarla sul valore predefinito dell'ultima posizione del veicolo. Puoi anche sovrascrivere la località dei risultati dell'attività impostata da Fleet Engine in un secondo momento. Fleet Engine non sovrascrive mai la località dei risultati delle attività da te fornita. Non puoi impostare una località dei risultati per un'attività per cui non è impostato alcun risultato. Puoi impostare sia i risultati dell'attività che la località dei risultati all'interno della stessa richiesta.
L'esempio seguente mostra come utilizzare la libreria gRPC Java per impostare il risultato di un'attività su SUCCEEDED e impostare il percorso in cui è stata completata l'attività:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTime(now())
.setTaskOutcomeLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per contrassegnare un'attività come completata da un ambiente server,
effettua una chiamata REST HTTP a UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`
<id> è un identificatore univoco dell'attività.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve contenere un'entità Task:
Campi obbligatori:
Campo Valore taskOutcome Risultato.SUCCEEDED o Risultato.NON RIUSCITO Campi facoltativi:
Campo Valore taskOutcomeLocation Il luogo in cui è stata completata l'attività. Se non viene configurato, Fleet Engine imposta l'ultima posizione del veicolo per impostazione predefinita. taskOutcomeTime Il timestamp di completamento dell'attività.
Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
Reindirizzare una spedizione
Una volta creata un'attività di spedizione, la posizione pianificata non può essere modificata. Per reindirizzare una spedizione, chiudi l'attività di spedizione senza impostare un risultato, quindi crea una nuova attività con la posizione pianificata aggiornata. Dopo aver creato la nuova attività, assegnala allo stesso veicolo. Per scoprire di più, consulta la pagina Chiudere l'attività di spedizione e assegnare l'attività.
Utilizzare il alimentatore e i veicoli per la consegna
Se utilizzi i veicoli alimentatori per trasportare le spedizioni ai veicoli per la consegna nell'arco della giornata, modella il trasferimento delle spedizioni come attività di interruzione pianificata per il veicolo per la consegna. Per garantire un monitoraggio accurato della posizione, assegna un'attività di consegna della spedizione per una spedizione trasferita solo dopo che è stata caricata sul vettore da consegnare. Per ulteriori informazioni, vedi Fermata programmata.
Stato di spedizione in negozio e altre meta informazioni
Quando un'attività di spedizione è completata, lo stato e il risultato dell'attività vengono registrati nell'attività. Tuttavia, potresti voler aggiornare altre meta informazioni specifiche della spedizione. Per archiviare altre meta informazioni a cui puoi fare riferimento al di fuori del servizio Fleet Engine, utilizza il tracking_id associato all'attività come chiave in una tabella esterna.
Per ulteriori informazioni, vedi Ciclo di vita di un'attività.
Cerca un veicolo
Puoi cercare un veicolo tramite l'SDK Driver o in un ambiente server utilizzando gRPC o REST.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per cercare un veicolo:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per cercare un veicolo da un ambiente server,
effettua una chiamata REST HTTP a GetVehicle:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`
<id> è un identificatore univoco dell'attività.
<vehicleId> è l'ID del veicolo da cercare.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve essere vuoto.
Se la ricerca ha esito positivo, il corpo della risposta contiene un'entità veicolo.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"
Cercare un'attività
Puoi cercare un'attività da un ambiente server utilizzando gRPC o REST. Driver SDK non supporta la ricerca di attività.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per cercare un'attività:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder() // No need for the header
.setName(taskName)
.build();
try {
Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per cercare un'attività da un ambiente server, esegui una chiamata REST HTTP a GetTask:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`
<id> è un identificatore univoco dell'attività.
<taskId> è l'ID dell'attività da cercare.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Il corpo della richiesta deve essere vuoto.
Se la ricerca ha esito positivo, il corpo della risposta contiene un'entità dell'attività.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"
Cerca le informazioni sull'attività di spedizione in base all'ID di monitoraggio
Puoi cercare le informazioni sulle attività di spedizione nei seguenti modi, ognuno dei quali ha uno scopo distinto:
- da un ID attività: utilizzato da utenti come gli operatori del parco risorse che hanno accesso alla visualizzazione completa dei dati delle attività.
- tramite un ID monitoraggio: utilizzato dal software client per fornire informazioni limitate a un utente finale, ad esempio quando è previsto un pacco a casa sua.
Questa sezione illustra la ricerca di informazioni sulle attività tramite un ID monitoraggio. Se vuoi cercare un'attività in base all'ID attività, vai a Cercare un'attività.
Per cercare informazioni in base a un ID monitoraggio, puoi utilizzare uno dei seguenti metodi:
Requisiti di ricerca
Le informazioni sulla spedizione fornite da un ID monitoraggio sono conformi alle regole di visibilità stabilite in Controllare la visibilità delle località monitorate.
Utilizza Fleet Engine per cercare informazioni sulla spedizione in base all'ID monitoraggio. L'SDK Driver non supporta la ricerca di informazioni per ID monitoraggio. Per farlo con Fleet Engine, puoi utilizzare un ambiente server o browser.
Utilizza il token più ristretto possibile per limitare i rischi per la sicurezza. Ad esempio, se utilizzi un token Delivery Consumer, ogni chiamata API Deliveries di Fleet Engine restituisce solo informazioni pertinenti per quell'utente finale, come il corriere o il destinatario di una spedizione. Tutte le altre informazioni nelle risposte vengono oscurate. Per maggiori informazioni sui token, consulta la pagina relativa alla creazione di un token web JSON (JWT) per l'autorizzazione.
Ricerche con Java utilizzando gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per cercare informazioni su un'attività di spedizione in base al relativo ID di monitoraggio.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder() // No need for the header
.setParent(parent)
.setTrackingId(TRACKING_ID)
.build();
try {
TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Ricerche con HTTP
Per cercare un'attività di spedizione da un browser, effettua una chiamata REST HTTP a
GetTaskTrackingInfo:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`
<tracking_id> è l'ID monitoraggio associato all'attività.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Se la ricerca ha esito positivo, il corpo della risposta contiene un'entità taskTrackingInfo.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"
Elenca attività
Puoi elencare le attività da un ambiente server o browser. L'SDK Driver non supporta la creazione delle schede.
L'elenco delle attività richiede l'accesso ampio alle attività. Le attività delle schede sono rivolte solo a utenti attendibili. Usa il lettore parco risorse di consegna o i token di autenticazione super user di distribuzione quando effettui richieste di attività di elenco.
Le attività elencate hanno i seguenti campi oscurati:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
Le attività elencate possono essere filtrate in base alla maggior parte delle proprietà delle attività. Per la sintassi delle query di filtro, vedi AIP-160. L'elenco seguente mostra le proprietà delle attività valide che puoi utilizzare per l'applicazione di filtri:
- attributes
- delivery_vehicle_id
- state
- planned_location
- task_duration
- task_outcome
- task_outcome_location
- task_outcome_location_source
- task_outcome_time
- tracking_id
- Tipo
Utilizza i seguenti formati dei campi basati sulle proposte di miglioramento delle API di Google:
| Tipo di campo | Formato | Esempio |
|---|---|---|
| Timestamp | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
| Durata | Numero di secondi seguiti da s |
task_duration = 120s |
| Enum | String | state = CLOSED AND type = PICKUP |
| Località | point.latitude e point.longitude |
planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0 |
Vedi AIP-160 per un elenco completo degli operatori di query di filtro.
Se non viene specificata alcuna query di filtro, vengono elencate tutte le attività.
Gli elenchi di attività vengono impaginati. È possibile specificare una dimensione di pagina nelle richieste di attività di elenco. Se si specifica una dimensione di pagina, il numero di attività restituite non è maggiore della dimensione di pagina specificata. Se non sono presenti dimensioni di pagina, viene usato un valore predefinito ragionevole. Se le dimensioni di pagina richieste superano un valore massimo interno, viene utilizzato il valore massimo interno.
Un elenco di attività può includere un token per la lettura della pagina successiva dei risultati. Utilizza il token di pagina con una richiesta altrimenti identica alla richiesta precedente per recuperare la pagina di attività successiva. Quando il token della pagina restituito è vuoto, non sono disponibili altre attività per il recupero.
gRPC
L'esempio seguente mostra come utilizzare la libreria gRPC Java per elencare le attività per un deliveryVeicoliId e un attributo attività. Una risposta corretta può essere ancora vuota. Una risposta vuota indica che nessuna attività è associata all'oggetto deliveryVeicoliId fornito.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder() // No need for the header
.setParent(parent)
.setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
.build();
try {
ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per elencare le attività da un browser, effettua una chiamata REST HTTP a ListTasks:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`
Per applicare un filtro alle attività elencate, includi un parametro URL "filtro" con una query di filtro con escape come valore.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Se la ricerca ha esito positivo, il corpo della risposta conterrà dati con la seguente struttura:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
Una risposta corretta può essere ancora vuota. Una risposta vuota indica che non sono state trovate attività che soddisfano i criteri di filtro specificati.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"
Elenca i veicoli per la consegna
Puoi elencare i veicoli per la consegna da un ambiente server o browser. L'SDK Driver non supporta l'elenco dei veicoli per la consegna.
L'elenco dei veicoli per la consegna richiede l'accesso ampio ai veicoli per la consegna ed è destinato solo agli utenti affidabili. Usa il lettore parco risorse o i token di autenticazione super utente di consegna quando effettui richieste di veicoli per la consegna dell'elenco.
I veicoli per la consegna elencati presentano i seguenti campi oscurati a causa del loro impatto sulle dimensioni della risposta:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
Puoi filtrare l'elenco dei veicoli per la consegna in base alla proprietà attributes. Ad esempio, per eseguire query su un attributo con chiave my_key e valore my_value, utilizza attributes.my_key = my_value. Per eseguire query su più attributi, unisci le query utilizzando gli operatori logici AND e OR come in attributes.key1 = value1 AND
attributes.key2 = value2. Vedi AIP-160 per una descrizione completa
della sintassi delle query di filtro.
Puoi filtrare i veicoli per la consegna elencati per località utilizzando il parametro di richiesta viewport. Il parametro di richiesta viewport definisce le aree visibili utilizzando due coordinate di delimitazione: una coppia di coordinate di latitudine e longitudine high (nord-est) e low (sud-ovest). Le richieste vengono rifiutate se contengono una latitudine
elevata geograficamente inferiore a una latitudine bassa.
Per impostazione predefinita, gli elenchi di veicoli per la consegna vengono impaginati utilizzando dimensioni della pagina ragionevoli. Se specifichi una dimensione di pagina, la richiesta restituisce solo il numero di veicoli specificato dal limite o meno. Se le dimensioni di pagina richieste superano un valore massimo interno, viene utilizzato il valore massimo interno. Le dimensioni predefinite e massime delle pagine sono entrambe di 100 veicoli.
Un elenco di veicoli per la consegna può includere un token per leggere la pagina successiva dei risultati. Un token di pagina è presente in una risposta solo quando sono disponibili più pagine di veicoli per la consegna per il recupero. Per recuperare la pagina successiva di attività, utilizza il token di pagina con una richiesta altrimenti identica alla richiesta precedente.
gRPC
L'esempio seguente mostra come utilizzare la libreria Java gRPC per elencare i veicoli di consegna in una determinata regione con un determinato attributo. Una risposta riuscita può ancora essere vuota. In questo caso, significa che nessun veicolo con l'attributo specificato si trova già nell'area visibile specificata.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
ListDeliveryVehiclesRequest.newBuilder() // No need for the header
.setParent(parent)
.setViewport(
Viewport.newBuilder()
.setHigh(LatLng.newBuilder()
.setLatitude(37.45)
.setLongitude(-122.06)
.build())
.setLow(LatLng.newBuilder()
.setLatitude(37.41)
.setLongitude(-122.11)
.build())
.setFilter("attributes.my_key = my_value")
.build();
try {
ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Per elencare le attività da un browser, effettua una chiamata REST HTTP a ListDeliveryVehicles:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Per applicare un filtro alle attività elencate, includi un parametro URL "filtro" con una query di filtro con escape URL come valore.
L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso dalla fabbrica di un token Fleet Engine.
Se la ricerca ha esito positivo, il corpo della risposta conterrà dati con la seguente struttura:
// JSON representation
{
"deliveryVehicles": [
{
object (DeliveryVehicle)
}
],
"nextPageToken": string,
"totalSize": integer
}
Una risposta corretta può essere ancora vuota. In questo caso, significa che non sono stati trovati veicoli per le consegne che soddisfano la query di filtro e l'area visibile specificati.
Esempio di comando curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"
Monitoraggio della spedizione
Hai due opzioni per utilizzare l'API Fleet Engine Deliveries per abilitare il monitoraggio della spedizione:
Preferito: utilizza la libreria JavaScript per il monitoraggio della spedizione. La libreria ti consente di visualizzare la posizione dei veicoli e le località di interesse monitorati in Fleet Engine. Contiene un componente mappa JavaScript che sostituisce un oggetto google.maps.Map standard, e componenti dati per la connessione a Fleet Engine. Questo componente ti consente di fornire un'esperienza animata e personalizzabile di monitoraggio della spedizione dalla tua applicazione web o mobile.
Implementa il monitoraggio della spedizione in aggiunta all'API Fleet Engine Deliveries.
La chiave è cercare le attività di spedizione per ID monitoraggio.
Se utilizzi un ruolo di consumatore Delivery, qualsiasi chiamata API Fleet Engine Deliveries restituisce solo informazioni pertinenti per un corriere o un destinatario. Tutte le altre informazioni nelle risposte vengono oscurate. Sei responsabile dell'autenticazione degli utenti finali. Inoltre, le informazioni sulla posizione vengono filtrate in base all'attività già in corso. Durante un'attività di indisponibilità, non vengono condivise informazioni sulla posizione con un utente finale.
Logging
Puoi impostare Fleet Engine in modo che invii i log RPC a Cloud Logging. Per ulteriori informazioni, consulta Logging.
Ruoli e token di autorizzazione
Come descritto in Gestire il ciclo di vita di veicoli e attività e nelle note di autorizzazione per i singoli casi d'uso, le chiamate a Fleet Engine richiedono l'autenticazione con token web JSON che sono stati firmati utilizzando le credenziali dell'account di servizio. Gli account di servizio utilizzati per emettere questi token possono avere uno o più ruoli e ogni ruolo concede un insieme di autorizzazioni diverso.
Per maggiori informazioni, consulta Autenticazione e autorizzazione.
Risolvere i problemi più comuni
Consulta le seguenti sezioni per assistenza in caso di problemi.
Resilienza
Fleet Engine non è considerata una fonte di riferimento. Sei responsabile del ripristino dello stato del tuo sistema, se necessario, senza dover fare affidamento su Fleet Engine.
Stato perso in Fleet Engine
Quando lavori con Fleet Engine, implementa i client in modo che il sistema si corregga da solo in caso di errore. Ad esempio, quando Fleet Engine tenta di aggiornare un veicolo, questo potrebbe rispondere con un errore che indica che il veicolo non esiste. Il client deve quindi ricreare il veicolo nel nuovo stato. Anche se questo problema si verifica raramente, assicurati che il sistema sia abbastanza resiliente per gestirlo.
Nello scenario estremamente improbabile di un guasto catastrofico di Fleet Engine, potrebbe essere necessario ricreare la maggior parte o tutti i veicoli e le attività. Se la frequenza di creazione diventa troppo elevata, alcune richieste potrebbero non riuscire di nuovo a causa di problemi di quota poiché sono in corso controlli delle quote per evitare attacchi DoS (Denial of Service). In questo caso, rallenta il tasso di ricreazione utilizzando una strategia di backoff per i nuovi tentativi.
Stato di perdita nell'app del conducente
Se l'app del conducente ha un arresto anomalo, quest'ultima deve ricreare lo stato corrente all'interno dell'SDK driver. L'app deve tentare di ricreare le attività per assicurarne l'esistenza e ripristinare lo stato attuale. L'app deve anche ricreare e impostare esplicitamente l'elenco delle fermate per l'SDK Driver.
Domande frequenti
Cosa succede se un conducente si ferma per un'attività non in ordine?
In questo caso, aggiorna prima l'ordine delle attività e poi procedi normalmente, contrassegnando l'arrivo alla fermata, il completamento dell'attività e altri dettagli. In caso contrario, il sistema potrebbe diventare incoerente, gli orari di arrivo stimati potrebbero diventare errati e potrebbero essere segnalati errori imprevisti.