L'API On-demand Rides and Deliveries di Fleet Engine consente di gestire le corse e lo stato del veicolo per le tue richieste di avanzamento viaggi e ordini. Gestisce le transazioni tra l'SDK driver, l'SDK consumer e di backend, che può comunicare con Fleet Engine grazie alla gRPC o le chiamate REST.
Prerequisiti
Per lo sviluppo, assicurati di installare lo strumento SDK (gcloud) e sono autenticati del progetto.
shell
gcloud auth login
Dovresti vedere 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 sulle chiamate API che riceve nei log della piattaforma Google Cloud. Consulta la documentazione di Cloud Logging per panoramica della lettura e dell'analisi dei log.
Il logging potrebbe non essere abilitato per impostazione predefinita per i progetti creati prima del giorno 10 feb 2022. Consulta le documentazione di logging per ulteriori informazioni.
Librerie client
Pubblichiamo le librerie client in diversi linguaggi di programmazione comuni. Questi per migliorare l'esperienza degli sviluppatori rispetto a REST o gRPC non elaborati. Per istruzioni su come ottenere 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 Avanzamento dei viaggi e degli ordini tramite la console Google Cloud. Queste API e questi SDK richiedono l'utilizzo di token web JSON che che sono stati firmati utilizzando account di servizio creati nella console Cloud.
Configurazione del progetto Cloud
Per configurare il progetto Cloud, devi prima creare il progetto e poi creare account di servizio.
Per creare il tuo progetto Google Cloud:
- Creare un progetto Google Cloud utilizzando la console Google Cloud.
- Utilizzando la dashboard dei servizi e delle API, abilita API Local Rides and Deliveries.
Gli account di servizio sono associati a uno o più ruoli. Vengono usate per creare i token web JSON che concedono set di autorizzazioni diversi a seconda del ruoli. In genere, per ridurre la possibilità di comportamenti illeciti, è possibile creare più di servizio, ciascuno con il set minimo di ruoli richiesto.
Lo stato di avanzamento dei viaggi e degli ordini utilizza i seguenti ruoli:
Ruolo | Descrizione |
---|---|
Utente SDK consumer di Fleet Engine
roles/fleetengine.consumerSdkUser |
Concede l'autorizzazione per cercare veicoli e recuperare informazioni su veicoli e viaggi. Token creati da un account di servizio con questo vengono in genere utilizzati dai dispositivi mobili dell'app per consumatori di ridesharing o di consegna a domicilio. |
Utente SDK driver Fleet Engine
roles/fleetengine.driverSdkUser |
Concede l'autorizzazione per aggiornare le posizioni e i percorsi dei veicoli e per recuperare informazioni su veicoli e viaggi. Token creati da un account di servizio con questo ruolo vengono in genere utilizzate dispositivi mobili con app di ridesharing o autisti per le consegne. |
Amministratore on demand di Fleet Engine
roles/fleetengine.ondemandAdmin |
Concede l'autorizzazione di lettura e scrittura per tutte le risorse per veicoli e viaggi. Le entità con questo ruolo non hanno bisogno di utilizzare JWT e dovrebbero utilizza le Credenziali predefinite dell'applicazione. Le rivendicazioni JWT personalizzate vengono ignorate. Questo ruolo deve essere limitato agli ambienti attendibili (backend del cliente). |
roles/fleetengine.serviceSuperUser |
Concede l'autorizzazione a tutti i veicoli e le API di viaggio. Token coniati
da un account di servizio con questo ruolo
sono in genere utilizzate dal backend
server web. Questo ruolo è obsoleto. Preferenza
roles/fleetengine.ondemandAdmin in alternativa. |
Ad esempio, crea un account di servizio per ognuno dei tre ruoli e assegna 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 un insieme arbitrario di autorizzazioni da raggruppare insieme. Gli SDK Driver e Consumer mostrano messaggi di errore ogni volta che autorizzazione richiesta mancante. Di conseguenza, consigliamo vivamente utilizzando l'insieme standard di ruoli presentato in precedenza e non utilizzando i ruoli personalizzati.
Per praticità, se devi creare token JWT per client non attendibili, aggiungendo 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
autenticarsi con gcloud (gcloud auth list
--format='value(account)'
).
Libreria di autenticazione di Fleet Engine
Fleet Engine utilizza token web JSON (JWT) per limitare l'accesso a API Fleet Engine. la nuova libreria di autenticazione Fleet Engine, disponibile su GitHub, semplifica la costruzione 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 si spaccia per un account di servizio).
- Collega i token firmati alle richieste in uscita effettuate da uno stub gRPC o nel client GAPIC.
Creazione di un token web JSON (JWT) per l'autorizzazione
Se non utilizzi la libreria di autenticazione Fleet Engine, i token web JSON (JWT) devono essere creati direttamente nel tuo codebase. Per questo è necessario disporre di un comprensione dei JWT e del loro rapporto con Fleet Engine. Ecco perché Consigliamo VIVAMENTE di sfruttare la libreria di autenticazione di Fleet Engine.
All'interno di Fleet Engine, i token JWT (JSON Web Token) forniscono l'autenticazione di breve durata e garantire che i dispositivi possano modificare solo veicoli, corse o attività per i quali sono autorizzati. I JWT contengono un'intestazione e una sezione di attestazione. La sezione dell'intestazione contiene informazioni come chiave privata da utilizzare (ottenuta dagli account di servizio) e la crittografia dell'algoritmo. La sezione delle rivendicazioni contiene informazioni quali l'ora di creazione del token, la durata dei token, i servizi che richiedono l'accesso e altre informazioni sull'autorizzazione per l'accesso; ad esempio l'ID veicolo.
Una sezione dell'intestazione JWT contiene i seguenti campi:
Campo | Descrizione |
---|---|
alg | L'algoritmo da utilizzare. "RS256". |
tipo | Il tipo di token. "JWT". |
bambino | L'ID della 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 delle attestazioni JWT contiene i seguenti campi:
Campo | Descrizione |
---|---|
iss | L'indirizzo email del tuo account di servizio. |
Pub/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 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. |
esp | Il timestamp di 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 è più di un'ora nel futuro. |
authorization | A seconda del caso d'uso, può contenere "vehicleid" o "tripid". |
La creazione di un token JWT si riferisce alla 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'altra attestazione nell'autorizzazione
con la chiave vehicleid
o tripid
impostata sul valore
ID veicolo o ID corsa per cui viene effettuata la chiamata.
L'SDK Driver utilizza sempre la rivendicazione vehicleid
, indipendentemente dal fatto che venga utilizzata
un percorso o un veicolo. Il backend di Fleet Engine assicura che il veicolo
alla corsa richiesta prima di apportare la modifica.
L'SDK consumer utilizza sempre la dichiarazione tripid
.
Il Fornitore di servizi di ridesharing o Fornitore di servizi di consegna deve utilizzare vehicleid
o tripid
con l'asterisco (*) a
che corrispondano a tutti i Veicoli e le Viaggi. Tieni presente che il JWT può contenere entrambi i token,
anche se non è richiesta, il che può semplificare l'implementazione della firma del token.
Casi d'uso di JWT
Di seguito è riportato un token di esempio per Provider server:
{
"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
nell'intestazione, specifica la chiave privata dell'account di servizio ID. Puoi trovare questo valore nel campoprivate_key_id
del tuo servizio di accesso al file JSON di destinazione. - Per i campi
iss
esub
, specifica l'indirizzo email del tuo account di servizio. Puoi trovare questo valore nel campoclient_email
del tuo account di servizio JSON. - Per il campo
aud
, specifica https://SERVICE_NAME/. - Per il campo
iat
, utilizza il timestamp di creazione del token, specificato come secondi trascorsi dalle ore 00:00:00 UTC del 1° gennaio 1970. Attendi 10 minuti per il disallineamento. Se il timestamp è troppo lontano nel passato, o in 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 il valore consentito èiat
+ 3600.
Quando firmi il JWT da trasmettere a un dispositivo mobile, assicurati di utilizzare l'account di servizio per il ruolo Driver o Consumer SDK. Altrimenti, lo smartphone dispositivo potrà 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 di super user. In caso contrario, 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, l'utente l'account 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 seguenti. iat
è l'ora corrente in secondi dopo l'epoca, che può essere
recuperata eseguendo date +%s
nel terminale. La proprietà exp
è
di scadenza in un numero di secondi dopo l'epoca, che può essere calcolata
aggiungendo 3600 a iat
. La scadenza non può essere superiore a un'ora nel
per il 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": "*" } }
Poi esegui questo comando gcloud per firmare il token per conto del tuo Account di servizio utente:
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'elenco dei veicoli
Endpoint REST:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
Veicoli e relativo ciclo di vita
Un veicolo è l'entità che rappresenta una coppia conducente-veicolo. Al momento, un conducente e un veicolo non possono essere monitorati separatamente. Fornitore di servizi di ridesharing o di consegna crea un Veicolo utilizzando un ID fornitore (che deve essere uguale al 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 di servizi di ridesharing o del fornitore di servizi di consegna.
Un veicolo che non è stato aggiornato tramite UpdateVehicle
dopo sette giorni verrà
automaticamente e le eventuali corse assegnate verranno contrassegnate come
non assegnato. L'approccio consigliato per mantenere disponibile un veicolo
in Fleet Engine è aggiornare la sua posizione a intervalli regolari. Aggiornamenti alla maggior parte
anche altri campi dell'entità Vehicle
ne estenderanno la durata, a condizione che
il valore del nuovo campo è diverso da quello esistente.
NOTA: alcuni campi sull'entità Vehicle
come device_settings
sono puramente di debug
che non sono rese persistenti da Fleet Engine. L'aggiornamento delle
prolungare la vita dell'entità Vehicle
.
È un errore chiamare CreateVehicle
con un
Coppia ID provider/ID veicolo già esistente. Il caso dei veicoli che
non vengono aggiornati di frequente. Possono essere gestiti in due modi:
CreateVehicle
con una coppia ID fornitore/ID veicolo prevista e verrà annullata
l'errore se il veicolo esiste già; o chiamando il numero CreateVehicle
dopo
UpdateVehicle
viene restituito con un errore NOT_FOUND
.
Aggiornamenti sulla posizione dei veicoli
Per ottenere le migliori prestazioni con Fleet Engine, fornisci un flusso di veicoli aggiornamenti posizione. Per fornire questi aggiornamenti, utilizza uno dei seguenti metodi:
- Usa l'SDK Driver - Android, iOS è l'opzione più semplice.
- Utilizza un codice personalizzato, utile se le località sono inoltrate tramite backend o se usi dispositivi diversi da Android o iOS.
Tipi di veicoli
L'entità Veicolo contiene un campo obbligatorio VehicleType
, che contiene un
Enum Category
che può essere specificato come AUTO
, TAXI
, TRUCK
,
TWO_WHEELER
, BICYCLE
o PEDESTRIAN
. Il tipo di veicolo può fungere da
criteri di filtro in SearchVehicles
e ListVehicles
.
Tutti i percorsi per i veicoli utilizzeranno il valore RouteTravelMode
corrispondente se
è impostata su AUTO
, TWO_WHEELER
, BICYCLE
o PEDESTRIAN
.
Se la categoria è impostata su TAXI
o TRUCK
, il routing viene considerato come se
la modalità AUTO
.
Attributi veicolo
L'entità Vehicle contiene un campo ripetuto di VehicleAttribute
. Questi
non vengono interpretati da Fleet Engine. SearchVehicles
L'API include un campo per richiedere che il valore 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
, ad esempio vehicle_type
e supported_trip_types
.
Tappe restanti del veicolo
L'entità Veicolo contiene un campo ripetuto di TripWaypoint
(RPC | REST),
chiamato waypoints
(RPC | REST).
Questo campo include le tappe rimanenti nelle corse, nell'ordine in cui
il veicolo li raggiunge. Fleet Engine calcola questo campo quando le corse vengono
assegnato al veicolo e lo aggiorna man mano che le corse cambiano il loro stato.
Queste tappe possono essere identificate dai campi TripId
e WaypointType
.
Espansione dell'idoneità di un veicolo per le corrispondenze
In genere, i servizi di ridesharing o fornitore di servizi di consegna sono responsabili della corrispondenza della corsa
richieste ai veicoli. Il servizio può utilizzare gli attributi del veicolo per includere una
veicolo in un maggior numero di ricerche. Ad esempio, il provider può implementare
un insieme di attributi corrispondenti ai livelli di vantaggi o capacità offerti
di un veicolo. Ad esempio, tre livelli possono essere un insieme di attributi con valori booleani
valori: is_bronze_level
, is_silver_level
e is_gold_level
. Un veicolo
tutti e tre. Quando Fleet Engine riceve la richiesta
percorso che richiede funzionalità di livello argento, la ricerca include quel veicolo.
Questo tipo di utilizzo degli attributi include i veicoli che offrono
le funzionalità di machine learning.
Esistono due modi per aggiornare gli attributi dei veicoli. Uno è UpdateVehicle
tramite Google Cloud CLI
o tramite l'API Compute Engine. Quando si utilizza questa API, l'intero set di attributi del veicolo viene
impostato sul valore. Non è possibile aggiornare soltanto un singolo attributo.
L'altro metodo è l'API UpdateVehicleAttributes
. Questo metodo prende solo
gli attributi da aggiornare. Gli attributi inclusi nella richiesta verranno
impostato sul nuovo valore o aggiunto; gli attributi non specificati non verranno modificati.
GUIDA: crea un veicolo
È necessario creare un'entità Vehicle
per ogni veicolo da monitorare nella flotta.
Utilizza l'endpoint CreateVehicle
con CreateVehicleRequest
per creare un
Veicolo.
Il provider_id
di Vehicle
deve essere l'ID progetto
(ad es. my-on-demand-project) del progetto Google Cloud che contiene
Account di servizio che verranno utilizzati per chiamare Fleet Engine. Tieni presente che mentre
più account di servizio possono accedere a Fleet Engine per la stessa Ridesharing
o Delivery Provider, Fleet Engine attualmente non supporta gli account di servizio
più progetti Google Cloud che accedono allo stesso Vehicles
.
Vehicle
può essere creato nello stato OFFLINE
o ONLINE
. Se
ONLINE
creato può essere immediatamente restituito in risposta a SearchVehicles
query.
Un last_location
iniziale può essere incluso nella chiamata CreateVehicle
.
Sebbene sia consentito, non è possibile creare un Vehicle
nello stato ONLINE
senza
un last_location
.
Consulta la pagina Tipi di veicolo per informazioni dettagliate sul veicolo .
Per informazioni dettagliate, consulta Attributi del veicolo nel campo degli attributi.
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
Consulta providers.vehicles.create riferimento.
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 la chiamata all'endpoint CreateVehicle
. La voce di log include
informazioni sui valori della richiesta CreateVehicle
. Se la chiamata
va a buon fine, verranno incluse anche informazioni sul Vehicle
che era
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 è stato creato un veicolo. Per ricevere queste notifiche, segui le istruzioni qui.
GUIDA: 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 qualsiasi veicolo attivo, Fleet Engine si aspetta un aggiornamento della posizione almeno una volta al minuto e al massimo una volta ogni 5 secondi. Questi aggiornamenti richiedono solo l'utente SDK driver Fleet Engine privilegiati.
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
Consulta providers.vehicles.update riferimento.
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.
Istruzioni: aggiorna altri campi Veicolo
Gli aggiornamenti di altri attributi dello stato del veicolo avvengono con meno frequenza rispetto a
aggiornamenti di posizione. Gli aggiornamenti di attributi diversi da last_location
richiedono
Privilegi di super user di Fleet Engine.
UpdateVehicleRequest
include un update_mask
per indicare quali campi
aggiornamento. Il comportamento del campo è quello indicato nella documentazione di Protobuf per
maschere di campo.
Come indicato in Attributi dei veicoli, l'aggiornamento delle
attributes
richiede la scrittura di tutti gli attributi per essere conservati. it
non è possibile semplicemente aggiornare il valore di una coppia chiave-valore in un
Chiamata UpdateVehicle
. Per aggiornare i valori di attributi specifici,
È possibile utilizzare l'API UpdateVehicleAttributes
.
Esempio
Questo esempio abilita 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
Consulta providers.vehicles.update riferimento.
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 di Google Cloud Platform per gli aggiornamenti dei veicoli
L'API Fleet Engine scrive una voce di log tramite i log della piattaforma Google Cloud quando
viene ricevuta la chiamata all'endpoint UpdateVehicle
. La voce di log include
informazioni sui valori della richiesta UpdateVehicle
. Se la chiamata
va a buon fine, verranno incluse anche informazioni sul Vehicle
che era
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 è aggiornato. Per ricevere queste notifiche, segui le istruzioni qui.
ISTRUZIONI: Cerca veicoli
Fleet Engine supporta la ricerca di veicoli. SearchVehicles
L'API ti consente di trovare i conducenti disponibili nelle vicinanze più adatti a un'attività come
per una corsa o per una richiesta di consegna. L'API SearchVehicles
restituisce un
elenco classificato di conducenti che corrispondono agli attributi delle attività con gli attributi dei veicoli in
della tua flotta. Per ulteriori informazioni, vedi
Ricerca di conducenti nelle vicinanze.
Esempio
Durante la ricerca di veicoli disponibili, Fleet Engine esclude i veicoli su delle corse attive per impostazione predefinita. I servizi di Ridesharing o Fornitore di servizi di consegna devono includerle esplicitamente nelle richieste di ricerca. L'esempio seguente mostra come includi questi veicoli nella ricerca di veicoli corrispondenti a una corsa dalla dall'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 è idoneo. Nel mondo reale, questo viene fatto dall'SDK del 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
Consulta providers.vehicles.search riferimento.
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 i filtri in base agli attributi del veicolo
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 del veicolo.
non può essere utilizzato per altri campi. La query di filtro funziona come una clausola AND
con altri vincoli, come minimum_capacity
o vehicle_types
in
SearchVehiclesRequest
.
GUIDA: Elencare i veicoli
SearchVehicles
è ottimizzato per trovare un numero limitato di veicoli in classifica
ordinare molto rapidamente e viene utilizzato principalmente per trovare conducenti nelle vicinanze
a un'attività. Tuttavia, a volte potresti voler trovare tutti i veicoli che soddisfano
anche se è necessario scorrere i risultati. ListVehicles
è
progettata per quel caso d'uso.
L'API ListVehicles
ti consente di trovare tutti i veicoli che soddisfano alcuni requisiti
le opzioni di richiesta. L'API ListVehicles
restituisce un elenco impaginato di veicoli in
il progetto che soddisfa alcuni requisiti.
Per filtrare in base agli attributi dei veicoli, consulta Query di filtro dei veicoli.
Esempio
In questo esempio viene eseguito un filtro in base a vehicle_type
e agli attributi utilizzando la proprietà
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
Consulta providers.vehicles.list riferimento.
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 e al ciclo di vita del veicolo.
Il Provider di Ridesharing è responsabile della creazione di viaggi utilizzando Fleet Engine
interfacce. Fleet Engine fornisce un servizio RPC,
TripService
e le risorse REST, provider.trips
di Google. Queste interfacce consentono la creazione di entità Trip, le richieste di informazioni, la ricerca
funzionalità e capacità di aggiornamento.
Un Trip
dispone di un campo di stato per monitorare il suo avanzamento durante il ciclo di vita.
I valori vengono spostati da NEW
a COMPLETE
più CANCELED
e UNKNOWN_TRIP_STATUS
di Google. Fai riferimento a 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 a CANCELED
da uno qualsiasi di questi stati.
Quando il servizio crea una corsa, il motore imposta lo stato su NEW
. R
Il campo vehicle_id
è facoltativo. Come per i veicoli, i servizi eliminano automaticamente le corse non assegnate
dopo sette giorni senza aggiornamenti. Se il tuo servizio tenta di creare una corsa con un
ID già esistente. È stato 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 valore vehicle_id
assegnato a una corsa solo quando quest'ultima
è attivo. Ad esempio, esegui questa operazione quando un autista annulla una corsa mentre
e la corsa viene riassegnata a un altro veicolo.
Lo stato è importante durante l'implementazione in sequenza assistenza per i viaggi. Questo supporto consente al Fornitore di assegnare una nuova corsa a un Veicolo. mentre il Veicolo è in viaggio. Il codice per la creazione di un viaggio in sequenza è uguale a un viaggio singolo e utilizza lo stesso l'ID veicolo. Fleet Engine aggiunge l'origine e la destinazione del nuovo viaggio al le tappe del veicolo. Per ulteriori informazioni sui viaggi consecutivi, vedi Creare viaggi con più tappe.
Tappe rimanenti del viaggio
L'entità Trip contiene un campo ripetuto di TripWaypoint
(RPC | REST),
chiamato remainingWaypoints
(RPC | REST).
Questo campo include tutte le tappe necessarie per viaggiare in ordine con il veicolo
prima del punto di partenza finale della corsa. Calcola da
Tappe restanti del veicolo.
Nei casi d'uso Back-to-back e Carpool, questo elenco contiene tappe da
altre corse che verranno attraversate prima di questa corsa, ma esclude eventuali tappe
dopo questo viaggio. Il waypoint nell'elenco può essere identificato dal relativo TripId
e WaypointType
.
La relazione tra lo stato della corsa e le tappe rimanenti del veicolo
Le tappe rimanenti del veicolo (RPC | REST) verranno
verrà aggiornato quando Fleet Engine riceve una richiesta di modifica dello stato della corsa. La
la tappa precedente verrà rimossa dall'elenco delle tappe rimanenti del veicolo quando
tripStatus
(RPC | REST)
è cambiato da altro stato a ENROUTE_TO_XXX. Ovvero, quando
lo stato della corsa è cambiato da ENROUTE_TO_PICKUP a ARRIVED_AT_PICKUP, il valore
il punto di prelievo sarà ancora presente nell'elenco delle tappe rimanenti del veicolo, ma quando la corsa
lo stato viene modificato in ENROUTE_TO_INTERMEDIATE_DESTINATION o ENROUTE_TO_DROPOFF,
il punto di prelievo verrà poi rimosso dalle tappe rimanenti del veicolo.
Lo stesso vale per ARRIVED_AT_INTERMEDIATE_DESTINATION e ENROUTE_TO_INTERMDEDIATE_DESTINATION. Quando ARRIVED_AT_INTERMEDIATE_DESTINATION, la destinazione intermedia corrente non verrà rimossa dai campi rimanenti l'elenco di tappe fino a quando il veicolo non segnala che sta per dirigersi alla tappa successiva.
Quando lo stato della corsa verrà modificato in COMPLETED
, non ci saranno tappe di questa corsa.
nell'elenco delle tappe rimanenti del veicolo.
GUIDA: Crea un viaggio
Affinché ogni richiesta di corsa possa essere monitorata, è necessario creare un'entità Trip
abbinate ai Veicoli nel parco risorse. Utilizza l'endpoint CreateTrip
con CreateTripRequest
per creare un viaggio.
Per creare un viaggio sono necessari i seguenti attributi:
parent
: una stringa che include l'ID provider creato al momento della generazione Il progetto Cloud è stato creato.trip_id
: una stringa creata da Ridesharing Provider.trip
- Container con metadati di base che descrivono la corsa.trip_type
: enum che indica se la corsa potrebbe avere altri viaggiatori da un'origine e una destinazione diverse nello stesso veicolo (SHARED
) oppure un solo soggetto (EXCLUSIVE
).pickup_point
: TerminalLocation che rappresenta il punto di origine dell' percorso. Fai riferimento a Riferimento RPC o riferimento REST
Quando crei un viaggio, puoi fornire number_of_passengers
, dropoff_point
e vehicle_id
. Questi campi non sono obbligatori, ma se li fornisci,
vengono conservati. Tutti gli altri campi Trip vengono ignorati. Ad esempio, tutti i viaggi
inizia con un trip_status
di NEW
anche se superi un trip_status
di
CANCELED
nella richiesta di creazione.
Esempio
L'esempio seguente crea un viaggio al Grand Indonesia East Mall. Il viaggio
è per due passeggeri ed è esclusivo. Il provider_id
di Trip
deve essere
uguale all'ID progetto. Nell'esempio, il Fornitore di ridesharing ha creato
Progetto Google Cloud, project-id. Questo progetto deve avere
Account di servizio utilizzati per chiamare Fleet Engine. Lo stato del percorso è NEW
.
Successivamente, dopo che il servizio abbina la corsa a un veicolo, il servizio può chiamare
UpdateTrip
e modifica 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
Consulta providers.trips.create riferimento.
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 Trip Creation
L'API Fleet Engine scrive una voce di log utilizzando i log della piattaforma Google Cloud quando
viene ricevuta la chiamata all'endpoint CreateTrip
. La voce di log include
informazioni sui valori della richiesta CreateTrip
. Se la chiamata
avrà esito positivo, saranno incluse anche informazioni sul Trip
restituito.
GUIDA: Aggiornare un percorso
L'entità Trip contiene campi che consentono il monitoraggio da parte del servizio e per
segnalando l'avanzamento della corsa da parte dell'SDK Driver e al
SDK consumer. Per aggiornare le proprietà, usa UpdateTripRequest
per creare un nuovo messaggio email. I campi Viaggio vengono aggiornati in base all'elemento field_mask
della richiesta.
Fai riferimento a 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 percorso.
- Modifiche a punto di partenza, arrivo o tappa.
Fleet Engine aggiorna automaticamente i campi seguenti quando si utilizza il metodo Funzionalità di condivisione del percorso tramite l'SDK Driver o l'SDK consumer:
- Route
- ETA
- Distanza rimanente
- Posizione del veicolo
- Tappe rimanenti
Fai riferimento a Trip
in RPC o
Resource.Trip
in REST.
Log di Google Cloud Platform per gli aggiornamenti sulle corse
L'API Fleet Engine scrive una voce di log utilizzando i log della piattaforma Google Cloud quando
viene ricevuta la chiamata all'endpoint UpdateTrip
. La voce di log include
informazioni sui valori della richiesta UpdateTrip
. Se la chiamata ha esito positivo,
saranno incluse anche le informazioni sul Trip
che è stato restituito.
GUIDA: Cerca percorsi
Fleet Engine supporta la ricerca delle corse. Come indicato in precedenza, un viaggio
eliminati automaticamente dopo sette giorni, quindi SearchTrips
non
mostrare una cronologia completa di tutti i viaggi.
Sebbene SearchTrips
sia un'API flessibile, l'elenco seguente prende 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
,vehicle_id
è impostato sul veicolo in esame eactive_trips_only
deve essere impostato sutrue
.Riconciliazione dello stato del provider e di Fleet Engine: il provider può utilizzare
SearchTrips
per garantire che lo stato del viaggio e quello di Fleet Engine corrispondano. Ciò è particolarmente importante per TripStatus. Se lo stato di un viaggio assegnato a un Veicolo non è impostato correttamente suCOMPLETE
oCANCELED
, il Veicolo non è incluso daSearchVehicles
.
Per utilizzare SearchTrips
in questo modo, lascia vuoto il campo vehicle_id
, imposta active_trips_only
su true
e imposta minimum_staleness
su un tempo superiore a quello della maggior parte delle durate dei viaggi.
Ad esempio, puoi utilizzare un'ora. I risultati includono Viaggi che non sono
COMPLETATO o ANNULLATO e non aggiornato da oltre un'ora. Il fornitore
esaminare questi Trip per verificare che il loro stato in Fleet Engine sia
correttamente.
Risoluzione dei problemi
In caso di errore DEADLINE_EXCEEDED
, lo stato di Fleet Engine
sconosciuto. Il provider deve chiamare di nuovo CreateTrip
, il che restituisce un
201 (CREAZIONE) o 409 (CONFLITTO). Nel secondo caso, la richiesta precedente è andata a buon fine
prima del giorno DEADLINE_EXCEEDED
. Per ulteriori informazioni, consulta le guide delle API consumer
sulla gestione degli errori di viaggio: Android
o iOS.
Assistenza per le corse di Carpool
Puoi assegnare più corse SHARED
a un veicolo che supporta TripType.SHARED
.
Devi specificare l'ordine di tutte le tappe non superate per tutte le corse assegnate a
il Veicolo in questa corsa condivisa tramite Trip.vehicle_waypoints
quando assegni il
vehicle_id
per un viaggio condiviso (in una richiesta CreateTrip
o UpdateTrip
).
Fai riferimento a vehicle_waypoints
per RPC
o vehicleWaypoints
per REST.
Supporto per più destinazioni
Individuare 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
. Durante l'aggiornamento
destinazioni intermedie, devi fornire un elenco completo di destinazioni intermedie,
incluse quelle che sono state visitate, non solo quelle
aggiunto o da modificare.
Quando intermediateDestinationIndex
punta a un indice dopo la posizione di
destinazione intermedia appena aggiunta/modificata,
destinazione non verrà aggiunta ai valori waypoints
o remainingWaypoints
del viaggio del veicolo.
Il motivo è che eventuali destinazioni intermedie prima del giorno intermediateDestinationIndex
vengono considerati come già visitati.
Modifiche allo stato del viaggio
Il campo intermediateDestinationsVersion
in (RPC | REST)
nella richiesta di aggiornamento dello stato del viaggio inviata a Fleet Engine per indicare
è trascorsa una destinazione intermedia. La destinazione intermedia target
viene specificato tramite il campo intermediateDestinationIndex
.
Quando tripStatus
(RPC | REST) è ENROUTE_TO_INTERMEDIATE_DESTINATION, un numero compreso tra
[0..N-1] indica la destinazione intermedia che verrà attraversata successivamente dal veicolo.
Quando tripStatus
è ARRIVED_AT_INTERMEDIATE_DESTINATION, un numero compreso tra
[0..N-1] indica la destinazione intermedia in cui si trova il veicolo.
Esempio
Il seguente esempio di codice mostra come aggiornare lo stato di una corsa in modo che corrisponda alla prima destinazione intermedia, supponendo che tu abbia creato un viaggio con più destinazioni e ha superato il punto di prelievo.
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;
}
Istruzioni: iscriviti ai messaggi di notifica dell'API Fleet Engine
L'API Fleet Engine utilizza Google Cloud Pub/Sub per pubblicare notifiche sull'argomento creato dal consumer Google Cloud progetto. Pub/Sub non è abilitato per impostazione predefinita per Fleet Engine su Google Cloud progetto. Invia una richiesta di assistenza o contatta il tuo Customer Engineer per abilitare 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 Fleet Engine su quelle di livello inferiore.
Una volta creato l'argomento, dovrai concedere l'API Fleet Engine
per pubblicare l'argomento. A questo scopo, fai clic sull'argomento
appena creato e aggiungere una nuova autorizzazione. Potrebbe essere necessario 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 dovrebbe essere Pub/Sub publisher
.
Per configurare il tuo progetto Cloud in modo da iscriverti alle notifiche, segui queste istruzioni
L'API Fleet Engine pubblica ogni notifica in due dati diversi
formati, protobuf
e
json
. Il formato dei dati per ciascuna notifica è indicato in
Attributi PubsubMessage
con chiave come data_format
e valore come protobuf
o json
.
Schema delle notifiche:
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"
}
}
}