Inizia a utilizzare Fleet Engine per Fleet Performance

Modella le attività del tuo parco risorse per il primo e l'ultimo miglio delle consegne con l'API Fleet Engine Deliveries. Puoi utilizzare questa API utilizzando 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.

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 ti assicura di aver risolto i problemi di autorizzazione comuni che possono verificarsi durante la configurazione del progetto. Esistono due modi per verificare la configurazione:

Librerie client

Per un'esperienza migliore per gli sviluppatori tramite REST o gRPC 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 di 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 creare modelli di ritiro e consegna delle spedizioni:

  • Il veicolo per la consegna utilizzato per trasportare la spedizione.
  • Le attività di ritiro e consegna della spedizione.

Puoi anche usare le attività per prevedere le pause e le fermate programmate nell'arco della giornata.

Veicoli per le consegne

I veicoli per le consegne trasportano le spedizioni da un deposito a una località di consegna e da un punto di ritiro al deposito. In alcuni casi, possono anche trasportare una spedizione direttamente dal punto di ritiro alla località 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.

Nota: puoi assegnare fino a 500 attività e 300 segmenti rimanenti del percorso del veicolo a DeliveryVehicle oggetti.

Attività

Per le azioni intraprese da un veicolo durante il giorno, puoi assegnare le attività in base al tipo di azione:

  • Per ritiri e consegne, assegna Attività di spedizione.
  • Per i casi in cui i conducenti non sono disponibili, ad esempio durante le pause richieste, assegna Attività non disponibili.
  • Per le attività non alla guida presso caselle personali o sedi dei clienti, assegna Attività con interruzione pianificata.

Ogni attività assegnata deve avere un ID attività univoco, ma le attività possono condividere lo stesso ID monitoraggio. Quando Fleet Engine calcola le finestre ETA per ogni attività, utilizza tutte le attività e l'ordine in cui sono pianificate per effettuare stime. Per maggiori informazioni sugli ID attività, consulta le linee guida per gli ID attività.

Per creare attività in Fleet Engine, utilizza Driver SDK Task Manager.

Attività di spedizione

Crea attività di spedizione per il ritiro e la consegna di una spedizione e includi le seguenti informazioni:

  • Il luogo di ritiro o consegna.
  • Un ID o numero di riferimento.
  • Un tempo di attesa per tenere conto del tempo aggiuntivo necessario per completare l'attività, cercare parcheggio o raggiungere a piedi il luogo di consegna.
  • Un ID attività univoco. Consulta le linee guida per gli ID attività.

Per ulteriori informazioni, consulta i seguenti argomenti:

Android

iOS

Attività non disponibili

Le attività indisponibilità riguardano i periodi di tempo in cui un veicolo non è disponibile per il ritiro o le consegne, ad esempio le pause per il rifornimento del veicolo o le pause dal polo conducente.

Crea un'attività di non disponibilità con le seguenti informazioni:

  • La durata della pausa.
  • Facoltativamente, la posizione dell'interruzione. Non è necessario specificare una località specifica, ma in questo modo puoi ottenere finestre di orario di arrivo stimato più precise durante tutta la giornata.

Per ulteriori informazioni, consulta i seguenti argomenti:

Android

iOS

Attività con interruzione pianificata

Creare attività con fermate pianificate per modellare le fermate che un veicolo per la consegna deve effettuare. Ad esempio, crea un'attività di interruzione pianificata per una fermata giornaliera di raccolta pianificata in una posizione specifica, indipendentemente da altre consegne o ritiri nella stessa posizione. Puoi anche creare attività di fermata pianificate per il ritiro dalle caselle o per modellare i trasferimenti feeder-veicoli o le fermate presso i centri assistenza e i punti di servizio.

Per ulteriori informazioni, consulta i seguenti argomenti:

Android

iOS

Linee guida per gli ID attività

Quando crei gli ID attività, segui queste linee guida sui contenuti e sulla formattazione:

  • Creare 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 secondo lo standard Unicode Normalization Form 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 i requisiti relativi a PII e 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 relativi a PII e caratteri: spazio vuoto, virgole e virgolette. Più di 64 caratteri.

Altre risorse

Per visualizzare i campi specifici contenuti in ogni struttura di dati, consulta la documentazione di riferimento delle API per DeliveryVehicle (gRPC, REST) e Task (gRPC, REST).

Vita di un veicolo

L'oggetto DeliveryVehicle rappresenta un veicolo per la consegna di 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.
  • L'ID di un veicolo di proprietà del cliente.

Utilizza ID veicolo univoci per ogni 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 verificare l'esistenza di un veicolo:

  1. Chiama UpdateDeliveryVehicle.
  2. Se ricevi un errore NOT_FOUND, chiama CreateDeliveryVehicle per ricreare il veicolo. Se la chiamata restituisce un veicolo, quest'ultimo è ancora disponibile per l'aggiornamento.

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 di routing di Fleet Engine.

Non includere informazioni che consentono l'identificazione personale (PII) o informazioni sensibili negli attributi, poiché questo campo potrebbe essere visibile agli utenti.

Durata di un'attività

Puoi creare, aggiornare ed eseguire query sulle attività in Fleet Engine con le interfacce gRPC o REST dell'API Deliveries.

Un oggetto Task include un campo di stato per monitorare l'avanzamento nel ciclo di vita. I valori si spostano da APERTO a CHIUSO. Le nuove attività vengono create con lo stato APERTO, a indicare che:

  • L'attività non è stata ancora assegnata a un veicolo per la consegna.
  • Il veicolo per la consegna non ha ancora superato l'arresto veicolo assegnato 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. Lo stato dell'attività viene impostato automaticamente su CHIUSO.

Quando il veicolo dell'attività completa l'arresto del veicolo:

  1. Aggiorna il campo del risultato dell'attività in SUCCEEDED o FAILED.

  2. Specifica il timestamp dell'evento.

    La libreria di monitoraggio del parco risorse JavaScript indica quindi il risultato dell'attività e lo stato dell'attività viene impostato automaticamente su CHIUSA. Per ulteriori informazioni, consulta Monitorare il parco risorse con la libreria di monitoraggio del parco risorse JavaScript.

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, restituisce 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 dei 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 fornisce per tuo conto.

Per gestire i cicli di vita dei veicoli e delle attività nel tuo sistema, usa l'API Fleet Engine Deliveries per creare, aggiornare e monitorare i tuoi veicoli e le attività associate.

Allo stesso tempo, l'applicazione del conducente 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. La località viene inviata direttamente alla libreria di monitoraggio, che puoi utilizzare per aggiornare i consumatori sullo stato dell'ordine.

Ad esempio, supponi di avere il seguente scenario:

  • Un autista si trova vicino a una fermata di consegna. L'applicazione del driver invia la sua posizione a Fleet Engine.
  • Fleet Engine invia la posizione del dispositivo alla libreria di monitoraggio, che la tua applicazione consumer utilizza per avvisare il consumatore della vicinanza del pacco.
  • Una volta completata 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 i passaggi di convalida e verifica aziendali necessari.
  • Il sistema conferma l'attività come SUCCEEDED e aggiorna Fleet Engine utilizzando l'API Deliveries.

Il seguente diagramma illustra questi processi a livello generico. Mostra inoltre la relazione standard tra il sistema, il client e Fleet Engine.

Diagramma di integrazione dell'API Deliveries>

Gestisci i token client

Gli aggiornamenti della posizione provenienti dall'applicazione del driver e inviati direttamente a Fleet Engine richiedono token di autorizzazione. Ecco l'approccio consigliato per gestire gli aggiornamenti dal client a Fleet Engine:

  1. Genera il token utilizzando il ruolo dell'account di servizio Fleet Engine Delivery UnTrusted Driver User.

  2. Fornisci all'applicazione del conducente un token di ambito limitato. Questo ambito consente solo di aggiornare la posizione del dispositivo in Fleet Engine.

Questo approccio garantisce che le chiamate provenienti da dispositivi mobili, considerati ambienti a bassa affidabilità, rispettino il principio del privilegio minimo.

Altri ruoli dell'account di servizio

Se invece vuoi autorizzare le applicazioni driver a eseguire aggiornamenti diretti di Fleet Engine oltre a quelli limitati al ruolo Driver non attendibile, ad esempio per alcuni aggiornamenti di attività, puoi utilizzare il ruolo Driver attendibile. Per informazioni su un modello che utilizza il ruolo Driver attendibile, consulta Modello driver attendibile.

Per maggiori informazioni sugli utilizzi dei ruoli driver non attendibili e attendibili, consulta Configurazione del progetto Cloud.

Definisci una giornata di lavoro

La seguente tabella descrive l'aspetto di una giornata lavorativa per i conducenti del primo o dell'ultimo miglio per un'azienda di consegna e logistica. La tua azienda potrebbe essere diversa nei dettagli, ma puoi vedere come potresti creare un modello per una giornata lavorativa.

TempoAttivitàDefinizione del modello
Entro 24 ore dall'inizio della giornata Il committente assegna le spedizioni ai veicoli o ai percorsi per la consegna. Puoi creare in anticipo attività per consegne, ritiri, pause e altro ancora in Fleet Engine. Ad esempio, puoi creare un'attività di ritiro della spedizione, un'attività di consegna della spedizione, un'attività di non disponibilità pianificata o un'interruzione pianificata.

Assegna attività a un veicolo una volta definiti i pacchi per la 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 in base alle tue esigenze.
Il conducente carica le spedizioni sul veicolo per la consegna, controllando le spedizioni. Se le attività di consegna della spedizione non sono state create in anticipo, crea le 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 fermate programmate.
Il conducente esce dal deposito e si impegna al numero successivo di attività da completare. Assegna tutte le attività o un sottoinsieme di attività al veicolo impostandone l'ordine di completamento.
Il conducente consegna una spedizione. Una volta arrivato 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, inserisci 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 le azioni relative a il veicolo completa una fermata e il veicolo arriva alla fermata successiva.
Il conducente incontra un veicolo con feeder per trasferire ulteriori spedizioni sul veicolo per la consegna. Il punto di incontro per un trasferimento tra veicoli di alimentazione e veicoli per la consegna deve essere modellato come fermata programmata.

Dopo aver trasferito e scansionato le spedizioni, crea attività di consegna, se non sono già state create. Quindi, aggiorna l'ordine di completamento delle attività assegnando le 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 per la spedizione. Quindi, aggiorna l'ordine di esecuzione delle attività assegnando attività a un veicolo e aggiornando l'ordine delle attività.
Mezzogiorno Il conducente è in pausa pranzo. Se all'attività di non disponibilità è associata una località, considerala come qualsiasi altra attività. Eseguire azioni relative a un veicolo che arriva a una fermata, il veicolo completa una fermata e il veicolo arriva 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 conducente 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 della spedizione e altre meta informazioni. Dopo aver completato tutte le attività alla fermata e prima di iniziare a guidare fino alla fermata successiva, esegui le azioni relative a il veicolo completa una fermata e il veicolo arriva alla fermata successiva. Nota: per garantire una fatturazione corretta, a tutti i ritiri deve essere associata un'attività di consegna. Se il ritiro deve essere consegnato in un'altra località lungo lo stesso percorso del conducente per quel giorno, consigliamo di definire come modello l'attività di consegna come qualsiasi altra attività di consegna lungo il percorso. Se l'autista riporta il ritiro al deposito, ti consigliamo di creare un'attività di consegna presso la destinazione del deposito.
Il conducente si ferma programmata per ritirare le spedizioni da una casella personale. Il modello è uguale a qualsiasi altra tappa per prelievo. Esegui azioni correlate all'arrivo di un veicolo in una fermata e alla chiusura di un'attività. Dopo aver completato tutte le attività alla fermata e aver iniziato a guidare fino alla fermata successiva, esegui le azioni relative a il veicolo completa una fermata e il veicolo arriva alla fermata successiva.
Il conducente riceve la notifica di una spedizione che viene dirottata in un luogo alternativo. Imposta lo stato dell'attività di consegna della spedizione originale su COMPLETATA e crea una nuova attività di consegna della spedizione per la nuova località di consegna. Per ulteriori informazioni, consulta la sezione Cambiare il percorso di una spedizione.
Il conducente ha tentato di consegnare un pacco, ma non è riuscito. Questo viene modellato in modo simile a un'interruzione di consegna riuscita, contrassegnando l'attività di consegna come completata. Eseguire azioni relative a un veicolo che arriva a una fermata. Dopo che non è stato possibile consegnare la spedizione, chiudi l'attività e, facoltativamente, lo stato della spedizione del negozio e altre meta informazioni. Dopo aver completato tutte le attività alla fermata e prima di iniziare a guidare fino alla fermata successiva, esegui le azioni relative a il veicolo completa una fermata e il veicolo arriva alla fermata successiva.
Il conducente è stato informato di trattenere (non consegnare) una spedizione. Dopo aver ricevuto e confermato la notifica, imposta lo stato dell'attività su COMPLETATA.
Al conducente è stato comunicato di consegnare successivamente una determinata spedizione, modificando l'ordine di consegna impegnato. Aggiorna l'ordinamento delle attività.
Il conducente sceglie di consegnare una spedizione non effettuata nell'ordine. Aggiorna l'ordinamento delle attività, quindi procedi normalmente.
Il conducente consegna più spedizioni in un unico luogo. Il modello è simile a quello di una fermata di consegna di una singola spedizione. Una volta arrivato alla fermata, esegui le azioni relative a un veicolo che arriva a una fermata. Dopo aver consegnato ogni spedizione, chiudi ogni attività e, facoltativamente, puoi anche indicare 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 le azioni relative a il veicolo completa una fermata e il veicolo arriva alla fermata successiva.
Fine giornata Il conducente torna al deposito. Se l'autista torna al deposito con le spedizioni ritirate durante il percorso, devi anche creare e chiudere ogni pacco come attività di consegna per garantire una fatturazione corretta. Puoi farlo modellando il deposito come qualsiasi altra tappa di consegna. Se il deposito non viene utilizzato come fermata di consegna, puoi comunque facoltativamente modellare il deposito 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 di posizione

Per prestazioni ottimali con Fleet Engine, fornisci un flusso di aggiornamenti sulla posizione dei veicoli. Per fornire questi aggiornamenti, utilizza uno dei seguenti metodi:

  1. Usa l'opzione più semplice dell'SDK Driver - Android, iOS.
  2. Usa il codice personalizzato, utile se le località vengono inoltrate tramite il backend o se usi dispositivi diversi da Android o iOS.

Indipendentemente da come fornisci gli aggiornamenti della posizione del veicolo, il tuo backend è responsabile dell'aggiornamento di Fleet Engine quando un veicolo per le consegne è indirizzato a una fermata (compreso il deposito) e quando arriva a una fermata. Fleet Engine non rileva questi eventi automaticamente.

Fermate veicoli e luoghi di consegna

L'arresto di un veicolo è il luogo in cui un veicolo per la consegna completa un'attività di spedizione o qualche altra attività. Può essere un punto di accesso, ad esempio un pontile di carico o un punto di accesso stradale.

La località di consegna è quella in cui viene consegna o ritirata la spedizione. Per raggiungere e tornare dal punto di consegna potrebbe essere necessario camminare dalla fermata del veicolo.

Ad esempio, quando un autista consegna un pacco a un negozio di un centro commerciale, il veicolo per le consegne si ferma nel parcheggio del centro commerciale vicino all'entrata più vicina al negozio. Questa è l'interruzione del veicolo. L'autista quindi cammina dalla fermata del veicolo al punto all'interno del centro commerciale in cui si trova il negozio. Questa è la località di consegna.

Per un'esperienza di monitoraggio della spedizione ottimale per i tuoi utenti, considera come le attività di spedizione vengono assegnate alle fermate dei veicoli e tieni presente che il numero di fermate del veicolo rimanenti per le attività di spedizione viene segnalato all'utente per aiutarli a visualizzare l'avanzamento della spedizione.

Ad esempio, se un conducente effettua molte consegne in un singolo ufficio, valuta la possibilità di assegnare tutte le attività di consegna a una singola fermata del veicolo. Se ogni attività di consegna è assegnata a una propria fermata del veicolo, l'esperienza di monitoraggio della spedizione sarebbe meno utile per i tuoi utenti, in quanto il monitoraggio è disponibile solo quando il veicolo si trova entro un numero limitato di tappe del veicolo prima della sua destinazione. Effettuare molte fermate dei veicoli in breve tempo non offre all'utente molto tempo per monitorare lo stato di avanzamento della consegna.

Utilizzare gli SDK mobile

Prima di effettuare chiamate all'SDK Driver, assicurati di inizializzarlo.

Inizializza l'API Delivery Driver

Prima di inizializzare l'API Delivery Driver nell'SDK Driver, assicurati di inizializzare l'SDK Navigation. 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 univoci delle entità

Il formato e il valore degli identificatori univoci delle entità utilizzati nelle chiamate REST sono opachi per Fleet Engine. Evita di utilizzare ID con incremento automatico e assicurati che l'identificatore non contenga informazioni che consentono l'identificazione personale (PII), ad esempio il numero di telefono del conducente.

Crea un veicolo

Puoi creare un veicolo dall'SDK Driver o da un ambiente server utilizzando gRPC o REST.

gRPC

Per creare un nuovo veicolo, effettua 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 nel campo Name viene ignorato in base alle indicazioni dell'API per gli ID specificati dall'utente. Devi usare il campo DeliveryVehicleId per impostare l'ID del veicolo.

Quando crei un DeliveryVehicle, se vuoi puoi specificare i seguenti 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 non impostato il campo DeliveryVehicle in CreateDeliveryVehicleRequest.

L'esempio seguente mostra come utilizzare la libreria gRPC Java 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>

<id> è un identificatore univoco di un veicolo per la consegna del tuo parco veicoli.

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso da un fabbrica di token di Fleet Engine.

Il corpo del POST rappresenta l'entità DeliveryVehicle da creare. Puoi specificare i seguenti campi facoltativi:

  • attributes
  • lastLocation
  • Tipo

Comando curl di esempio:

# 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 istruzioni API per gli ID specificati dall'utente. Non impostare altri campi. In caso contrario, Fleet Engine restituisce un errore perché questi campi sono di sola lettura o possono essere aggiornati solo tramite una chiamata a UpdateDeliveryVehicle.

Per creare un veicolo senza impostare alcun campo, lascia vuoto il corpo della richiesta POST. Il veicolo appena creato estrae un ID veicolo dal parametro deliveryVehicleId nell'URL POST.

Comando curl di esempio:

# 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}"

Creare 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 gRPC Java 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 disponi di ID attività nel sistema, 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità Task:

  • Campi obbligatori:

    CampoValore
    Tipo Type.PICKUP
    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 il luogo di ritiro della spedizione.
    taskDuration Il tempo previsto, in secondi, necessario per ritirare la spedizione presso il luogo di ritiro.

  • Campi facoltativi:

    CampoValore
    targetTimeWindow La finestra temporale durante la 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 deliveryVehicleId assegnato. Puoi assegnare le attività utilizzando UpdateDeliveryVehicleRequest. Per maggiori informazioni, consulta Assegnare attività a un veicolo e UpdateDeliveryVehicleRequest.

Comando curl di esempio:

# 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

Crea 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 gRPC Java 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 disponi di ID attività nel sistema, 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità Task:

  • Campi obbligatori:

    CampoValore
    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 dell'ordine.
    taskDuration Il tempo previsto, in secondi, necessario per consegnare la spedizione presso la località di consegna.

  • Campi facoltativi:

    CampoValore
    targetTimeWindow La finestra temporale durante la 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 oggetto delivery VehicleId assegnato. Puoi assegnare le attività utilizzando UpdateDeliveryVehicleRequest. Per maggiori informazioni, consulta Assegnare attività a un veicolo e UpdateDeliveryVehicleRequest.

Comando curl di esempio:

# 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

Creazione in gruppo di attività

Puoi creare un batch di attività da un ambiente server utilizzando gRPC o REST.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java per creare due attività, una per una consegna e una per un 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 ritiro da un ambiente server, crea 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 (Autorizzazione) con il valore Bearer <token>, dove <token> è un token emesso da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità BatchCreateTasksRequest:

  • Campi obbligatori:

    CampoValore
    richieste Array<CreateTasksRequest>

  • Campi facoltativi:

    CampoValore
    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 nel livello BatchCreateTasksRequest di primo livello. Consulta Creazione di un'attività di ritiro in caso di spedizione e creazione di un'attività di consegna della spedizione per regole di convalida specifiche di ciascuna attività.

Per ulteriori informazioni, consulta la documentazione di riferimento API per BatchCreateTasks (gRPC, REST).

Comando curl di esempio:

# 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 la mancata disponibilità (ad esempio, per interruzioni del conducente o rifornimento di veicoli) dall'SDK Driver o da un ambiente server che utilizza gRPC o REST. Un'attività pianificata non disponibile non deve includere un ID monitoraggio. Se vuoi, puoi fornire una località.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java per creare un'attività di non disponibilità:

    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 non disponibilità 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 non hai ID attività nel sistema, puoi generare un UUID (Universally Unique Identifier).

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità Task:

  • Campi obbligatori:

    CampoValore
    Tipo Type.UNAVAILABLE
    state State.OPEN
    taskDuration La durata dell'interruzione in secondi.

  • Campi facoltativi:

    CampoValore
    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 oggetto delivery VehicleId assegnato. Puoi assegnare le attività utilizzando UpdateDeliveryVehicleRequest. Per maggiori informazioni, consulta Assegnare attività a un veicolo e UpdateDeliveryVehicleRequest.

Comando curl di esempio:

    # 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 che utilizza gRPC o REST. Un'attività con interruzione pianificata potrebbe non includere un ID monitoraggio.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java 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 non hai ID attività nel sistema, 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità Task:

  • Campi obbligatori:

    CampoValore
    Tipo Type.SCHEDULED_STOP
    state State.OPEN
    plannedLocation La posizione della fermata.
    taskDuration La durata prevista dell'interruzione in secondi.

  • Campi facoltativi:

    • Nessuno

Tutti gli altri campi dell'entità vengono ignorati per la creazione. Fleet Engine genera un'eccezione se la richiesta include un oggetto delivery VehicleId assegnato. Puoi assegnare le attività utilizzando UpdateDeliveryVehicleRequest. Per maggiori informazioni, consulta Assegnare attività a un veicolo e UpdateDeliveryVehicleRequest.

Comando curl di esempio:

    # 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 target

La finestra temporale target è TimeWindow durante il quale l'attività deve essere completata. Ad esempio, se comunichi ai destinatari della consegna una finestra temporale, puoi utilizzare questa finestra temporale per acquisire questa finestra temporale e generare avvisi o analizzare il rendimento dopo il viaggio utilizzando il campo.

La finestra temporale target è composta da un'ora di inizio e da un'ora di fine e può essere impostata per qualsiasi tipo di attività. La finestra temporale target non influisce sul comportamento di routing.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java per impostare la finestra temporale di un'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 la finestra temporale di un'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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità Task:

  • Campi obbligatori:

    CampoValore
    targetTimeWindow La finestra temporale durante la quale deve essere completata l'attività. Questa impostazione non influisce sul comportamento di routing

  • Campi facoltativi:

    • Nessuno

Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.

Comando curl di esempio:

# 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 delle spedizioni e di questi dati restituiti da una chiamata a GetTaskTrackingInfo può essere controllata in base all'attività impostando un TaskTrackingViewConfig sull'attività. Per ulteriori informazioni, consulta Attività attive con il 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 gRPC Java 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 di 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità Task:

  • Campi obbligatori:

    CampoValore
    taskTrackingViewConfig La configurazione per il monitoraggio delle attività che specifica quali elementi di dati sono visibili agli utenti finali e in quali circostanze.

  • Campi facoltativi:

    • Nessuno

Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.

Comando curl di esempio:

# 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 la consegna aggiornando l'ordinamento delle attività per il veicolo. L'ordinamento delle attività per un veicolo è determinato dall'elenco delle fermate del veicolo per la consegna e puoi assegnare una o più attività a ogni fermata del veicolo. Per maggiori dettagli, consulta Aggiornare l'ordinamento delle attività.

Per cambiare una spedizione da un veicolo a un altro, chiudi l'attività originale e ricreala prima di assegnargli il nuovo veicolo. Se aggiorni l'ordine delle attività per un'attività già assegnata a un altro veicolo, viene visualizzato un errore.

Aggiorna ordinamento delle attività

Puoi aggiornare le attività di ordine assegnate a un veicolo che vengono eseguite dall'SDK Driver o dall'ambiente server. Non usare entrambi i metodi per evitare razze e mantenere un'unica fonte attendibile.

Quando aggiorni l'ordine delle attività per un veicolo, vengono eseguiti anche i seguenti passaggi:

  • Assegna le attività nuove per il veicolo.
  • Chiude tutte le attività che erano state precedentemente assegnate al veicolo, ma non nell'ordine aggiornato.

Per cambiare una spedizione da un veicolo a un altro, chiudi l'attività originale e poi ricreala prima di assegnare il nuovo veicolo. Se aggiorni l'ordine delle attività per un'attività già assegnata a un altro veicolo, viene visualizzato un errore.

Puoi aggiornare l'ordinamento delle attività in qualsiasi momento.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java per aggiornare l'ordinamento 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'ordinamento 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`

<id> è un identificatore univoco per un veicolo di consegna del tuo parco risorse per il quale intendi aggiornare l'ordinamento delle attività. È l'identificatore 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità DeliveryVehicle:

  • Campi obbligatori:

    CampoValore
    remainingVehicleJourneySegments Un elenco di segmenti del percorso per le attività nell'ordine in cui devono essere eseguite. La prima attività nell'elenco viene eseguita per prima.
    rimanenteVeicoloJourneySegments[i].stop L'interruzione per l'attività i nell'elenco.
    rimanente VehicleJourneySegments[i].stop.plannedLocation La posizione pianificata per la fermata.
    rimanente VehicleJourneySegments[i].stop.tasks Un elenco di attività da eseguire presso questa fermata.
    remainingVehicleJourneySegments[i].stop.state State.NEW

  • Campi facoltativi:

    • Nessuno

Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.

Comando curl di esempio:

# 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 linea con la prossima fermata

Fleet Engine deve ricevere una notifica quando un veicolo parte da una fermata o inizia la navigazione. Puoi inviare notifiche a Fleet Engine dall'SDK Driver o da un ambiente server utilizzando gRPC o REST. Non usare entrambi i metodi per evitare le razze e mantenere un'unica fonte attendibile.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java per notificare a Fleet Engine che un veicolo sta per raggiungere 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 a Fleet Engine che un veicolo è sul percorso verso la prossima fermata da un ambiente server, effettua una chiamata REST HTTP a UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> è un identificatore univoco del veicolo di consegna del parco risorse per il quale intendi aggiornare l'ordine delle attività. È l'identificatore 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità DeliveryVehicle:

  • Campo obbligatorio:

    CampoValore
    remainingVehicleJourneySegments Elenco delle fermate rimanenti del veicolo con i relativi stati contrassegnati come State.NEW. La prima fermata nell'elenco deve avere lo stato contrassegnato come State.ENROUTE.

  • Campi facoltativi:

    • Nessuno

Tutti gli altri campi dell'entità vengono ignorati per la notifica.

Comando curl di esempio:

# 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 effettuare una chiamata diretta a Fleet Engine con la posizione del veicolo. Per ogni veicolo attivo, Fleet Engine prevede 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 gRPC Java per aggiornare la località 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`

<id> è un identificatore univoco del veicolo per la consegna del tuo parco risorse o di cui intendi aggiornare la località. È l'identificatore 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità DeliveryVehicle:

  • Campo obbligatorio:

    CampoValore
    lastLocation.supplementalLocation La posizione del veicolo.
    lastLocation.supplementalLocationTime L'ultimo timestamp noto in cui si trovava il veicolo in questa posizione.
    lastLocation.supplementalLocationSensor Il campo deve essere compilato con CUSTOMER_SUPPLIED_LOCATION.

  • Campi facoltativi:

    CampoValore
    lastLocation.supplementalLocationAccuracy Precisione della posizione fornita, in metri.

Comando curl di esempio:

# 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 ricevere una notifica quando un veicolo arriva a un fermo. Puoi inviare notifiche a Fleet Engine dall'SDK Driver o da un ambiente server utilizzando gRPC o REST. Non usare entrambi i metodi per evitare le razze e mantenere un'unica fonte attendibile.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java 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 notificare a Fleet Engine l'arrivo di un veicolo in una fermata da un ambiente server, effettua una chiamata REST HTTP a UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> è un identificatore univoco del veicolo di consegna del parco risorse per il quale intendi aggiornare l'ordine delle attività. È l'identificatore 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità DeliveryVehicle:

  • Campi obbligatori:

    CampoValore
    remainingVehicleJourneySegments Lo stato della fermata a cui hai raggiunto la fermata è impostato su State.ARRIVED, seguito da un elenco di fermate rimanenti con i relativi stati contrassegnati come State.NEW.

  • Campi facoltativi:

    • Nessuno

Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.

Comando curl di esempio:

# 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 ricevere una notifica quando un veicolo completa un'arresto. In questo modo tutte le attività associate alla fermata vengono impostate sullo stato CHIUSA. Puoi inviare notifiche a Fleet Engine dall'SDK Driver o da un ambiente server utilizzando gRPC o REST. Non usare entrambi i metodi per evitare razze di condizioni e mantenere un'unica fonte attendibile.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java per notificare a Fleet Engine che un veicolo ha completato un arresto.

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, effettua una chiamata REST HTTP a UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`

<id> è un identificatore univoco del veicolo di consegna del parco risorse per il quale intendi aggiornare l'ordine delle attività. È l'identificatore 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità DeliveryVehicle:

  • Campi obbligatori:

    CampoValore
    remaining_vehicle_journey_segments La fermata che hai completato non dovrebbe più essere nell'elenco delle fermate rimanenti del veicolo.

  • Campi facoltativi:

    • Nessuno

Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.

Comando curl di esempio:

    # 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

Aggiornare un'attività

La maggior parte dei campi delle attività è immutabile. Tuttavia, puoi modificare stato, risultato dell'attività, tempo di risultato dell'attività, posizione del risultato dell'attività e 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 l'arresto in cui si svolge l'attività oppure rimuovilo dall'elenco delle fermate del veicolo. A questo scopo, puoi impostare l'elenco delle fermate rimanenti del veicolo proprio come per aggiornare l'ordine delle attività per un veicolo.

Se a un'attività non è ancora stato assegnato un veicolo e deve essere chiusa, aggiorna l'attività impostandola sullo stato CHIUSA. Tuttavia, non puoi riaprire un'attività CHIUSA.

La chiusura di un'attività non indica l'esito positivo o negativo. Indica che l'attività non è più considerata in corso. Per il monitoraggio del parco risorse, è 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 (Autorizzazione) con il valore Bearer <token>, dove <token> è un token emesso da un fabbrica di token di Fleet Engine.

Devi includere un'entità Task nel corpo della richiesta:

  • Campi obbligatori:

    CampoValore
    state State.CLOSED

  • Campi facoltativi:

    CampoValore
    taskOutcome Risultato.SUCCEEDED o Risultato.NON RIUSCITO
    taskOutcomeTime L'ora in cui l'attività è stata completata.
    taskOutcomeLocation Il luogo in cui è stata completata l'attività. Per impostazione predefinita, Fleet Engine mostra l'ultima posizione del veicolo, a meno che non venga sostituita manualmente dal fornitore.

Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.

Comando curl di esempio:

    # 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 il risultato dell'attività e la sua posizione

La chiusura di un'attività non indica successo o fallimento, ma indica che l'attività non è più considerata in corso. Per il monitoraggio del parco risorse, è importante indicare il risultato effettivo di un'attività per poter mostrare il risultato della consegna e garantire una fatturazione adeguata per i servizi. Una volta impostato, non puoi modificare il risultato dell'attività. Tuttavia, puoi modificare l'ora e la località del risultato dell'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 distribuzione con lo stato SUCCEEDED.

Quando contrassegni il risultato di un'attività, Fleet Engine compila automaticamente la posizione del risultato dell'attività con l'ultima posizione nota del veicolo. Puoi eseguire l'override di questo comportamento.

gRPC

Puoi scegliere di impostare la località del risultato dell'attività al momento di definire il risultato. L'impostazione della località impedisce a Fleet Engine di impostarla sul valore predefinito dell'ultima posizione del veicolo. Puoi anche sovrascrivere il set di Fleet Engine per la località dei risultati dell'attività in un secondo momento. Fleet Engine non sovrascrive mai la località dei risultati di un'attività fornita da te. Non puoi impostare una località del risultato per un'attività che non ne ha uno. Puoi impostare sia l'esito che il risultato dell'attività 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 la località 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve contenere un'entità Task:

  • Campi obbligatori:

    CampoValore
    taskOutcome Risultato.SUCCEEDED o Risultato.NON RIUSCITO
    taskOutcomeTime Il timestamp di quando è stato impostato il risultato dell'attività (dal provider). Questa è l'ora in cui l'attività è stata completata.

  • Campi facoltativi:

    CampoValore
    taskOutcomeLocation Il luogo in cui è stata completata l'attività. Per impostazione predefinita, Fleet Engine mostra l'ultima posizione del veicolo, a meno che non venga sostituita manualmente dal fornitore.

Tutti gli altri campi dell'entità vengono ignorati per l'aggiornamento.

Comando curl di esempio:

# 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

Cambio di percorso di una spedizione

Una volta creata un'attività di spedizione, la località 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 saperne di più, consulta Chiudere l'attività di spedizione e assegnare l'attività.

Utilizza feeder e veicoli per la consegna

Se utilizzi veicoli con feeder per trasportare le spedizioni ai veicoli per la consegna nell'arco dell'intera giornata, modella il trasferimento delle spedizioni come attività di interruzione programmata per il veicolo per la consegna. Per garantire un monitoraggio della posizione accurato, assegna un'attività di consegna relativa a una spedizione trasferita solo dopo che questa è stata caricata sul veicolo per la consegna. Per ulteriori informazioni, consulta la sezione Fermata programmata.

Stato della spedizione del negozio e altre meta informazioni

Quando un'attività di spedizione è stata 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 all'esterno del servizio Fleet Engine, utilizza il tracking_id associato all'attività come chiave in una tabella esterna.

Per ulteriori informazioni, consulta Vita di un'attività.

Cercare un veicolo

Puoi cercare un veicolo nell'SDK Driver o in un ambiente server utilizzando gRPC o REST.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve essere vuoto.

Se la ricerca ha esito positivo, il corpo della risposta contiene un'entità veicolo.

Comando curl di esempio:

# 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. L'SDK Driver non supporta la ricerca di un'attività.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java 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, effettua 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 da un fabbrica di token di Fleet Engine.

Il corpo della richiesta deve essere vuoto.

Se la ricerca ha esito positivo, il corpo della risposta contiene un'entità attività.

Comando curl di esempio:

    # 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}"

Cercare le informazioni sulle attività di spedizione in base all'ID monitoraggio

Puoi cercare le informazioni sulle attività del parco risorse nei seguenti modi, ognuno dei quali ha uno scopo distinto:

  • in base a 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 delle informazioni sulle attività in base a un ID monitoraggio. Se vuoi cercare un'attività in base al relativo ID, vai a Cercare un'attività.

Per cercare le 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 ottemperano alle regole di visibilità indicate nella sezione 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 di monitoraggio. Per fare ciò con Fleet Engine, utilizza un ambiente server o browser.

  • Utilizza il token più ristretto possibile per limitare i rischi per la sicurezza. Ad esempio, se utilizzi un token consumer per la consegna, qualsiasi chiamata API Fleet Engine Deliveries restituisce solo informazioni pertinenti per quell'utente finale, ad esempio 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 JWT (JSON Web Token) per l'autorizzazione.

Ricerche con Java mediante gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java per cercare informazioni su un'attività di spedizione in base al relativo ID 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 mediante 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 (Autorizzazione) con il valore Bearer <token>, dove <token> è un token emesso da un fabbrica di token di Fleet Engine.

Se la ricerca ha esito positivo, il corpo della risposta contiene un'entità taskTrackingInfo.

Comando curl di esempio:

# 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 di elenchi di attività.

Le attività della scheda richiedono accesso ampio alle attività. Le attività della scheda sono destinate solo a utenti attendibili. Usa Delivery Fleet Reader o Delivery Super User Tokens quando effettui richieste di attività per gli elenchi.

I seguenti campi delle attività elencate sono oscurati:

  • VehicleStop.planned_location
  • VehicleStop.state
  • VehicleStop.TaskInfo.taskId

Le attività elencate possono essere filtrate in base alla maggior parte delle relative proprietà. Per la sintassi delle query di filtro, consulta AIP-160. Il seguente elenco 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 dell'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 Stringa 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à sono impaginati. È possibile specificare le dimensioni di pagina nelle richieste di attività elenco. Se viene specificata una dimensione di pagina, il numero di attività restituite non è maggiore delle dimensioni della pagina specificate. Se non sono presenti dimensioni di pagina, viene utilizzato un valore predefinito ragionevole. Se le dimensioni della pagina richieste superano un valore massimo interno, viene utilizzato quello massimo interno.

Un elenco di attività può includere un token per leggere la pagina dei risultati successiva. Utilizza il token di pagina con una richiesta altrimenti identica alla richiesta precedente per recuperare la pagina successiva delle attività. 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 oggetto delivery VehicleId e un attributo dell'attività. Una risposta riuscita può essere vuota. Una risposta vuota indica che non è associata alcuna attività al delivery VehicleId specificato.

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 come valore un parametro URL "filtro" con una query di filtro con URL con caratteri di escape.

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso da un fabbrica di token di Fleet Engine.

Se la ricerca ha esito positivo, il corpo della risposta contiene dati con la seguente struttura:

    // JSON representation
    {
      "tasks": [
        {
          object (Task)
        }
      ],
      "nextPageToken": string,
      "totalSize": integer
    }

Una risposta corretta può ancora essere vuota. Una risposta vuota indica che non sono state trovate attività che soddisfano i criteri di filtro specificati.

Comando curl di esempio:

    # 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 di consegna da un ambiente server o browser. L'SDK Driver non supporta la pubblicazione di schede sui veicoli per la consegna.

La pubblicazione della scheda dei veicoli per la consegna richiede accesso ampio ai veicoli per la consegna ed è destinata solo a utenti attendibili. Utilizza Lettore parco risorse o token di autenticazione super utente Delivery quando effettui richieste relative ai veicoli per la consegna degli elenchi.

I veicoli di consegna elencati hanno i seguenti campi oscurati a causa del loro impatto sulle dimensioni della risposta:

  • CurrentRouteSegment
  • RemainingVehicleJourneySegments

Puoi filtrare i veicoli per la consegna dell'elenco in base alla relativa proprietà attributes. Ad esempio, per eseguire una query su un attributo con la chiave my_key e il 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. Consulta AIP-160 per una descrizione completa della sintassi delle query di filtro.

Puoi filtrare i veicoli per la consegna elencati in base alla 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 bassa.

Gli elenchi di veicoli per la consegna a domicilio vengono impaginati per impostazione predefinita utilizzando dimensioni ragionevoli delle pagine. Se specifichi le dimensioni della pagina, la richiesta restituisce solo il numero massimo di veicoli specificati dal limite. Se le dimensioni della pagina richieste superano un valore massimo interno, viene utilizzato quello massimo interno. Le dimensioni di pagina predefinite e massime sono entrambe 100 veicoli.

Un elenco di veicoli per la consegna può includere un token per leggere la pagina dei risultati successiva. Un token di pagina è presente in una risposta solo quando sono disponibili più pagine di veicoli da consegnare per il recupero. Per recuperare la pagina successiva di attività, utilizza il token di pagina con una richiesta identica a quella precedente.

gRPC

L'esempio seguente mostra come utilizzare la libreria gRPC Java per elencare i veicoli di consegna in una regione specifica con un determinato attributo. Una risposta corretta 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 URL con escape come valore.

L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> è un token emesso da un fabbrica di token di Fleet Engine.

Se la ricerca ha esito positivo, il corpo della risposta contiene dati con la seguente struttura:

// JSON representation
{
  "deliveryVehicles": [
    {
      object (DeliveryVehicle)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Una risposta corretta può ancora essere vuota. Ciò significa che non sono stati trovati veicoli per la consegna che soddisfano la query di filtro e l'area visibile specificate.

Comando curl di esempio:

# 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 del parco risorse

Hai due opzioni per utilizzare l'API Fleet Engine Deliveries per abilitare il monitoraggio del parco risorse:

  • Opzione preferita: utilizza la libreria di monitoraggio del parco risorse JavaScript. La libreria ti consente di visualizzare la posizione dei veicoli e le posizioni di interesse monitorati in Fleet Engine. Contiene un componente mappa JavaScript che sostituisce direttamente un oggetto google.maps.Map standard e i componenti di dati per la connessione a Fleet Engine. Questo componente ti consente di fornire un'esperienza di monitoraggio del parco risorse animata e personalizzabile dall'applicazione web o mobile.

  • Implementa il monitoraggio della tua flotta sull'API Fleet Engine Deliveries.

La chiave è cercare le attività del parco risorse per ID monitoraggio.

Logging

Puoi impostare Fleet Engine per inviare i log RPC a Cloud Logging. Per ulteriori informazioni, consulta Logging.

Ruoli e token di autorizzazione

Come descritto in Gestione del ciclo di vita del veicolo e delle attività e nelle note sull'autorizzazione per 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 diverso di autorizzazioni.

Per ulteriori informazioni, consulta la sezione Autenticazione e autorizzazione.

Risolvere i problemi più comuni

In caso di problemi, consulta le sezioni seguenti per assistenza.

Resilienza

Fleet Engine non è considerato una fonte attendibile. Spetta a te ripristinare lo stato del tuo sistema, se necessario, senza fare affidamento su Fleet Engine.

Stato perso in Fleet Engine

Quando lavori con Fleet Engine, implementa i client in modo che il sistema si ripara da solo in caso di errore. Ad esempio, quando Fleet Engine tenta di aggiornare un veicolo, potrebbe rispondere con un errore che indica che il veicolo non esiste. Il cliente deve quindi ricreare il veicolo nel nuovo stato. Anche se questo problema si verifica raramente, assicurati che il tuo sistema sia abbastanza resiliente da gestirlo.

Nell'improbabile scenario 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 divente troppo elevata, alcune richieste potrebbero non riuscire nuovamente a causa di problemi di quota, poiché sono in atto controlli delle quote per evitare attacchi DOS (denial of service). In questo caso, rallenta la frequenza di ricreazione utilizzando una strategia di backoff per i nuovi tentativi.

Stato perso nell'app del conducente

Se l'app del driver si arresta in modo anomalo, deve ricreare lo stato corrente all'interno dell'SDK Driver. Deve tentare di ricreare le attività per assicurarsi che esistano 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 autista si ferma per un'attività non nell'ordine corretto?

In questo caso, aggiorna prima l'ordine delle attività e poi procedi come di consueto, contrassegnando l'arrivo alla fermata, il completamento dell'attività e altri dettagli. In caso contrario, il sistema potrebbe risultare incoerente, gli orari di arrivo stimati potrebbero non essere corretti e potrebbero essere segnalati errori imprevisti.