L'API On-demand Rides and Deliveries de Fleet Engine vous permet de gérer les trajets et l'état du véhicule pour vos applications de trajet et de progression de commande. Il gère les transactions entre le SDK Driver, le SDK Consumer et vos de backend, qui peut communiquer avec Fleet Engine en effectuant gRPC ou REST.
Prérequis
Pour le développement, veillez à installer la suite Cloud du SDK (gcloud) et sont authentifiés votre projet.
shell
gcloud auth login
Un message indiquant que l'opération a réussi doit s'afficher:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Vérifiez que les API On-demand Rides and Deliveries Solution Fleet Engine sont correctement configurées.
shell
gcloud --project=project-id services enable fleetengine.googleapis.com
Si cette commande génère une erreur, contactez votre administrateur de projet et votre représentant de l'assistance Google pour y accéder.
Journalisation
Fleet Engine peut écrire des messages de journal sur les appels d'API qu'il reçoit. dans les journaux Google Cloud Platform. Consultez la documentation Cloud Logging pour découvrir de la lecture et de l'analyse des journaux.
Il est possible que la journalisation ne soit pas activée par défaut pour les projets créés avant 10 févr. 2022. Consultez le documentation sur la journalisation pour en savoir plus.
Bibliothèques clientes
Nous publions des bibliothèques clientes dans plusieurs langages de programmation courants. Ces amélioreront l'expérience développeur par rapport aux fichiers REST ou gRPC bruts. Pour obtenir des instructions sur la façon d'obtenir des bibliothèques clientes pour votre application de serveur, voir Bibliothèques clientes.
Les exemples Java de cette documentation partent du principe que vous connaissez le protocole gRPC.
Authentification et autorisation
Vous pouvez configurer les fonctionnalités fournies par le trajet et la progression de la commande via la console Google Cloud. Ces API et SDK nécessitent l'utilisation de jetons Web JSON qui ont été signés à l'aide de comptes de service créés la console Cloud.
Configuration du projet Cloud
Pour configurer votre projet Cloud, commencez par créer votre projet, puis créer des comptes de service.
Pour créer votre projet Google Cloud:
- Créez un projet Google Cloud à l'aide de la console Google Cloud.
- À l'aide du tableau de bord des API et services, API Local Rides and Deliveries
Les comptes de service sont associés à un ou plusieurs rôles. Elles servent à créer qui accordent différents ensembles d'autorisations en fonction de rôles. En règle générale, pour réduire les risques d'abus, vous pouvez créer plusieurs des comptes de service, chacun disposant de l'ensemble minimal de rôles requis.
Le trajet et la progression de la commande utilisent les rôles suivants:
Rôle | Description |
---|---|
Utilisateur du SDK client Fleet Engine
roles/fleetengine.consumerSdkUser |
Accorde l'autorisation de rechercher des véhicules et de récupérer des informations sur les véhicules et les trajets. Les jetons créés par un compte de service sont généralement utilisés sur les appareils mobiles de votre application grand public de partage de course ou de livraison. |
Utilisateur du SDK pilote Fleet Engine
roles/fleetengine.driverSdkUser |
Accorde l'autorisation de mettre à jour l'emplacement et les itinéraires des véhicules, et pour récupérer des informations sur les véhicules et les trajets. Jetons créés par un compte de service doté de ce rôle sont généralement utilisées les applications mobiles de partage de course ou de chauffeur-livreur. |
Administrateur Fleet Engine On-demand
roles/fleetengine.ondemandAdmin |
Accorde une autorisation de lecture et d'écriture pour toutes les ressources liées aux véhicules et aux trajets. Les comptes principaux dotés de ce rôle n'ont pas besoin d'utiliser de jetons JWT et doivent plutôt utiliser les identifiants par défaut de l'application. Les revendications JWT personnalisées sont ignorées. Ce rôle doit être limité aux environnements approuvés (backend du client). |
roles/fleetengine.serviceSuperUser |
Accorde l'autorisation à toutes les API liées aux véhicules et aux trajets. Jetons frappés
par un compte de service doté de ce rôle sont généralement utilisées depuis votre backend
serveurs. Ce rôle est obsolète. Préférer
roles/fleetengine.ondemandAdmin à la place. |
Par exemple, créez un compte de service pour chacun des trois rôles et attribuez-lui leurs rôles respectifs.
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
Les SDK Driver et Consumer SDK s'appuient sur ces rôles standards.
Il est également possible de créer des rôles personnalisés un ensemble arbitraire d'autorisations à regrouper. Le pilote et le SDK grand public affichent des messages d'erreur chaque fois qu'un autorisation requise manquante. Par conséquent, nous vous recommandons vivement en utilisant l'ensemble standard de rôles présenté ci-dessus et sans utiliser de rôles personnalisés.
Pour plus de commodité, si vous devez créer des jetons JWT pour des clients non approuvés, ajoutez le rôle Créateur de jetons du compte de service permet aux utilisateurs de créer des jetons à l'aide des outils de ligne de commande gcloud.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Où my-user@example.com
est l'adresse e-mail utilisée pour
vous authentifier avec gcloud (gcloud auth list
--format='value(account)'
).
Bibliothèque d'authentification Fleet Engine
Fleet Engine utilise des jetons Web JSON (JWT) pour limiter l'accès à API Fleet Engine. La nouvelle bibliothèque d'authentification Fleet Engine disponibles sur GitHub, simplifie la construction de jetons JWT Fleet Engine et les signe de façon sécurisée.
Cette bibliothèque offre les avantages suivants:
- Simplifie le processus de création des jetons Fleet Engine.
- Fournit des mécanismes de signature de jetons autres que l'utilisation de fichiers d'identifiants (tels que empruntant l'identité d'un compte de service)
- associe des jetons signés à des requêtes sortantes effectuées à partir d'un bouchon gRPC ou client GAPIC.
Créer un jeton Web JSON (JWT) pour l'autorisation
Lorsque vous n'utilisez pas la bibliothèque d'authentification Fleet Engine, les jetons Web JSON (JWT) doivent être directement dans votre codebase. Pour cela, vous devez avoir à la fois sur les jetons JWT et sur leur lien avec Fleet Engine. C'est pourquoi nous Nous vous recommandons vivement d'utiliser la bibliothèque Auth Fleet Engine.
Dans Fleet Engine, les jetons Web JSON (JWT) permettent une authentification de courte durée et s'assurer que les appareils ne peuvent modifier que les véhicules, les trajets ou les tâches pour qu'ils sont autorisés. Les jetons JWT contiennent un en-tête et une section de revendication. La section d'en-tête contient des informations telles que le (obtenue auprès des comptes de service) et le chiffrement algorithme. La section "Revendication" contient des informations telles que le la date de création, la durée de vie des jetons, les services Revendiquer l'accès et d'autres informations d'autorisation pour réduire le champ d'application l'accès aux données ; par exemple, l'ID du véhicule.
Une section d'en-tête JWT contient les champs suivants:
Champ | Description |
---|---|
alg | Algorithme à utiliser. "RS256". |
type | Type de jeton. "JWT". |
enfant | ID de la clé privée de votre compte de service. Cette valeur dans le champ "private_key_id" du fichier JSON de votre compte de service. Veillez à utiliser une clé d'un compte de service disposant du niveau d'autorisation approprié. |
Une section de revendications JWT contient les champs suivants:
Champ | Description |
---|---|
iss | Adresse e-mail de votre compte de service. |
Pub/Sub. | Adresse e-mail de votre compte de service. |
aud | SERVICE_NAME de votre compte de service, dans ce cas https://fleetengine.googleapis.com/ |
iat | Code temporel de la création du jeton, spécifié en secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC. Le décalage peut prendre 10 minutes. Si le le code temporel est trop éloigné dans le passé ou dans le futur, le serveur risque de signaler une erreur. |
exp | Code temporel de l'expiration du jeton, spécifié en secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC. La requête échoue si le code temporel est plus d’une heure dans le futur. |
autorisation | Peut contenir "vehicleid" ou "tripid", selon le cas d'utilisation. |
La création d'un jeton JWT fait référence à sa signature. Instructions et exemples de code pour créer et signer le jeton JWT, consultez Autorisation via un compte de service sans OAuth. Vous pouvez ensuite associer un jeton signé aux appels gRPC ou aux autres méthodes utilisées pour accéder à Fleet Engine.
Revendications JWT
Lors de la création de la charge utile JWT, ajoutez une revendication supplémentaire dans l'autorisation
avec la clé vehicleid
ou tripid
définie sur la valeur du
identifiant du véhicule ou du trajet pour lequel l'appel est effectué.
Le SDK Driver utilise toujours la revendication vehicleid
, que ce soit sur
un trajet ou un véhicule. Le backend de Fleet Engine
s'assure que le véhicule
est associé au trajet demandé avant d'effectuer la modification.
Le SDK grand public utilise toujours la revendication tripid
.
Le fournisseur de services de VTC ou de livraison doit utiliser l'attribut vehicleid
ou tripid
avec un "*" à
correspondant à tous les véhicules et trajets. Notez que le JWT peut contenir les deux jetons,
même si ce n'est pas obligatoire, ce qui peut simplifier l'implémentation de la signature des jetons.
Cas d'utilisation de JWT
Voici un exemple de jeton pour Serveur fournisseur:
{
"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": "*"
}
}
Voici un exemple de jeton pour l'application consommateur:
{
"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"
}
}
Voici un exemple de jeton pour l'application 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"
}
}
- Dans le champ
kid
de l'en-tête, spécifiez la clé privée de votre compte de service. ID. Vous trouverez cette valeur dans le champprivate_key_id
de votre service fichier JSON du compte de service. - Dans les champs
iss
etsub
, indiquez l'adresse e-mail de votre compte de service. Vous trouverez cette valeur dans le champclient_email
de votre compte de service JSON. - Pour le champ
aud
, indiquez https://SERVICE_NAME/. - Pour le champ
iat
, utilisez le code temporel correspondant à la création du jeton. spécifiée en secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC. Le décalage peut prendre 10 minutes. Si le code temporel est trop ancien, ou si, à l'avenir, le serveur pourrait signaler une erreur. - Pour le champ
exp
, utilisez l'horodatage de l'expiration du jeton. spécifiée en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. La valeur la valeur autorisée estiat
+ 3 600.
Lorsque vous signez le jeton JWT à transmettre à un appareil mobile, veillez à utiliser le compte de service pour le rôle Pilote ou SDK client. Dans le cas contraire, l'appareil pourra modifier l'état qu'il ne devrait pas avoir.
De même, lorsque vous signez le jeton JWT destiné aux appels privilégiés, assurez-vous pour utiliser le compte de service avec le rôle de super-utilisateur. Dans le cas contraire, l'opération échouera.
Générer un jeton JWT à des fins de test
La génération de jetons à partir du terminal peut être utile lors des tests.
Pour effectuer ces étapes, votre utilisateur doit disposer du rôle Créateur de jetons du compte de service:
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Créez un fichier nommé unsigned_token.json
avec le contenu ci-dessous. iat
est l'heure actuelle, exprimée en nombre de secondes après l'epoch, qui peut être
récupérée en exécutant date +%s
dans votre terminal. La propriété exp
est
délai d'expiration en nombre de secondes après l'epoch, qui peut être calculé comme suit :
en ajoutant 3 600 à iat
. Le délai d'expiration ne peut pas dépasser une heure dans le
à venir.
{ "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": "*" } }
Exécutez ensuite la commande gcloud suivante pour signer le jeton Compte de service utilisateur:
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 jeton JWT signé encodé en base64 doit maintenant être stocké dans le fichier.
signed_token.jwt
Le jeton est valide pour la prochaine heure.
Vous pouvez maintenant tester le jeton en exécutant une commande curl
sur la liste de véhicules
Point de terminaison REST:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
Les véhicules et leur cycle de vie
Le véhicule est l'entité représentant une paire conducteur-véhicule. Actuellement, le Conducteur et le Véhicule ne peuvent pas être suivis séparément. Le fournisseur de partage de course ou de livraison crée un véhicule à l'aide d'un ID de fournisseur (qui doit être identique à celui ID du projet Google Cloud contenant le compte de service utilisé pour appeler les API Fleet Engine) et un ID de véhicule appartenant au fournisseur de services de livraison ou de covoiturage.
Un Véhicule qui n'a pas été mis à jour via UpdateVehicle
après sept jours
automatiquement supprimés, et les trajets qui lui sont attribués, le cas échéant, seront marqués comme
non attribuées. Approche recommandée pour garder un véhicule disponible
dans Fleet Engine, il faut mettre à jour
son emplacement à intervalles réguliers. Mises à jour dans la plupart des
D'autres champs de l'entité Vehicle
prolongent également sa durée de vie, à condition que
la nouvelle valeur du champ est
différente de la valeur existante.
REMARQUE: Certains champs de l'entité Vehicle
, comme device_settings
, ne sont utilisés qu'à des fins de débogage
des informations qui ne sont pas conservées par Fleet Engine. Leur mise à jour n'entraîne
prolonger la durée de vie de l'entité Vehicle
.
Vous ne devez pas appeler CreateVehicle
avec une
La paire ID de fournisseur/ID de véhicule existe déjà. Le cas des véhicules
qui ne sont pas mis à jour fréquemment peuvent être traités de deux manières: les appels fréquents
CreateVehicle
avec la paire ID de fournisseur/ID de véhicule attendue et suppression
l'erreur si le véhicule existe déjà ; ou appeler CreateVehicle
après une
UpdateVehicle
renvoie une erreur NOT_FOUND
.
Mises à jour de la position des véhicules
Pour optimiser les performances de Fleet Engine, fournissez un flux de véhicules mises à jour de la position géographique. Pour fournir ces mises à jour, utilisez l'une des méthodes suivantes:
- Utiliser le SDK Driver – Android iOS est l'option la plus simple.
- Utilisez un code personnalisé (utile si les lieux sont transmis via votre backend, ou si vous utilisez des appareils autres qu'Android ou iOS
Type de véhicule
L'entité "Véhicule" comporte un champ obligatoire VehicleType
, qui inclut un
Énumération Category
pouvant être spécifiée comme AUTO
, TAXI
, TRUCK
,
TWO_WHEELER
, BICYCLE
ou PEDESTRIAN
. Le type de véhicule peut servir
critères de filtre dans SearchVehicles
et ListVehicles
.
Tous les itinéraires pour les véhicules utiliseront le RouteTravelMode
correspondant si le
La catégorie est définie sur AUTO
, TWO_WHEELER
, BICYCLE
ou PEDESTRIAN
.
Si la catégorie est définie sur TAXI
ou TRUCK
, le routage est traité de la même manière que
le mode AUTO
.
Attributs du véhicule
L'entité Véhicule contient un champ répété VehicleAttribute
. Ces
ne sont pas interprétés par Fleet Engine. SearchVehicles
L'API inclut un champ exigeant que la valeur Vehicles
correspondante contienne tous les éléments
les attributs inclus définis sur la valeur spécifiée.
Notez que le champ d'attribut s'ajoute à plusieurs autres champs acceptés.
dans le message Vehicle
, par exemple vehicle_type
et supported_trip_types
.
Points de cheminement restants du véhicule
L'entité "Véhicule" contient un champ répété de type TripWaypoint
(RPC | REST).
appelé waypoints
(RPC | REST).
Ce champ inclut les points de cheminement restants dans les trajets, dans l'ordre
le véhicule les atteint. Fleet Engine calcule ce champ au fur et à mesure que les trajets
attribué au véhicule et le met à jour à mesure que son état change.
Ces points de cheminement peuvent être identifiés à l'aide des champs TripId
et WaypointType
.
Élargissement de l'éligibilité d'un véhicule aux correspondances
En règle générale, la mise en correspondance des trajets est effectuée par les services de VTC ou du Prestataire de livraison
aux véhicules. Le service peut utiliser les attributs du véhicule pour inclure
à un véhicule lors d'un plus grand nombre de recherches. Par exemple, le fournisseur peut implémenter
un ensemble d'attributs correspondant aux niveaux d'avantages ou de capacités fournis par
un véhicule. Par exemple, trois niveaux peuvent être un ensemble d'attributs avec des valeurs booléennes
les valeurs suivantes: is_bronze_level
, is_silver_level
et is_gold_level
. Un véhicule
sont éligibles à ces trois catégories. Lorsque Fleet Engine reçoit une demande
nécessitant des fonctionnalités de niveau Argent, la recherche inclut ce véhicule.
De cette façon, les attributs sont utilisés pour les véhicules qui offrent une variété
des fonctionnalités.
Il existe deux façons de mettre à jour les attributs d'un véhicule. Le premier est UpdateVehicle
API. Lorsque vous utilisez cette API, l'ensemble des attributs de véhicule
défini sur la valeur. Il n'est pas possible de mettre à jour un seul attribut.
L'autre méthode est l'API UpdateVehicleAttributes
. Cette méthode ne prend que
les attributs à mettre à jour. Les attributs inclus dans la demande seront
définie sur la nouvelle valeur ou ajoutée ; les attributs non spécifiés ne seront pas modifiés.
PROCÉDURE: Créer un véhicule
Une entité Vehicle
doit être créée pour chaque véhicule à suivre dans le parc.
Utilisez le point de terminaison CreateVehicle
avec CreateVehicleRequest
pour créer un
Véhicule.
L'élément provider_id
de Vehicle
doit correspondre à l'ID du projet.
(par exemple, my-on-demand-project) du projet Google Cloud contenant le
Comptes de service qui seront utilisés pour appeler Fleet Engine. Notez que même si
plusieurs comptes de service peuvent accéder à Fleet Engine pour le même VTC
ou le fournisseur de services de livraison, Fleet Engine n'accepte pas les comptes de service
plusieurs projets Google Cloud accèdent au même Vehicles
.
Le Vehicle
peut être créé à l'état OFFLINE
ou ONLINE
. Si
ONLINE
créé, il peut être immédiatement renvoyé en réponse à SearchVehicles
requêtes.
Un last_location
initial peut être inclus dans l'appel CreateVehicle
.
Bien que cela soit autorisé, vous ne devez pas créer de Vehicle
à l'état ONLINE
sans
un last_location
.
Pour en savoir plus sur votre véhicule, consultez la page Types de véhicules. .
Pour en savoir plus, consultez les attributs du véhicule. dans le champ "Attributs".
La valeur renvoyée par CreateVehicle
est l'entité Vehicle
créée.
Exemple
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
Voir providers.vehicles.create référence.
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.
Journaux Google Cloud Platform pour la création de véhicules
L'API Fleet Engine écrit une entrée de journal via Google Cloud Platform lorsqu'une
au point de terminaison CreateVehicle
est reçu. L'entrée de journal inclut
des informations sur les valeurs de la requête CreateVehicle
. Si l'appel
réussit, il inclut également des informations sur l'Vehicle
qui a été
renvoyé.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
Il doit imprimer un enregistrement semblable à celui-ci:
---
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'
Notifications Cloud Pub/Sub pour la création de véhicules
L'API Fleet Engine publie une notification via Cloud Pub/Sub lorsqu'une nouvelle le véhicule est créé. Pour recevoir ces notifications, veuillez suivre les consultez ces instructions.
PROCÉDURE: Mettre à jour l'emplacement d'un véhicule
Si vous n'utilisez pas le SDK Driver pour mettre à jour la position du véhicule, vous pouvez effectuer une appel direct à Fleet Engine avec l'emplacement du véhicule. Pour tout véhicule actif, Fleet Engine attend une mise à jour de la position au moins une fois par minute et au maximum toutes les 5 secondes. Ces mises à jour ne nécessitent qu'un utilisateur du SDK pilote Fleet Engine de droits.
Exemple
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
Voir providers.vehicles.update référence.
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.
PROCÉDURE: Mettre à jour d'autres champs pour les véhicules
Les mises à jour d'autres attributs de l'état du véhicule sont moins fréquentes
la position de votre annonce. Les mises à jour d'attributs autres que last_location
nécessitent
Droits de super-utilisateur Fleet Engine
Le UpdateVehicleRequest
inclut un update_mask
pour indiquer les champs à
mise à jour. Le comportement du champ est le même que dans la documentation Protobuf pour
masques de champ.
Comme indiqué dans Attributs du véhicule, mettre à jour les
Le champ attributes
nécessite d'écrire tous les attributs à conserver. Il
n'est pas possible de simplement mettre à jour la valeur d'une paire clé-valeur dans une
UpdateVehicle
appel. Pour mettre à jour les valeurs d'attributs spécifiques,
Vous pouvez utiliser l'API UpdateVehicleAttributes
.
Exemple
Cet exemple active 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
Voir providers.vehicles.update référence.
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.
Journaux Google Cloud Platform pour les mises à jour de véhicules
L'API Fleet Engine écrit une entrée de journal via Google Cloud Platform lorsqu'une
au point de terminaison UpdateVehicle
est reçu. L'entrée de journal inclut
des informations sur les valeurs de la requête UpdateVehicle
. Si l'appel
réussit, il inclut également des informations sur l'Vehicle
qui a été
renvoyé.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
Notifications Cloud Pub/Sub pour les mises à jour du véhicule
L'API Fleet Engine publie une notification via Cloud Pub/Sub lorsqu'un objet véhicule est mis à jour. Pour recevoir ces notifications, veuillez suivre les consultez ces instructions.
INSTRUCTIONS: Rechercher des véhicules
Fleet Engine permet de rechercher des véhicules. SearchVehicles
L'API vous permet de trouver les conducteurs disponibles à proximité les mieux adaptés à une tâche telle que
le traitement d'un trajet
ou d'une demande de livraison. L'API SearchVehicles
renvoie une
classement des conducteurs qui associent les attributs de tâche aux attributs de véhicules dans
votre parc. Pour en savoir plus, consultez
Identifier les conducteurs à proximité
Exemple
Lorsqu'il recherche des véhicules disponibles, Fleet Engine exclut les véhicules de les trajets actifs par défaut. Les services du Fournisseur de covoiturage ou de livraison doivent les inclure explicitement dans les requêtes de recherche. L'exemple suivant montre comment inclure ces véhicules dans la recherche de véhicules correspondant à un trajet depuis le Grand Indonesia East Mall au centre de congrès Balai Sidang Jakarta.
shell
Modifiez d'abord l'emplacement du véhicule que nous avons créé lors des étapes précédentes est éligible. En situation réelle, c'est le SDK Driver qui exécute sur un appareil Android ou iOS dans le véhicule.
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 recherche doit permettre d'obtenir au moins ce véhicule.
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
Voir providers.vehicles.search référence.
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;
}
Requête de filtrage des véhicules
SearchVehicles
et ListVehicles
acceptent le filtrage en fonction des attributs du véhicule
à l'aide d'une requête de filtre. Pour connaître la syntaxe d'une requête de filtre, consultez
AIP-160 pour obtenir des exemples.
Notez que les requêtes de filtrage SEULEMENT permettent de filtrer en fonction des attributs du véhicule.
ne peut pas être utilisée pour d'autres champs. La requête de filtre fonctionne comme une clause AND
.
avec d'autres contraintes, telles que minimum_capacity
ou vehicle_types
dans
SearchVehiclesRequest
INSTRUCTIONS: Lister les véhicules
SearchVehicles
est optimisé pour trouver un petit nombre de véhicules dans le classement
commandent très rapidement, principalement pour trouver les chauffeurs à proximité les mieux adaptés
à une tâche. Cependant, il peut arriver que vous souhaitiez trouver tous les véhicules correspondant
même si la pagination des résultats est nécessaire. ListVehicles
correspond à
conçues pour ce cas d'utilisation.
L'API ListVehicles
vous permet de trouver tous les véhicules répondant à des critères spécifiques
options de requête. L'API ListVehicles
renvoie une liste paginée de véhicules dans
le projet qui répond
à certaines exigences.
Pour effectuer un filtrage en fonction des attributs des véhicules, consultez Requête de filtrage des véhicules.
Exemple
Cet exemple effectue un filtrage sur vehicle_type
et sur les attributs à l'aide du
Chaîne 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
Voir providers.vehicles.list référence.
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;
}
Voyages et leur cycle de vie
L'API Trip et son cycle de vie sont semblables à ceux de l'API Vehicle.
Le fournisseur de services de VTC est chargé de créer des trajets à l'aide de Fleet Engine
de commande. Fleet Engine fournit
un service RPC,
TripService
.
et les ressources REST, provider.trips
pour en savoir plus. Ces interfaces permettent de créer des entités de trajet, de demander des informations, de rechercher
les fonctionnalités et la capacité de mise à jour.
Un Trip
comporte un champ d'état permettant de suivre sa progression tout au long du cycle de vie.
Les valeurs vont de NEW
à COMPLETE
, plus CANCELED
et UNKNOWN_TRIP_STATUS
pour en savoir plus. Reportez-vous à trip_status
pour les appels RPC.
ou TripStatus pour REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Votre service peut mettre à jour le trajet vers CANCELED
à partir de n'importe lequel de ces états.
Lorsque votre service crée un trajet, le moteur définit l'état sur NEW
. A
vehicle_id
est facultatif. Comme pour les véhicules, les services suppriment automatiquement les trajets non attribués
au bout de sept jours sans mise à jour. Si votre service tente de créer un trajet avec
qui existe déjà, une erreur est renvoyée. Un trajet est considéré comme "actif" si
son état est différent de COMPLETE
ou CANCELED
; Cette distinction est
important dans le champ active_trips
de l'entité "Véhicule" et dans SearchTripsRequest
.
Votre service ne peut modifier les vehicle_id
attribués à un trajet que lorsque celui-ci
est actif. Par exemple, lorsqu'un conducteur annule un trajet
itinéraire et le trajet est réaffecté à un autre véhicule.
L'état est important lors de l'implémentation de l'annonce à la suite. une aide au voyage. Cette prise en charge permet au fournisseur d'attribuer un nouveau trajet à un véhicule. lorsque ce Véhicule effectue un trajet actif. Le code pour créer un trajet aller-retour est identique à un trajet unique et utilise la même identifiant du véhicule. Fleet Engine ajoute le point de départ et la destination du nouveau trajet au les points de cheminement du véhicule. Pour en savoir plus sur les trajets interdépendants, consultez Créer des trajets avec plusieurs points de cheminement
Points de cheminement restants du trajet
L'entité "Trip" contient un champ répété TripWaypoint
(RPC | REST),
appelé remainingWaypoints
(RPC | REST).
Ce champ inclut tous les points de cheminement que le véhicule devra parcourir dans l'ordre
avant le dernier point de dépose. Il calcule à partir de
Points de cheminement restants du véhicule.
Dans les cas d'utilisation "Retour à dos" et "Carpool", cette liste contient les points de cheminement
Autres trajets qui seront traversés avant ce trajet, mais exclut les points de cheminement
après ce trajet. Le point de cheminement dans la liste peut être identifié par son TripId
et WaypointType
.
Relation entre l'état du trajet et les points de cheminement restants du véhicule
Les points de cheminement restants du véhicule (RPC | REST)
doit être mis à jour lorsque Fleet Engine reçoit une demande de modification d'état du trajet. La
le point de cheminement précédent sera supprimé de la liste des points de cheminement restants du véhicule
la commande tripStatus
(RPC | REST)
passe de l'autre état à ENROUTE_TO_XXX. C'est-à-dire, lorsque
l'état du trajet est passé de ENROUTE_TO_PICKUP à ARRIVED_AT_PICKUP, le nombre
figure toujours dans la liste des points de cheminement restants du véhicule, mais lors du trajet
son état est remplacé par ENROUTE_TO_INTERMEDIATE_DESTINATION ou ENROUTE_TO_DROPOFF,
son point de prise en charge est alors supprimé des autres points de cheminement du véhicule.
Il en va de même pour ARRIVED_AT_INTERMEDIATE_DESTINATION et ENROUTE_TO_INTERMDEDIATE_DESTINATION. Lorsque ARRIVED_AT_INTERMEDIATE_DESTINATION, la destination intermédiaire actuelle ne sera pas supprimée du reste du véhicule jusqu'à ce que le véhicule signale l'itinéraire vers le point de cheminement suivant.
Lorsque l'état du trajet est défini sur COMPLETED
, aucun point de cheminement ne sera
dans la liste des points de cheminement restants du véhicule.
PROCÉDURE: Créer un voyage
Une entité Trip
doit être créée pour que chaque demande de trajet soit suivie et
correspondant aux véhicules du parc. Utiliser le point de terminaison CreateTrip
avec CreateTripRequest
pour créer un voyage.
Les attributs suivants sont obligatoires pour créer un trajet:
parent
: chaîne incluant l'ID de fournisseur créé lorsque le gestionnaire La valeur Projet Cloud a été créée.trip_id
: chaîne créée par le fournisseur de services de VTC.trip
: conteneur avec les métadonnées de base décrivant le trajet.trip_type
: énumération indiquant si le trajet peut inclure ou non d'autres usagers d'un point de départ et d'une destination différents dans le même véhicule (SHARED
) ou une partie individuelle uniquement (EXCLUSIVE
).pickup_point
: TerminalLocation représentant le point de départ du voyage. Consultez la documentation de référence sur RPC. ou documentation de référence REST
Lorsque vous créez un voyage, vous pouvez fournir les éléments suivants :number_of_passengers
, dropoff_point
et vehicle_id
. Même si ces champs ne sont pas obligatoires,
elles sont conservées. Tous les autres champs "Trip" sont ignorés. Par exemple, tous les trajets
commencez par un trip_status
de NEW
, même si vous transmettez un trip_status
de
CANCELED
dans la requête de création.
Exemple
L'exemple suivant crée un trajet vers le Grand Indonesia East Mall. Le voyage
est réservé à deux passagers. L'provider_id
de Trip
doit être
identique à l'ID du projet. Dans cet exemple, le fournisseur de services de VTC a créé la
Projet Google Cloud, project-id. Ce projet doit disposer du
Comptes de service utilisés pour appeler Fleet Engine. L'état du trajet est NEW
.
Plus tard, une fois que le service a mis en correspondance le trajet avec un véhicule, il peut appeler
UpdateTrip
et modifier le vehicle_id
lorsque le trajet est attribué à un véhicule.
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
Voir providers.trips.create référence.
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;
}
Journaux Google Cloud Platform pour la création de trajets
L'API Fleet Engine écrit une entrée de journal à l'aide des journaux Google Cloud Platform lorsqu'une
au point de terminaison CreateTrip
est reçu. L'entrée de journal inclut
des informations sur les valeurs de la requête CreateTrip
. Si l'appel
réussit, il inclut également des informations sur le Trip
renvoyé.
PROCÉDURE: Mettre à jour un trajet
L'entité "Trip" contient des champs permettant le suivi par le service et pour
en signalant la progression du trajet par le SDK Driver et au
Consumer SDK. Pour mettre à jour les propriétés, utilisez UpdateTripRequest
.
. Les champs "Trip" sont alors mis à jour en fonction du field_mask
de la requête.
Consultez UpdateTripRequest.
Le fournisseur de services de VTC est chargé de mettre à jour les attributs suivants:
- État du trajet.
- ID du véhicule. Soit au moment de la création du véhicule, soit après avoir associé le véhicule à un voyage.
- Modifications apportées aux points de prise en charge, de dépose ou de cheminement
Fleet Engine met automatiquement à jour les champs suivants lorsque vous utilisez la Fonctionnalité de partage de parcours via le SDK Driver ou le SDK Consumer:
- Routes
- ETA
- Distance restante
- Emplacement du véhicule
- Points de cheminement restants
Reportez-vous à Trip
dans RPC ou
Resource.Trip
dans REST.
Journaux Google Cloud Platform pour les mises à jour des trajets
L'API Fleet Engine écrit une entrée de journal à l'aide des journaux Google Cloud Platform lorsqu'une
au point de terminaison UpdateTrip
est reçu. L'entrée de journal inclut
des informations sur les valeurs de la requête UpdateTrip
. Si l'appel aboutit,
il inclut également des informations sur l'élément Trip
renvoyé.
PROCÉDURE: Rechercher des trajets
Fleet Engine permet de rechercher des trajets. Comme indiqué précédemment, un trajet est
sont automatiquement supprimées au bout de sept jours. SearchTrips
pour afficher l'historique complet de tous les trajets.
Bien que SearchTrips
soit une API flexible, la liste ci-dessous prend en compte deux cas d'utilisation.
Déterminer les trajets actifs d'un véhicule : le fournisseur peut déterminer les trajets actuellement actifs d'un véhicule. Dans
SearchTripsRequest
, levehicle_id
est défini sur le véhicule en cours d'examen etactive_trips_only
doit être défini surtrue
.Rapprocher l'état du fournisseur et de Fleet Engine : le fournisseur peut utiliser
SearchTrips
pour s'assurer que l'état de leur trajet et celui de Fleet Engine correspondent. Ce point est particulièrement important pour TripStatus. Si l'état d'un trajet sur "Vehicle" n'est pas correctement défini surCOMPLETE
ouCANCELED
, le "Vehicle" n'est pas incluse dansSearchVehicles
.
Pour utiliser SearchTrips
de cette manière, laissez le champ vehicle_id
vide, définissez active_trips_only
sur true
et définissez minimum_staleness
sur une heure supérieure à la plupart des durées de trajet.
Par exemple, vous pouvez utiliser une heure. Les résultats incluent des trajets qui ne sont pas
TERMINÉ ou ANNULÉ, et qui n'ont pas été mis à jour depuis plus d'une heure. Le fournisseur
devez examiner ces trajets pour s'assurer que leur état dans Fleet Engine est
correctement mis à jour.
Dépannage
En cas d'erreur DEADLINE_EXCEEDED
, l'état de Fleet Engine est
inconnu. Le fournisseur doit appeler à nouveau CreateTrip
, ce qui renvoie
201 (CREATED) ou 409 (CONFLICT). Dans ce dernier cas, la requête précédente a abouti.
avant le DEADLINE_EXCEEDED
. Pour en savoir plus, consultez les guides de l'API Consumer
sur la gestion des erreurs de trajet: Android
ou iOS.
Assistance concernant les trajets en covoiturage
Vous pouvez attribuer plusieurs trajets SHARED
à un véhicule compatible avec TripType.SHARED
.
Vous devez indiquer l'ordre de tous les points de cheminement non transmis pour tous les trajets auxquels
le véhicule dans ce trajet partagé via Trip.vehicle_waypoints
lorsque vous attribuez le
vehicle_id
pour un trajet partagé (dans une requête CreateTrip
ou UpdateTrip
).
Reportez-vous à vehicle_waypoints
pour les appels RPC.
ou vehicleWaypoints
pour REST.
Compatibilité avec plusieurs destinations
Identifier une destination intermédiaire
Les champs intermediateDestinations
et intermediateDestinationIndex
dans le trajet (RPC | REST)
sont combinés pour indiquer la destination.
Mettre à jour la destination intermédiaire
Vous pouvez mettre à jour les destinations intermédiaires via UpdateTrip
. Lors de la mise à jour
les destinations intermédiaires, vous devez fournir la liste complète des destinations intermédiaires,
y compris ceux qui ont été visités, et pas seulement
ajoutés ou à modifier.
Lorsque intermediateDestinationIndex
pointe vers un indice après la position de
destination intermédiaire récemment ajoutée/modifiée, la destination intermédiaire nouvelle/mise à jour
la destination ne sera pas ajoutée au waypoints
du véhicule ni au remainingWaypoints
du trajet.
La raison est que toute destination intermédiaire avant intermediateDestinationIndex
sont traités comme déjà visités.
Modifications de l'état des trajets
Le champ intermediateDestinationsVersion
dans (RPC | REST)
est requis dans la demande de mise à jour de l'état du trajet envoyée à Fleet Engine pour indiquer
une destination intermédiaire est passée. La destination intermédiaire ciblée
est spécifiée via le champ intermediateDestinationIndex
.
Lorsque tripStatus
(RPC | REST) est défini sur ENROUTE_TO_INTERMEDIATE_DESTINATION, un nombre compris entre
[0..N-1] indique la prochaine destination intermédiaire que le véhicule traversera.
Lorsque tripStatus
est ARRIVED_AT_INTERMEDIATE_DESTINATION, un nombre compris entre
[0..N-1] indique la destination intermédiaire du véhicule.
Exemple
L'exemple de code suivant montre comment mettre à jour l'état d'un trajet pour qu'il passe en route vers sa première destination intermédiaire, en supposant que vous avez créé un trajet à plusieurs destinations et qui a dépassé son point de prise en charge.
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;
}
PROCÉDURE: S'abonner aux messages de notification de l'API Fleet Engine
L'API Fleet Engine utilise Google Cloud Pub/Sub pour publier des notifications sur le sujet créé par le client Projet. Pub/Sub n'est pas activé par défaut pour Fleet Engine sur Google Cloud projet. Veuillez déposer une demande d'assistance ou contacter votre ingénieur client pour activer Pub/Sub.
Pour créer un sujet dans votre projet Cloud, suivez ces instructions. L'ID du sujet doit être "fleet_engine_notifications".
Le sujet doit être créé dans le projet Cloud qui appelle Fleet Engine API.
Une fois le sujet créé, vous devez accorder à l'API Fleet Engine
l'autorisation de publier sur le sujet. Pour ce faire, cliquez sur le sujet
que vous venez de créer et
d’ajouter une nouvelle autorisation. Vous devrez peut-être cliquer sur AFFICHER LE PANNEAU D'INFORMATIONS pour ouvrir l'éditeur d'autorisations.
Le compte principal doit être geo-fleet-engine@system.gserviceaccount.com
et le rôle doit être Pub/Sub publisher
.
Pour configurer votre projet Cloud afin de vous abonner aux notifications, suivez ces instructions.
L'API Fleet Engine publiera chaque notification dans deux données différentes
formats, protobuf
et
json
Le format des données de chaque notification est indiqué dans la
Attributs PubsubMessage
avec la clé data_format
et la valeur protobuf
ou json
.
Schéma de notification:
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"
}
}
}