L'API On-demand Rides and Deliveries di Fleet Engine consente di gestire le corse e lo stato dei veicoli per le applicazioni di avanzamento dei viaggi e degli ordini. Gestisce le transazioni tra l'SDK Driver, l'SDK consumer e il tuo 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 eseguire l'autenticazione nel progetto.
shell
gcloud auth login
Dovresti visualizzare un messaggio che indica che l'operazione è riuscita, ad esempio:
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 Fleet Engine siano configurate correttamente.
shell
gcloud --project=project-id services enable fleetengine.googleapis.com
Se questo comando genera 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 relativi alle chiamate API che riceve 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 contribuiranno a fornire una migliore esperienza per gli sviluppatori su REST o gRPC non elaborati. Per istruzioni su come ottenere le librerie client per la tua applicazione server, vedi Librerie client.
Gli esempi Java in questa documentazione presuppongono familiarità con gRPC.
Autenticazione e autorizzazione
Puoi configurare le funzionalità fornite da Trip and Order Avanzamento 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 da Cloud Console.
Configurazione del progetto Cloud
Per configurare il progetto Cloud, crea prima il progetto e poi gli account di servizio.
Per creare un progetto Google Cloud:
- Creare un progetto Google Cloud utilizzando la console Google Cloud.
- Utilizzando le API e la dashboard dei 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 insiemi diversi di autorizzazioni 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.
Lo stato di avanzamento del viaggio e dell'ordine utilizza i seguenti ruoli:
Ruolo | Descrizione |
---|---|
Utente SDK consumer di Fleet Engine
roles/fleetengine.consumerSdkUser |
Concede l'autorizzazione a cercare 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 della tua app consumer per la ridesharing o la consegna. |
Utente SDK driver di Fleet Engine
roles/fleetengine.driverSdkUser |
Concede l'autorizzazione ad 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 per il ridesharing o per le 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 tuoi 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 si basano 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 di ruoli standard presentato sopra 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 con 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 di Fleet Engine
Fleet Engine utilizza token JWT (JSON Web Token) per limitare l'accesso alle API di 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
Quando non utilizzi la libreria di autenticazione Fleet Engine, i token web JSON (JWT) devono essere creati direttamente all'interno del codebase. A tal fine, è necessario conoscere approfonditamente i JWT e il loro rapporto con Fleet Engine. Ecco perché consigliamo vivamente di sfruttare la libreria di autenticazione Fleet Engine.
All'interno di Fleet Engine, i token web JSON (JWT) 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 di intestazione contiene informazioni come la chiave privata da utilizzare (ottenuta dagli account di servizio) e l'algoritmo di crittografia. La sezione delle richieste contiene informazioni quali data e ora di creazione del token, durata dei token, servizi per i quali richiede l'accesso e altre informazioni sull'autorizzazione per limitare l'accesso, ad esempio l'ID veicolo.
Una sezione di intestazione JWT contiene i seguenti campi:
Campo | Descrizione |
---|---|
Alg | L'algoritmo da utilizzare. "RS256". |
typ | Il tipo di token. "JWT". |
bambino | ID chiave privata dell'account di servizio. Puoi trovare questo valore nel campo "private_key_id" del file JSON dell'account di servizio. Assicurati di utilizzare una chiave di un account di servizio con il livello di autorizzazioni corretto. |
Una sezione relativa alle rivendicazioni JWT contiene i seguenti campi:
Campo | Descrizione |
---|---|
è | L'indirizzo email dell'account di servizio. |
sub | L'indirizzo email dell'account di servizio. |
Aud | SERVICE_NAME del tuo account di servizio, in questo caso https://fleetengine.googleapis.com/ |
IAT | Il timestamp del momento in cui è stato creato il token, specificato in secondi trascorsi dalle 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 della scadenza del token, specificato in secondi trascorsi dalle 00:00:00 UTC, 1° gennaio 1970. La richiesta non va a buon fine se il timestamp è a più di un'ora nel futuro. |
authorization | A seconda del caso d'uso, potrebbe contenere "vehicleid" o "tripid". |
Per creare un token JWT si intende la firma del token. Per istruzioni ed esempi di codice per la creazione e la firma del 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.
Rivendicazioni JWT
Quando crei il payload JWT, aggiungi un'altra richiesta nella sezione dell'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
, sia che si tratti di un viaggio o di un veicolo. Il backend di Fleet Engine assicura che il veicolo sia associato alla corsa richiesta prima di apportare la modifica.
L'SDK consumer utilizza sempre la rivendicazione tripid
.
Il fornitore di Ridesharing o di consegna 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 token di esempio 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 App consumer:
{
"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
dell'intestazione, specifica l'ID della chiave privata dell'account di servizio. Puoi trovare questo valore nel campoprivate_key_id
del file JSON dell'account di servizio. - Nei campi
iss
esub
, specifica l'indirizzo email del tuo account di servizio. Puoi trovare questo valore nel campoclient_email
del file JSON del tuo account di servizio. - Per il campo
aud
, specifica https://SERVICE_NAME/. - Per il campo
iat
, utilizza il timestamp del momento della creazione del token, specificato come secondi trascorsi dalle 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 firmi il JWT da trasmettere a un dispositivo mobile, assicurati di utilizzare l'account di servizio per il ruolo SDK Driver o Consumer. In caso contrario, il dispositivo mobile avrà la possibilità di modificare lo stato che non dovrebbe avere.
Allo stesso modo, quando firmi il JWT da utilizzare per le chiamate con privilegi, 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
Durante i test può essere utile generare token dal terminale.
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 indicati di seguito. La proprietà iat
indica l'ora corrente in numero di secondi dopo il periodo, che può essere recuperata eseguendo date +%s
nel terminale. La proprietà exp
indica il tempo di scadenza in secondi dopo l'epoca, che può essere calcolato aggiungendo 3600 a iat
. La data di 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 il seguente 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
Un JWT firmato con codifica Base64 ora dovrebbe essere archiviato all'interno del file signed_token.jwt
. Il token è 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 conducente-veicolo. Al momento, un conducente e un veicolo non possono essere monitorati separatamente. Il fornitore di Ridesharing o di consegna crea un veicolo utilizzando un ID fornitore (che deve essere uguale all'ID progetto del progetto Google Cloud contenente l'account di servizio utilizzato per chiamare le API di 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 restituisce un errore. Il caso dei veicoli che
non vengono aggiornati di frequente può essere gestito in due modi: chiamando spesso
CreateVehicle
con una coppia di ID fornitore/ID veicolo prevista ed eliminando
l'errore se il veicolo esiste già; oppure chiamando CreateVehicle
dopo che
UpdateVehicle
viene restituito con un errore NOT_FOUND
.
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ò essere utilizzato come
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à Vehicle contiene un campo ripetuto di VehicleAttribute
. Questi attributi non sono interpretati da Fleet Engine. L'API SearchVehicles
include un campo per richiedere che Vehicles
corrispondente debba contenere tutti
gli attributi inclusi impostati sul valore specificato.
Tieni presente che il campo dell'attributo si aggiunge a molti altri campi supportati
nel messaggio Vehicle
, come vehicle_type
e supported_trip_types
.
Waypoint rimanenti del veicolo
L'entità Vehicle contiene un campo ripetuto di TripWaypoint
(RPC | REST),
chiamato waypoints
(RPC | REST).
Questo campo include i tappe 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 modificano il loro stato.
Questi tappe possono essere identificati dai campi TripId
e WaypointType
.
Aumentare l'idoneità di un veicolo per le corrispondenze
In genere, i servizi di Ridesharing o di consegna sono responsabili della corrispondenza tra le richieste di viaggio e i veicoli. Il servizio può utilizzare gli attributi dei veicoli 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 di viaggio che richiede funzionalità di livello argento, la ricerca include il veicolo.
L'utilizzo di attributi in questo modo include veicoli che offrono una varietà di funzionalità.
Esistono due modi per aggiornare gli attributi dei veicoli. Una è l'API UpdateVehicle
, Quando utilizzi questa API, l'intero set di attributi del veicolo è impostato su questo valore. Non è possibile aggiornare semplicemente un singolo attributo.
L'altro metodo è l'API UpdateVehicleAttributes
. Questo metodo richiede solo
gli attributi da aggiornare. Gli attributi inclusi nella richiesta verranno impostati sul nuovo valore o aggiunti; gli attributi non specificati non verranno modificati.
GUIDA ILLUSTRATIVA: 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.
Il valore 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, sebbene più account di servizio possano accedere a Fleet Engine per lo stesso Ridesharing o provider di distribuzione, al momento Fleet Engine non supporta gli account di servizio di più progetti Google Cloud che accedono allo stesso Vehicles
.
Vehicle
può essere creato nello stato OFFLINE
o ONLINE
. Se
creato ONLINE
, può essere restituito immediatamente in risposta alle query
SearchVehicles
.
È possibile che nella chiamata CreateVehicle
sia incluso un last_location
iniziale.
Sebbene sia consentito, non è consentito creare un Vehicle
in stato ONLINE
senza
un last_location
.
Per maggiori dettagli sul campo relativo al tipo di veicolo, consulta Tipi di veicoli.
Per maggiori dettagli sul campo degli attributi, consulta Attributi dei veicoli.
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 di Google Cloud Platform per la creazione di veicoli
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, verranno incluse anche informazioni sull'oggetto 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"
'
Deve essere stampato 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.
GUIDA ILLUSTRATIVA: aggiornare un veicolo
UpdateVehicle
viene utilizzato per aggiornare lo stato di Vehicle
. Gli aggiornamenti si suddividono
in due categorie.
Aggiornamento della posizione del veicolo
L'SDK Driver aggiorna spesso i last_location
del veicolo. Questi aggiornamenti richiedono solo i privilegi Utente SDK Driver di Fleet Engine. Fleet Engine
ottimizza gli aggiornamenti della posizione del veicolo.
Aggiorna l'altro stato del veicolo
Gli aggiornamenti di 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.
UpdateVehicleRequest
include un update_mask
per indicare quali campi aggiornare. Il comportamento del campo è come nella documentazione di Protobuf per le maschere del campo.
Come indicato in Attributi dei veicoli, l'aggiornamento del campo attributes
richiede la scrittura di tutti gli attributi da conservare. Non è possibile aggiornare semplicemente il valore di una coppia chiave-valore in una chiamata UpdateVehicle
. Per aggiornare i valori di attributi specifici, è possibile utilizzare l'API UpdateVehicleAttributes
.
Esempio
In questo esempio viene attivata l'autorizzazione 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, verranno incluse anche informazioni sull'oggetto 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 dei veicoli
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: Cerca veicoli
Fleet Engine supporta la ricerca di veicoli. L'API SearchVehicles
ti consente di trovare i conducenti disponibili nelle vicinanze più adatti a un'attività come la manutenzione di una corsa o una richiesta di consegna. L'API SearchVehicles
restituisce un elenco classificato di conducenti che corrispondono agli attributi dell'attività con gli attributi dei veicoli nel tuo parco risorse. Per ulteriori informazioni, consulta la sezione Trovare conducenti nelle vicinanze.
Esempio
Durante la ricerca dei veicoli disponibili, Fleet Engine esclude i veicoli sulle corse attive per impostazione predefinita. I servizi di Ridesharing o di consegna devono includerli esplicitamente nelle richieste di ricerca. L'esempio seguente mostra come includere questi veicoli nella ricerca di veicoli che corrispondono a una corsa dal Grand Indonesia East Mall al Balai Sidang Jakarta Convention Center.
shell
Per prima cosa, aggiorna la posizione del veicolo che abbiamo creato nei passaggi precedenti, in modo che sia idoneo. Nel mondo reale, questa operazione viene eseguita dall'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
La 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 filtro veicolo
SearchVehicles
e ListVehicles
supportano l'applicazione di filtri in base agli attributi dei veicoli utilizzando una query di filtro. Per la sintassi delle query di filtro, consulta AIP-160 per alcuni esempi.
Tieni presente che le query di filtro supportano SOLO il filtro in base agli attributi dei veicoli 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 ILLUSTRATIVA: elencare i veicoli
SearchVehicles
è ottimizzato per trovare molto rapidamente un numero ridotto di veicoli in ordine di importanza ed è utilizzato principalmente per trovare i conducenti nelle vicinanze più adatti a un'attività. Tuttavia, a volte potresti voler trovare tutti i veicoli che soddisfano alcuni criteri, anche se è necessario sfogliare i risultati. ListVehicles
è progettato per questo caso d'uso.
L'API ListVehicles
ti 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 corrisponde ad alcuni requisiti.
Per filtrare in base agli attributi dei veicoli, consulta Query relativa al filtro dei veicoli.
Esempio
Questo esempio esegue l'applicazione di filtri su vehicle_type
e sugli 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 a 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 relativo ciclo di vita
L'API Trip e il ciclo di vita sono simili all'API Vehicle e al ciclo di vita.
Il provider Ridesharing è responsabile della creazione delle corse utilizzando le interfacce di Fleet Engine. Fleet Engine fornisce un servizio RPC,
TripService
e risorse REST, provider.trips
. Queste interfacce consentono la creazione di entità Viaggio, le richieste di informazioni, la funzionalità di ricerca e la funzionalità di aggiornamento.
Un elemento Trip
include un campo di stato per monitorare l'avanzamento lungo il ciclo di vita.
I valori vengono spostati 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 servizio può aggiornare la corsa per CANCELED
da uno di questi stati.
Quando il servizio crea una corsa, il motore imposta lo stato su NEW
. Un
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à Vehicle e SearchTripsRequest
.
Il servizio può modificare l'elemento vehicle_id
assegnato a un Trip 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 durante l'implementazione del supporto per viaggi di ritorno. Questo supporto consente al fornitore di assegnare una nuova corsa a un veicolo mentre quel veicolo è attivo. 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 pointpoint del veicolo. Per ulteriori informazioni sui viaggi consecutivi, vedi Creare viaggi con più tappe.
Waypoint rimanenti del viaggio
L'entità Viaggio contiene un campo ripetuto di TripWaypoint
(RPC | REST),
chiamato remainingWaypoints
(RPC | REST).
Questo campo include tutti i tappe che il veicolo dovrà percorrere in ordine prima del punto di partenza della corsa. Viene calcolata dai
pointpoint rimanenti del veicolo.
Nei casi d'uso back-to-back e Carpool, questo elenco contiene tappe di altri viaggi che verranno attraversati prima di questo viaggio, ma esclude eventuali tappe successive. Il Waypoint nell'elenco può essere identificato dai relativi TripId
e WaypointType
.
La relazione tra lo stato della corsa e i punti intermedi del veicolo rimanenti
I pointpoint 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 tappe rimanenti del veicolo quando
il valore di tripStatus
(RPC | REST)
verrà modificato da un altro stato a ENROUTE_TO_XXX. In altre parole, se lo stato della corsa viene modificato da ENROUTE_TO_PICKUP ad ARRIVED_AT_PICKUP, il punto di ritiro della corsa sarà ancora nell'elenco dei tappe rimanenti del veicolo, ma quando lo stato della corsa viene cambiato in ENROUTE_TO_INTERMEDIATE_DESTINATION o ENROUTE_TO_DROPOFF, il punto di ritiro verrà rimosso dal percorso rimanente del veicolo.
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 passaggi restanti del veicolo finché il veicolo non segnala che sta seguendo il percorso successivo.
Se lo stato della corsa viene modificato in COMPLETED
, nessun tappa di questa corsa sarà
nell'elenco dei tappe rimanenti del veicolo.
GUIDA ILLUSTRATIVA: Creare un viaggio
È necessario creare un'entità Trip
affinché ogni richiesta di viaggio venga monitorata e abbinata ai veicoli del parco risorse. Utilizza 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 il viaggio.trip_type
: enum che rappresenta 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 a Riferimento RPC o Riferimento REST
Quando crei un viaggio, puoi fornire number_of_passengers
, dropoff_point
e vehicle_id
. Sebbene questi campi non siano obbligatori, se li fornisci, vengono conservati. Tutti gli altri campi Trip vengono ignorati. Ad esempio, tutte le corse
iniziano con un trip_status
pari a NEW
anche se superi un valore trip_status
di
CANCELED
nella richiesta di creazione.
Esempio
Nell'esempio seguente viene creata una corsa al Grand Indonesia East Mall. La corsa è esclusiva per due passeggeri. provider_id
di Trip
deve essere
uguale all'ID progetto. Nell'esempio, il provider Ridesharing ha creato il progetto Google Cloud project-id. Questo progetto deve avere gli account di servizio utilizzati per chiamare Fleet Engine. Lo stato della corsa è NEW
.
Successivamente, dopo che il servizio associa la corsa a un veicolo, può chiamare
UpdateTrip
e modificare vehicle_id
quando la corsa viene 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, verranno incluse anche informazioni sull'oggetto Trip
restituito.
GUIDA ILLUSTRATIVA: aggiornare un viaggio
L'entità Trip contiene campi che consentono il monitoraggio da parte del servizio e
per segnalare l'avanzamento della corsa tramite l'SDK Driver e
l'SDK Consumer. Per aggiornare le proprietà, utilizza il messaggio UpdateTripRequest
. I campi Corsa vengono aggiornati in base alle field_mask
della richiesta.
Fai riferimento a UpdateTripRequest.
Il Fornitore di Ridesharing è responsabile dell'aggiornamento dei seguenti attributi:
- Stato della corsa.
- ID veicolo. al momento della creazione o dopo aver abbinato il veicolo a una corsa.
- Modifiche relative a ritiro, discesa o tappe.
Fleet Engine aggiorna automaticamente i campi seguenti quando si utilizza 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
Consulta Trip
in RPC o Resource.Trip
in REST.
Log di Google Cloud Platform per Trip Updates
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 su Trip
restituito.
GUIDA ILLUSTRATIVA: Cerca viaggi
Fleet Engine supporta la ricerca di corse. 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 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. In
SearchTripsRequest
,vehicle_id
è impostato sul veicolo in considerazione eactive_trips_only
deve essere impostato sutrue
.Riconciliazione dello stato del provider e del parco risorse: il fornitore può utilizzare
SearchTrips
per garantire la corrispondenza tra lo stato della corsa e quello di Fleet Engine. Questo è particolarmente importante per TripStatus. Se lo stato di una corsa assegnato a un veicolo non è impostato correttamente suCOMPLETE
oCANCELED
, il Veicolo non è incluso daSearchVehicles
.
Per utilizzare SearchTrips
in questo modo, lascia vuoto vehicle_id
, imposta active_trips_only
su true
e imposta minimum_staleness
su un orario superiore alla maggior parte delle durate della corsa.
Ad esempio, potresti utilizzare un'ora. I risultati includono Viaggi che non sono
COMPLETATI né ANNULLATI e che non sono stati aggiornati da oltre un'ora. Il Fornitore deve esaminare questi Viaggi per garantire che il loro stato in Fleet Engine sia aggiornato correttamente.
Risoluzione dei problemi
In caso di errore DEADLINE_EXCEEDED
, lo stato di Fleet Engine è sconosciuto. Il provider deve richiamare 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 all'API Consumer per ulteriori informazioni sulla gestione degli errori di viaggio: Android o iOS.
Assistenza per le corse in carpooling
Puoi assegnare più corse di 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
vehicle_id
a una corsa condivisa (in una richiesta CreateTrip
o UpdateTrip
).
Consulta vehicle_waypoints
per RPC o vehicleWaypoints
per REST.
Supporto di più destinazioni
Identifica una destinazione intermedia
I campi intermediateDestinations
e intermediateDestinationIndex
in Viaggio (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 di 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 a waypoints
del veicolo o a remainingWaypoints
di Trip.
Il motivo è che le destinazioni intermedie prima di 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 è passata. La destinazione intermedia scelta come 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 ILLUSTRATIVA: 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 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 all'API Fleet Engine per pubblicare sull'argomento. Per farlo, 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à dovrebbe essere geo-fleet-engine@system.gserviceaccount.com
e il ruolo dovrebbe 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 di dati, protobuf
e json
. Il formato dei dati per ogni notifica è indicato negli attributi PubsubMessage con la chiave come data_format
e il valore 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"
}
}
}