Introduzione a Fleet Engine

L'API On-demand Rides and Deliveries di Fleet Engine consente di gestire le corse e lo stato dei veicoli per le applicazioni Trip and Order Progress. Gestisce le transazioni tra l'SDK Driver, l'SDK consumer e il servizio di backend, che può comunicare con Fleet Engine effettuando chiamate gRPC o REST.

Prerequisiti

Per lo sviluppo, assicurati di installare Cloud SDK (gcloud) e di aver eseguito l'autenticazione nel tuo progetto.

shell

gcloud auth login

Dovresti vedere un messaggio di operazione riuscita come:

You are now logged in as [my-user@example.com].
Your current project is [project-id].  You ...

Verifica che le API On-demand Rides and Deliveries Solution del Fleet Engine siano configurate correttamente.

shell

gcloud --project=project-id services enable fleetengine.googleapis.com

Se questo comando restituisce un errore, contatta l'amministratore del progetto e il rappresentante dell'assistenza Google per ottenere l'accesso.

Logging

Fleet Engine può scrivere messaggi di log sulle chiamate API ricevute nei log della piattaforma Google Cloud. Consulta la documentazione di Cloud Logging per una panoramica su come leggere e analizzare i log.

Logging potrebbe non essere abilitato per impostazione predefinita per i progetti creati prima del 10 febbraio 2022. Per ulteriori dettagli, consulta la documentazione sul logging.

Librerie client

Pubblichiamo librerie client in molti linguaggi di programmazione comuni. Queste librerie consentiranno agli sviluppatori di avere un'esperienza migliore su REST o gRPC non elaborati. Per istruzioni su come ottenere le librerie client per la tua applicazione server, consulta Librerie client.

Gli esempi di Java in questa documentazione presuppongono familiarità con gRPC.

Autenticazione e autorizzazione

Puoi configurare le funzionalità fornite da Trip and Order Progress tramite la console Google Cloud. Queste API e questi SDK richiedono l'utilizzo di token web JSON che sono stati firmati utilizzando account di servizio creati dalla console Cloud.

Configurazione del progetto Cloud

Per configurare il progetto cloud, devi prima creare il progetto e poi gli account di servizio.

Per creare il tuo progetto Google Cloud:

  1. Crea un progetto Google Cloud utilizzando la console Google Cloud.
  2. Con la dashboard API e servizi, abilita l'API Local Rides and Deliveries.

Gli account di servizio sono associati a uno o più ruoli. Vengono utilizzati per creare token web JSON che concedono set di autorizzazioni diversi a seconda dei ruoli. In genere, per ridurre la possibilità di comportamenti illeciti, puoi creare più account di servizio, ciascuno con l'insieme minimo di ruoli richiesto.

Viaggio e Avanzamento dell'ordine utilizzano i seguenti ruoli:

RuoloDescrizione
Utente SDK consumer di Fleet Engine

roles/fleetengine.consumerSdkUser
Concede l'autorizzazione per cercare veicoli e recuperare informazioni su veicoli e corse. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dai dispositivi mobili dell'app consumer per il ridesharing o la consegna.
Utente SDK driver Fleet Engine

roles/fleetengine.driverSdkUser
Concede l'autorizzazione per aggiornare le posizioni e i percorsi dei veicoli e a recuperare informazioni su veicoli e corse. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dai dispositivi mobili dell'app di ridesharing o di addetti alle consegne.
Super user servizio Fleet Engine

roles/fleetengine.serviceSuperUser
Concede l'autorizzazione a tutte le API per i veicoli e le corse. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dai server di backend.

Ad esempio, crea un account di servizio per ciascuno dei tre ruoli e assegna loro i rispettivi ruoli.

gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.consumerSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.driverSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-su
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.serviceSuperUser

Gli SDK Driver e Consumer sono basati su questi ruoli standard.

In alternativa, è possibile creare ruoli personalizzati che consentono di raggruppare un set arbitrario di autorizzazioni. Gli SDK Driver e Consumer mostreranno messaggi di errore ogni volta che manca un'autorizzazione richiesta. Di conseguenza, ti consigliamo vivamente di utilizzare l'insieme standard di ruoli descritto in precedenza e di non utilizzare ruoli personalizzati.

Per praticità, se devi creare token JWT per client non attendibili, l'aggiunta di utenti al ruolo Creatore token account di servizio consente loro di creare token mediante gli strumenti a riga di comando gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Dove my-user@example.com è l'indirizzo email utilizzato per l'autenticazione con gcloud (gcloud auth list --format='value(account)').

Libreria di autenticazione Fleet Engine

Fleet Engine utilizza token JWT (JSON Web Tokens) per limitare l'accesso alle API Fleet Engine. La nuova libreria di autenticazione Fleet Engine, disponibile su GitHub, semplifica la creazione dei JWT di Fleet Engine e li firma in modo sicuro.

La libreria offre i seguenti vantaggi:

  • Semplifica il processo di creazione dei token Fleet Engine.
  • Fornisce meccanismi di firma dei token diversi dall'utilizzo dei file di credenziali (come l'identità di un account di servizio).
  • Collega i token firmati alle richieste in uscita effettuate da uno stub gRPC o da un client GAPIC.

Creazione di un token JWT (JSON Web Token) per l'autorizzazione

Se non utilizzi la libreria di autenticazione di Fleet Engine, i token JWT (JSON Web Token) devono essere creati direttamente all'interno del tuo codebase. Ciò richiede una conoscenza approfondita dei JWT e della loro relazione con Fleet Engine. Ecco perché consigliamo vivamente di sfruttare la libreria di autenticazione Fleet Engine.

All'interno di Fleet Engine, i token JWT (JSON Web Tokens) forniscono un'autenticazione di breve durata e assicurano che i dispositivi possano modificare solo veicoli, corse o attività per cui sono autorizzati. I JWT contengono un'intestazione e una sezione di attestazione. La sezione dell'intestazione contiene informazioni quali la chiave privata da utilizzare (ottenuta dagli account di servizio) e l'algoritmo di crittografia. La sezione di attestazione contiene informazioni come data e ora di creazione del token, durata dei token, servizi a cui viene richiesto l'accesso e altre informazioni sull'autorizzazione per ridurre l'accesso, ad esempio l'ID veicolo.

Una sezione di intestazione JWT contiene i seguenti campi:

CampoDescrizione
alg L'algoritmo da utilizzare. "RS256".
typ Il tipo di token. "JWT".
bambino L'ID della chiave privata del tuo account di servizio. Puoi trovare questo valore nel campo "private_key_id" del file JSON del tuo account di servizio. Assicurati di utilizzare una chiave di un account di servizio con il livello di autorizzazioni corretto.

Una sezione delle attestazioni JWT contiene i seguenti campi:

CampoDescrizione
iss L'indirizzo email del tuo account di servizio.
sub L'indirizzo email del tuo account di servizio.
Aud Il SERVICE_NAME del tuo account di servizio, in questo caso https://fleetengine.googleapis.com/
iat Il timestamp di creazione del token, specificato in secondi trascorsi dalle ore 00:00:00 UTC, 1° gennaio 1970. Attendi 10 minuti per il disallineamento. Se il timestamp è troppo lontano nel passato o nel futuro, il server potrebbe segnalare un errore.
exp Il timestamp di scadenza del token, specificato in secondi trascorsi dalle ore 00:00:00 UTC, 1° gennaio 1970. La richiesta non riesce se il timestamp supera un'ora nel futuro.
authorization A seconda del caso d'uso, potrebbe contenere "vehicleid" o "tripid".

La creazione di un token JWT implica la firma del token. Per istruzioni ed esempi di codice per creare e firmare il JWT, consulta Autorizzazione dell'account di servizio senza OAuth. Puoi quindi collegare un token firmato alle chiamate gRPC o ad altri metodi utilizzati per accedere a Fleet Engine.

Attestazioni JWT

Quando crei il payload JWT, aggiungi un'ulteriore richiesta nella sezione di autorizzazione con la chiave vehicleid o tripid impostata sul valore dell'ID veicolo o dell'ID corsa per cui viene effettuata la chiamata.

L'SDK Driver utilizza sempre la rivendicazione vehicleid, a prescindere dal fatto che si tratti di un viaggio o di un veicolo. Il backend Fleet Engine assicura che il veicolo sia associato alla corsa richiesta prima di apportare la modifica.

L'SDK consumer utilizza sempre l'attestazione tripid.

Il fornitore di servizi di ridesharing o di consegna a domicilio deve utilizzare vehicleid o tripid con un segno "*" per associare tutti i veicoli e i viaggi. Tieni presente che il JWT può contenere entrambi i token, anche se non richiesti, il che può semplificare l'implementazione della firma dei token.

Casi d'uso di JWT

Di seguito è riportato un esempio di token per il Server provider:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
  "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Di seguito è riportato un token di esempio per Consumer app:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

Di seguito è riportato un token di esempio per l'app Driver:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}
  • Per il campo kid nell'intestazione, specifica l'ID della chiave privata dell'account di servizio. Puoi trovare questo valore nel campo private_key_id del file JSON del tuo account di servizio.
  • Per i campi iss e sub, specifica l'indirizzo email dell'account di servizio. Puoi trovare questo valore nel campo client_email del file JSON del tuo account di servizio.
  • Per il campo aud, specifica https://SERVICE_NAME/.
  • Per il campo iat, utilizza il timestamp al momento della creazione del token, specificato come secondi trascorsi dalle ore 00:00:00 UTC, 1° gennaio 1970. Attendi 10 minuti per il disallineamento. Se il timestamp è troppo lontano nel passato o nel futuro, il server potrebbe segnalare un errore.
  • Per il campo exp, utilizza il timestamp della scadenza del token, specificato come secondi a partire dalle ore 00:00:00 UTC, 1° gennaio 1970. Il valore massimo consentito è iat + 3600.

Quando firma il JWT da passare a un dispositivo mobile, assicurati di utilizzare l'account di servizio per il ruolo dell'SDK Driver o Consumer. Altrimenti, il dispositivo mobile potrà modificare lo stato che non dovrebbe avere.

Allo stesso modo, quando firma il JWT da utilizzare per le chiamate privilegiate, assicurati di utilizzare l'account di servizio con il ruolo Super User. In caso contrario, l'operazione non andrà a buon fine.

Generazione di un JWT per i test

La generazione di token dal terminale può essere utile durante i test.

Per seguire questi passaggi, il tuo account utente deve avere il ruolo Creatore token account di servizio:

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Crea un nuovo file denominato unsigned_token.json con i contenuti riportati di seguito. La proprietà iat indica l'ora corrente in numero di secondi dopo l'epoca, che può essere recuperata eseguendo date +%s nel terminale. La proprietà exp indica l'ora di scadenza in numero di secondi dopo l'epoca, che può essere calcolata aggiungendo 3600 a iat. La scadenza non può essere superiore a un'ora nel futuro.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "sub": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Quindi esegui questo comando gcloud per firmare il token per conto del tuo account di servizio super user:

gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt

A questo punto, un JWT firmato con codifica Base64 dovrebbe essere archiviato all'interno del file signed_token.jwt. Il token sarà valido per la prossima ora.

Ora puoi testare il token eseguendo un comando curl sull'endpoint REST List Vehicles:

curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"

Veicoli e loro ciclo di vita

Per "Veicolo" si intende l'entità che rappresenta una coppia guida-veicolo. Attualmente, un conducente e un veicolo non possono essere monitorati separatamente. Il provider di Ridesharing o di consegna crea un veicolo utilizzando un ID provider (che deve essere uguale all'ID del progetto Google Cloud che contiene l'account di servizio utilizzato per chiamare le API Fleet Engine) e un ID veicolo di proprietà del fornitore Ridesharing o di consegna.

Un veicolo che non è stato aggiornato tramite UpdateVehicle dopo sette giorni verrà eliminato automaticamente. Chiamare CreateVehicle con una coppia ID provider/ID veicolo già esistente comporta un errore. Il caso dei veicoli che non vengono aggiornati di frequente può essere gestito in due modi: chiamando di frequente CreateVehicle con una coppia ID fornitore/ID veicolo prevista e ignorando l'errore se il veicolo esiste già; oppure chiamando CreateVehicle dopo il ritorno di un UpdateVehicle con un errore NOT_FOUND.

Aggiornamenti sulla posizione dei veicoli

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.

Tipi di veicoli

L'entità Veicolo contiene un campo obbligatorio VehicleType, che contiene un'enumerazione Category che può essere specificata come AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE o PEDESTRIAN. Il tipo di veicolo può fungere da criterio di filtro in SearchVehicles e ListVehicles.

Tutti i percorsi per i veicoli utilizzeranno il valore RouteTravelMode corrispondente se la categoria è impostata su AUTO, TWO_WHEELER, BICYCLE o PEDESTRIAN. Se la categoria è impostata su TAXI o TRUCK, il routing viene considerato come la modalità AUTO.

Attributi veicolo

L'entità Veicolo contiene un campo ripetuto di VehicleAttribute. Questi attributi non sono interpretati da Fleet Engine. L'API SearchVehicles include un campo per richiedere che la corrispondenza di Vehicles deve contenere tutti gli attributi inclusi impostati sul valore specificato.

Tieni presente che il campo dell'attributo si aggiunge a diversi altri campi supportati nel messaggio Vehicle, come vehicle_type e supported_trip_types.

Waypoint rimanenti del veicolo

L'entità Veicolo contiene un campo ripetuto di TripWaypoint (RPC | REST), denominato waypoints(RPC | REST). Questo campo include i waypoint rimanenti nelle corse, nell'ordine in cui il veicolo li raggiunge. Fleet Engine calcola questo campo man mano che le corse vengono assegnate al veicolo e lo aggiorna quando le corse cambiano il loro stato. Questi waypoint possono essere identificati dai campi TripId e WaypointType.

Ampliare l'idoneità di un veicolo per le corrispondenze

In genere, i servizi di Ridesharing o di Delivery Provider sono responsabili della corrispondenza delle richieste di viaggio ai veicoli. Il servizio può utilizzare gli attributi del veicolo per includere un veicolo in un numero maggiore di ricerche. Ad esempio, il fornitore può implementare un insieme di attributi corrispondenti ai livelli di vantaggi o funzionalità forniti da un veicolo. Ad esempio, tre livelli potrebbero essere un insieme di attributi con valori booleani: is_bronze_level, is_silver_level e is_gold_level. Un veicolo può essere idoneo per tutti e tre. Quando Fleet Engine riceve una richiesta per un viaggio che richiede funzionalità di livello argento, la ricerca include il veicolo. L'utilizzo degli attributi in questo modo include veicoli che offrono una varietà di funzionalità.

Esistono due modi per aggiornare gli attributi del veicolo. Una è l'API UpdateVehicle. Quando utilizzi questa API, l'intero set di attributi del veicolo è impostato sul valore. Non è possibile aggiornare soltanto un singolo attributo. L'altro metodo è l'API UpdateVehicleAttributes. Questo metodo richiede solo l'aggiornamento degli attributi. Gli attributi inclusi nella richiesta verranno impostati sul nuovo valore o aggiunti; gli attributi non specificati non verranno modificati.

GUIDA INTRODUTTIVA: creare un veicolo

È necessario creare un'entità Vehicle per ogni veicolo da monitorare nel parco risorse.

Usa l'endpoint CreateVehicle con CreateVehicleRequest per creare un Veicolo.

provider_id di Vehicle deve essere l'ID progetto (ad esempio progetto on demand) del progetto Google Cloud che contiene gli account di servizio che verranno utilizzati per chiamare il parco risorse. Tieni presente che mentre più account di servizio possono accedere a Fleet Engine per lo stesso Ridesharing o provider di consegne, Fleet Engine attualmente non supporta gli account di servizio di più progetti Google Cloud che accedono allo stesso Vehicles.

L'elemento Vehicle può essere creato in stato OFFLINE o ONLINE. Se viene creato ONLINE, può essere restituito immediatamente in risposta a SearchVehicles query.

Un last_location iniziale potrebbe essere incluso nella chiamata CreateVehicle. Sebbene sia consentito, non è necessario creare Vehicle nello stato ONLINE senza last_location.

Per informazioni dettagliate sul campo relativo al tipo di veicolo, consulta Tipi di veicolo.

Per informazioni dettagliate sul campo degli attributi, consulta Attributi del veicolo.

Il valore restituito da CreateVehicle è l'entità Vehicle creata.

Esempio

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "OFFLINE",
    "supportedTripTypes": ["EXCLUSIVE"],
    "maximumCapacity": 4,
    "vehicleType": {"category": "AUTO"},
    "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

Vedi il riferimento providers.vehicles.create.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)  // Initial state
    .addSupportedTripTypes(TripType.EXCLUSIVE)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .addAttributes(VehicleAttribute.newBuilder()
        .setKey("on_trip").setValue("false"))  // Opaque to the Fleet Engine
    // Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
    // matching while even if it is on a trip.  By default this is disabled.
    .build();

CreateVehicleRequest createVehicleRequest =
    CreateVehicleRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setVehicleId("vid-8241890")  // Vehicle ID assigned by Rideshare or Delivery Provider
        .setVehicle(vehicle)  // Initial state
        .build();

// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided.  When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.

try {
  Vehicle createdVehicle =
      vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle created successfully.

Log della piattaforma Google Cloud per la creazione del veicolo

L'API Fleet Engine scrive una voce di log tramite i log della piattaforma Google Cloud quando viene ricevuta una chiamata all'endpoint CreateVehicle. La voce di log include informazioni sui valori nella richiesta CreateVehicle. Se la chiamata ha esito positivo, saranno incluse anche le informazioni sul Vehicle che è stato restituito.

shell

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'

Devi stampare un record simile al seguente:

---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
  '@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
  request:
    vehicle:
      attributes:
      - key: on_trip
        value: 'false'
      maximumCapacity: 4
      state: VEHICLE_STATE_OFFLINE
      supportedTrips:
      - EXCLUSIVE_TRIP
      vehicleType:
        vehicleCategory: AUTO
    vehicleId: vid-8241890
  response:
    attributes:
    - key: on_trip
      value: 'false'
    availableCapacity: 4
    currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
    maximumCapacity: 4
    name: providers/project-id/vehicles/vid-8241890
    state: VEHICLE_STATE_OFFLINE
    supportedTrips:
    - EXCLUSIVE_TRIP
    vehicleType:
      vehicleCategory: AUTO
labels:
  vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
  labels:
    location: global
    resource_container: projects/project-id
  type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'

Notifiche Cloud Pub/Sub per la creazione di veicoli

L'API Fleet Engine pubblica una notifica tramite Cloud Pub/Sub quando viene creato un nuovo veicolo. Per ricevere queste notifiche, segui le istruzioni riportate qui.

TUTORIAL: aggiornare la posizione di un 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. Questi aggiornamenti richiedono solo i privilegi utente dell'SDK dei driver Fleet Engine.

Esempio

shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
}
EOM

Vedi il riferimento providers.vehicles.update.

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setLastLocation(VehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("last_location"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

GUIDA INTRODUTTIVA: aggiornare altri campi Veicolo

Gli aggiornamenti ad altri attributi dello stato del veicolo avvengono con minore frequenza rispetto agli aggiornamenti della posizione. Gli aggiornamenti ad attributi diversi da last_location richiedono i privilegi Super user di Fleet Engine.

L'elemento UpdateVehicleRequest include un update_mask per indicare i campi da aggiornare. Il comportamento del campo è come nella documentazione di Protobuf per le maschere di campo.

Come indicato in Attributi del veicolo, l'aggiornamento del campo attributes richiede la scrittura di tutti gli attributi da conservare. Non è possibile semplicemente aggiornare il valore di una coppia chiave-valore in una chiamata UpdateVehicle. Per aggiornare i valori di attributi specifici, è possibile utilizzare l'API UpdateVehicleAttributes.

Esempio

Questo esempio attiva back_to_back.

shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "on_trip", "value": "true"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

Vedi il riferimento providers.vehicles.update.

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_state")
        .addPaths("attributes")
        .addPaths("back_to_back_enabled"))
    .build();

// Attributes and vehicle state are being updated, so both are
// included in the field mask.  Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

Log della piattaforma Google Cloud per gli aggiornamenti dei veicoli

L'API Fleet Engine scrive una voce di log tramite i log della piattaforma Google Cloud quando viene ricevuta una chiamata all'endpoint UpdateVehicle. La voce di log include informazioni sui valori nella richiesta UpdateVehicle. Se la chiamata ha esito positivo, saranno incluse anche le informazioni sul Vehicle che è stato restituito.

shell

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'

Notifiche Cloud Pub/Sub per gli aggiornamenti del veicolo

L'API Fleet Engine pubblica una notifica tramite Cloud Pub/Sub quando un veicolo esistente viene aggiornato. Per ricevere queste notifiche, segui le istruzioni riportate qui.

GUIDA INTRODUTTIVA: Cerca veicoli

Fleet Engine supporta la ricerca di veicoli. L'API SearchVehicles consente di trovare i conducenti disponibili nelle vicinanze più adatti a svolgere un'attività, come la manutenzione di una corsa o di una richiesta di consegna. L'API SearchVehicles restituisce un elenco classificato di conducenti che corrispondono agli attributi delle attività con gli attributi dei veicoli del tuo parco risorse. Per maggiori informazioni, vedi Trovare conducenti nelle vicinanze.

Esempio

Durante la ricerca di veicoli disponibili, Fleet Engine esclude i veicoli su corse attive per impostazione predefinita. I servizi del Ridesharing o del fornitore di consegne devono includerli esplicitamente nelle richieste di ricerca. L'esempio seguente mostra come includere questi veicoli nella ricerca di veicoli corrispondenti a un viaggio dal Grand Indonesia East Mall al Balai Sidang Jakarta Convention Center.

shell

Innanzitutto aggiorna la posizione del veicolo che abbiamo creato nei passaggi precedenti in modo che sia idoneo. Nel mondo reale, ciò viene fatto tramite l'SDK Driver in esecuzione su un dispositivo Android o iOS nel veicolo.

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
    "location": {
      "latitude": "-6.195139",
      "longitude": "106.820826"
    }
  },
  "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

L'esecuzione della ricerca dovrebbe restituire almeno quel veicolo.

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  },
  "pickupRadiusMeters": 2000,
  "count": 10,
  "minimumCapacity": 2,
  "tripTypes": ["EXCLUSIVE"],
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
  "orderBy": "PICKUP_POINT_ETA",
  "includeBackToBack": true
}
EOM

Vedi il riferimento providers.vehicles.search.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jakarta Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);

  // Search results: Each vehicle match contains a vehicle entity and information
  // about the distance and ETA to the pickup point and dropoff point.
  List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Query di filtro dei veicoli

SearchVehicles e ListVehicles supportano il filtro sugli attributi del veicolo utilizzando una query di filtro. Per la sintassi delle query di filtro, consulta AIP-160 per gli esempi.

Tieni presente che le query di filtro supportano SOLO i filtri in base agli attributi del veicolo e non possono essere utilizzate per altri campi. La query di filtro funziona come una clausola AND con altri vincoli, come minimum_capacity o vehicle_types in SearchVehiclesRequest.

GUIDA INTRODUTTIVA: elencare i veicoli

SearchVehicles è ottimizzato per trovare molto rapidamente un numero limitato di veicoli in ordine di ordinamento e viene utilizzato principalmente per trovare i conducenti più adatti a un'attività nelle vicinanze. Tuttavia, a volte potresti voler trovare tutti i veicoli che soddisfano alcuni criteri, anche se è necessario sfogliare i risultati. ListVehicles è progettato per quel caso d'uso.

L'API ListVehicles consente di trovare tutti i veicoli che soddisfano alcune opzioni di richiesta specifiche. L'API ListVehicles restituisce un elenco impaginato dei veicoli nel progetto che soddisfa alcuni requisiti.

Per filtrare in base agli attributi dei veicoli, consulta Query di filtro dei veicoli.

Esempio

In questo esempio vengono applicati filtri su vehicle_type e attributi utilizzando la stringa filter.

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
}
EOM

Vedi il riferimento providers.vehicles.list.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
    .setParent(parent)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  ListVehiclesResponse listVehiclesResponse =
      vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Viaggi e ciclo di vita

L'API Trip e il suo ciclo di vita sono simili all'API Vehicle e al ciclo di vita. Il provider di Ridesharing è responsabile della creazione delle corse utilizzando le interfacce di Fleet Engine. Fleet Engine fornisce sia un servizio RPC TripService sia risorse REST, provider.trips . Queste interfacce consentono la creazione di entità Trip, le richieste di informazioni, la funzionalità di ricerca e la capacità di aggiornamento.

Un elemento Trip ha un campo di stato per monitorare l'avanzamento nel ciclo di vita. I valori si spostano da NEW a COMPLETE più CANCELED e UNKNOWN_TRIP_STATUS. Consulta trip_status per RPC o TripStatus per REST.

  • NEW
  • ENROUTE_TO_PICKUP
  • ARRIVED_AT_PICKUP
  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETE

Il tuo servizio può aggiornare la corsa a CANCELED da uno qualsiasi di questi stati. Quando il servizio crea una corsa, il motore imposta lo stato su NEW. L'elemento vehicle_id è facoltativo. Come per i veicoli, i servizi eliminano automaticamente le corse dopo sette giorni senza un aggiornamento. Se il servizio tenta di creare una corsa con un ID già esistente, viene restituito un errore. Una corsa è considerata "attiva" se in uno stato diverso da COMPLETE o CANCELED. Questa distinzione è importante nel campo active_trips nell'entità Veicolo e in SearchTripsRequest.

Il servizio può modificare il vehicle_id assegnato a un Viaggio solo quando lo stato è NEW o CANCELED. Se un conducente annulla una corsa durante il percorso, lo stato della corsa deve essere impostato su NEW o CANCELED prima che vehicle_id venga modificato o cancellato.

Lo stato è importante quando si implementa il supporto di viaggio back-to-back. Questo supporto consente al Fornitore di assegnare una nuova corsa a un Veicolo mentre è in corso una corsa attiva. Il codice per la creazione di una corsa back-to-back è uguale a una singola corsa e utilizza lo stesso ID veicolo. Fleet Engine aggiunge l'origine e la destinazione della nuova corsa ai waypoint del veicolo. Per ulteriori informazioni sui viaggi uno dopo l'altro, consulta Creare viaggi a più tappe.

Waypoint rimanenti del viaggio

L'entità Trip contiene un campo ripetuto di TripWaypoint (RPC | REST), denominato remainingWaypoints(RPC | REST). Questo campo include tutti i waypoint che il veicolo dovrà percorrere in ordine prima del punto di partenza finale di questa corsa. Viene calcolato in base ai waypoint rimanenti del veicolo. Nei casi d'uso di tipo back-to-back e Carpool, questo elenco contiene i waypoint di altri viaggi che verranno attraversati prima di questo viaggio, ma esclude eventuali waypoint dopo questo viaggio. Il waypoint nell'elenco può essere identificato dai relativi TripId e WaypointType.

La relazione tra lo stato della corsa e i waypoint rimanenti del veicolo

I waypoint rimanenti del veicolo (RPC | REST) verranno aggiornati quando Fleet Engine riceve una richiesta di modifica dello stato della corsa. Il waypoint precedente verrà rimosso dall'elenco di waypoint rimanenti del veicolo quando lo stato tripStatus(RPC | REST) verrà modificato da altro stato a ENROUTE_TO_XXX. In altre parole, se lo stato del viaggio passa da ENROUTE_TO_PICKUP ad ARRIVED_AT_PICKUP, il punto di ritiro della corsa continuerà a essere nell'elenco dei tappe rimanenti del veicolo, ma se lo stato della corsa viene modificato in ENROUTE_TO_INTERMEDIATE_DESTINATION o ENROUTE_TO_DROPOFF, il punto di ritiro verrà rimosso dall'elenco dei tappe rimanenti.

Questo vale per ARRIVED_AT_INTERMEDIATE_DESTINATION ed ENROUTE_TO_INTERMDEDIATE_DESTINATION. Quando ARRIVED_AT_INTERMEDIATE_DESTINATION, la destinazione intermedia corrente non viene rimossa dall'elenco dei waypoint rimanenti finché il veicolo non segnala che raggiunge il waypoint successivo.

Se lo stato della corsa viene modificato in COMPLETED, nessun waypoint di questa corsa sarà nell'elenco dei waypoint rimanenti del veicolo.

GUIDA INTRODUTTIVA: Creare un viaggio

È necessario creare un'entità Trip per consentire il monitoraggio di ogni richiesta di viaggio e l'associazione ai veicoli del parco risorse. Usa l'endpoint CreateTrip con CreateTripRequest per creare un Trip.

Per creare una corsa sono necessari i seguenti attributi:

  • parent: una stringa che include l'ID provider creato al momento della creazione del progetto Google Cloud.
  • trip_id: una stringa creata dal fornitore di Ridesharing.
  • trip: container con metadati di base che descrivono la corsa.
    • trip_type - Enum che indica se la corsa potrebbe includere altri passeggeri di origine e destinazione diverse nello stesso veicolo (SHARED) o solo in una singola parte (EXCLUSIVE).
    • pickup_point: TerminalLocation che rappresenta il punto di partenza della corsa. Fai riferimento al riferimento RPC o al riferimento REST

Quando crei un viaggio, puoi fornire i seguenti elementi: number_of_passengers, dropoff_point e vehicle_id. Sebbene questi campi non siano obbligatori, se li fornisci, vengono conservati. Tutti gli altri campi Viaggio vengono ignorati. Ad esempio, tutte le corse iniziano con un valore trip_status pari a NEW anche se passi in un valore trip_status di CANCELED nella richiesta di creazione.

Esempio

Nell'esempio seguente viene creata una corsa al Grand Indonesia East Mall. Il viaggio è esclusivo per due passeggeri. Il provider_id di Trip deve essere uguale all'ID progetto. Nell'esempio, il provider di Ridesharing ha creato il progetto Google Cloud project-id. Questo progetto deve disporre degli account di servizio utilizzati per chiamare Fleet Engine. Lo stato della corsa è NEW.

In seguito, dopo che il servizio associa la corsa a un veicolo, può chiamare UpdateTrip e modificare la vehicle_id quando la corsa è assegnata a un veicolo.

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "tripType": "EXCLUSIVE",
  "numberOfPassengers": 2,
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  }
}
EOM

Vedi il riferimento providers.trips.create.

Java

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
    .setPickupPoint(                 // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    // Provide the number of passengers if available.
    .setNumberOfPassengers(2)
    // Provide the drop-off point if available.
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
    .build();

CreateTripRequest createTripRequest =
    CreateTripRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setTripId("tid-1f97")  // Trip ID assigned by the Provider
        .setTrip(trip)              // Initial state
        .build();

// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.

try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Log della piattaforma Google Cloud per la creazione dei viaggi

L'API Fleet Engine scrive una voce di log utilizzando i log della piattaforma Google Cloud quando viene ricevuta una chiamata all'endpoint CreateTrip. La voce di log include informazioni sui valori nella richiesta CreateTrip. Se la chiamata ha esito positivo, saranno incluse anche le informazioni relative al Trip che è stato restituito.

Istruzioni: aggiornare un viaggio

L'entità Trip contiene campi che consentono il monitoraggio da parte del servizio e per segnalare l'avanzamento del viaggio tramite l'SDK Driver e l'SDK consumer. Per aggiornare le proprietà, utilizza il messaggio UpdateTripRequest. Questa operazione aggiorna i campi Viaggio in base alle field_mask della richiesta. Consulta UpdateTripRequest.

Il fornitore di Ridesharing è responsabile dell'aggiornamento dei seguenti attributi:

  • Stato del viaggio.
  • ID veicolo. al momento della creazione o dopo aver abbinato il veicolo a una corsa.
  • Modifiche relative a prelievo, consegna o waypoint.

Fleet Engine aggiorna automaticamente i seguenti campi quando utilizzi la funzionalità di condivisione del percorso tramite l'SDK Driver o l'SDK consumer:

  • Route
  • Orario di arrivo stimato
  • Distanza rimanente
  • Posizione del veicolo
  • Waypoint rimanenti

Fai riferimento a Tripin RPC o Resource.Trip in REST.

Log della piattaforma Google Cloud per gli aggiornamenti sui viaggi

L'API Fleet Engine scrive una voce di log utilizzando i log della piattaforma Google Cloud quando viene ricevuta una chiamata all'endpoint UpdateTrip. La voce di log include informazioni sui valori nella richiesta UpdateTrip. Se la chiamata ha esito positivo, verranno incluse anche informazioni sul Trip che è stato restituito.

GUIDA INTRODUTTIVA: Cercare i viaggi

Fleet Engine supporta la ricerca di viaggi. Come indicato in precedenza, un Viaggio viene eliminato automaticamente dopo sette giorni, pertanto SearchTrips non mostra una cronologia completa di tutti i Viaggi.

Sebbene SearchTrips sia un'API flessibile, nell'elenco riportato di seguito vengono presi in considerazione due casi d'uso.

  • Determinazione delle corse attive di un veicolo: il fornitore può determinare le corse attualmente attive di un veicolo. All'interno di SearchTripsRequest, l'attributo vehicle_id è impostato sul veicolo in esame e il valore active_trips_only deve essere impostato su true.

  • Riconciliazione dello stato del provider e di Fleet Engine: il provider può utilizzare SearchTrips per garantire la corrispondenza dello stato della corsa con quello di Fleet Engine. Questo è particolarmente importante per TripStatus. Se lo stato di una corsa assegnata a un veicolo non è impostato correttamente su COMPLETE o CANCELED, il veicolo non è incluso da SearchVehicles.

Per utilizzare SearchTrips in questo modo, lascia il campo vehicle_id vuoto, imposta active_trips_only su true e imposta minimum_staleness su un intervallo di tempo superiore alla maggior parte delle durate del viaggio. Ad esempio, puoi utilizzare un'ora. I risultati includono i viaggi che non sono COMPLETATI né ANNULLATI e che non sono stati aggiornati da oltre un'ora. Il provider deve esaminare questi viaggi per garantire che il loro stato in Fleet Engine sia aggiornato correttamente.

Risolvere i problemi

In caso di errore DEADLINE_EXCEEDED, lo stato di Fleet Engine è sconosciuto. Il provider dovrebbe chiamare di nuovo CreateTrip, che restituisce un errore 201 (CREATED) o 409 (CONFLICT). Nel secondo caso, la richiesta precedente è andata a buon fine prima del giorno DEADLINE_EXCEEDED. Consulta le guide alle API Consumer per ulteriori informazioni sulla gestione degli errori di viaggio: Android o iOS.

Assistenza per le corse in carpooling

Puoi assegnare più corse SHARED a un veicolo che supporta TripType.SHARED. Devi specificare l'ordine di tutti i waypoint non superati per tutti i viaggi assegnati al veicolo in questa corsa condivisa tramite Trip.vehicle_waypoints quando assegni il vehicle_id a un viaggio condiviso (in una richiesta CreateTrip o UpdateTrip). Fai riferimento a vehicle_waypoints per RPC o vehicleWaypoints per REST.

Supporto di più destinazioni

Identifica una destinazione intermedia

I campi intermediateDestinations e intermediateDestinationIndex in Trip (RPC | REST) vengono combinati per essere utilizzati per indicare la destinazione.

Aggiorna destinazione intermedia

Puoi aggiornare le destinazioni intermedie tramite UpdateTrip. Quando aggiorni le destinazioni intermedie, devi fornire un elenco completo delle destinazioni intermedie, comprese quelle che sono state visitate, non solo quella appena aggiunta o da modificare. Quando intermediateDestinationIndex rimanda a un indice dopo la posizione della destinazione intermedia appena aggiunta/modificata, la destinazione intermedia nuova/aggiornata non verrà aggiunta al waypoints del veicolo o al remainingWaypoints del viaggio. Il motivo è che tutte le destinazioni intermedie prima del giorno intermediateDestinationIndex vengono trattate come già visitate.

Modifiche allo stato del viaggio

Il campo intermediateDestinationsVersion in (RPC | REST) è obbligatorio nella richiesta di aggiornamento dello stato del viaggio inviata a Fleet Engine per indicare che una destinazione intermedia è stata superata. La destinazione intermedia target viene specificata tramite il campo intermediateDestinationIndex. Quando tripStatus (RPC | REST) è ENROUTE_TO_INTERMEDIATE_DESTINATION, un numero compreso tra [0..N-1] indica la destinazione intermedia che il veicolo attraverserà. Quando tripStatus è ARRIVED_AT_INTERMEDIATE_DESTINATION, un numero compreso tra [0..N-1] indica a quale destinazione intermedia si trova il veicolo.

Esempio

Il seguente esempio di codice mostra come aggiornare lo stato di una corsa in modo da raggiungere la prima destinazione intermedia, supponendo che tu abbia creato una corsa con più destinazioni e che la corsa abbia superato il punto di partenza.

Java

static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to update.
Trip trip = Trip.newBuilder()
    // Trip status cannot go back to a previous status once it is passed
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
    // Enrouting to the first intermediate destination.
    .setIntermediateDestinationIndex(0)
    // intermediate_destinations_version MUST be provided to ensure you
    // have the same picture on intermediate destinations list as FleetEngine has.
    .setIntermediateDestinationsVersion(
        trip.getIntermediateDestinationsVersion())
    .build();

// Trip update request
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(
            FieldMask.newBuilder()
                .addPaths("trip_status")
                .addPaths("intermediate_destination_index")
                // intermediate_destinations_version must not be in the
                // update mask.
                .build())
        .build();

// Error handling
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:  // Trip does not exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid, or the
                                // intermediate_destinations_version
                                // doesn’t match FleetEngine’s.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

GUIDA INTRODUTTIVA: Iscrizione ai messaggi di notifica dall'API Fleet Engine

L'API Fleet Engine utilizza Google Cloud Pub/Sub per pubblicare notifiche sull'argomento creato dal progetto consumer di Google Cloud. Pub/Sub non è abilitato per impostazione predefinita per Fleet Engine nel tuo progetto Google Cloud. Invia una richiesta di assistenza o contatta il tuo Customer Engineer per attivare Pub/Sub.

Per creare un argomento nel tuo progetto Cloud, segui queste istruzioni. L 'ID argomento deve essere "fleet_engine_notifications.

L'argomento deve essere creato nello stesso progetto Cloud che chiama le API Fleet Engine.

Una volta creato l'argomento, devi concedere l'autorizzazione API Fleet Engine per pubblicare nell'argomento. A questo scopo, fai clic sull'argomento appena creato e aggiungi una nuova autorizzazione. Potresti dover fare clic su MOSTRA RIQUADRO INFORMAZIONI per aprire l'editor delle autorizzazioni. L'entità deve essere geo-fleet-engine@system.gserviceaccount.com e il ruolo deve essere Pub/Sub publisher.

Per configurare il tuo progetto Cloud in modo da iscriverti alle notifiche, segui queste istruzioni

L'API Fleet Engine pubblicherà ogni notifica in due diversi formati dei dati: protobuf e json. Il formato dei dati per ogni notifica è indicato negli attributi PubsubMessage con la chiave come data_format e il valore come protobuf o json.

Schema di notifica:

Protobuf

// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
  // Required. At least one notification must exist.
  // List of notifications containing information related to changes in
  // Fleet Engine data.
  repeated Notification notifications = 1;
}

// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
  // Required. At least one type must exist.
  // Type of notification.
  oneof type {
    // Notification related to changes in vehicle data.
    VehicleNotification vehicle_notification = 1;
  }
}

// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
  // Required.
  // Vehicle must contain all fields that were set when it was created.
  Vehicle vehicle = 1;
}

// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
  // Required.
  // Vehicle must only contain name and fields that are present in the
  // field_mask field below.
  Vehicle vehicle = 1;

  // Required.
  // Contains vehicle field paths that were specifically requested
  // by the Provider.
  google.protobuf.FieldMask field_mask = 2;
}

// Notification related to changes in vehicle data.
message VehicleNotification {
  // Required. At least one type must be set.
  // Type of notification.
  oneof type {
    // Notification sent when a new vehicle was created.
    CreateVehicleNotification create_notification = 1;
    // Notification sent when an existing vehicle is updated.
    UpdateVehicleNotification update_notification = 2;
  }
}

JSON

BatchNotification: {
  "description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
  "type": "object",
  "required": ["notifications"],
  "properties": {
    "notifications": {
      "description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
      "type": "Notification[]"
    }
  }
}

Notification: {
  "description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
  "type": "object",
  "properties": {
    "vehicleNotification": {
      "description": "Notification related to changes in vehicle data.",
      "type": "VehicleNotification"
    }
  }
}

VehicleNotification: {
  "description": "Notification related to changes in vehicle data.",
  "type": "object",
  "properties": {
    "createNotification": {
      "description": "Notification sent when a new vehicle was created.",
      "type": "CreateVehicleNotification"
    },
    "updateNotification": {
      "description": "Notification sent when an existing vehicle is updated.",
      "type": "UpdateVehicleNotification"
    }
  }
}

CreateVehicleNotification: {
  "description": "Notification sent when a new vehicle was created.",
  "type": "object",
  "required": ["vehicle"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must contain all fields that were set when it was created.",
      "type": "Vehicle"
    }
  }
}

UpdateVehicleNotification: {
  "description": "Notification sent when an existing vehicle is updated.",
  "type": "object",
  "required": ["vehicle", "fieldMask"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
      "type": "Vehicle"
    },
    "fieldMask": {
      "description": "Contains vehicle field paths that were specifically requested by the Provider.",
      "type": "FieldMask"
    }
  }
}