Premiers pas avec Fleet Engine

L'API On-demand Rides and Deliveries de Fleet Engine vous permet de gérer les trajets et l'état des véhicules pour vos applications Trip et Order Progress. Il gère les transactions entre le SDK Driver, le SDK Consumer et votre service de backend, qui peuvent communiquer avec Fleet Engine via des appels gRPC ou REST.

Conditions préalables

Pour le développement, assurez-vous d'installer le SDK Cloud (gcloud) et d'être authentifié auprès de votre projet.

Remarque :Envisagez d'utiliser l'environnement interactif Cloud Shell dans lequel Cloud SDK et d'autres dépendances telles que curl sont déjà installés. Consultez la page Utiliser Cloud Shell.

shell

gcloud auth login

Un message indiquant que l'opération a réussi doit s'afficher:

You are now logged in as [[e-mail]].
Your current project is [project-id].  You ...

Remarque :Modifiez les valeurs des variables dans les blocs de code pour préparer les commandes suivantes afin de pouvoir les copier et les coller directement.

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 l'administrateur de votre projet et votre représentant de l'assistance Google pour obtenir l'accès.

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 comment lire et analyser les journaux.

Il est possible que la journalisation ne soit pas activée par défaut pour les projets créés avant le 10 février 2022. Pour en savoir plus, consultez la documentation sur la journalisation.

Bibliothèques clientes

Nous publions des bibliothèques clientes dans plusieurs langages de programmation courants. Ces bibliothèques permettent d'offrir aux développeurs une meilleure expérience utilisateur par rapport aux services REST ou gRPC bruts. Pour savoir comment obtenir des bibliothèques clientes pour votre application de serveur, consultez la page 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 la progression des trajets et des commandes 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 à partir de Cloud Console.

Configuration du projet Cloud

Pour configurer votre projet Cloud, commencez par créer votre projet, puis créez des comptes de service.

Pour créer votre projet Google Cloud:

1. Créez un projet Google Cloud à l'aide de la console Google Cloud.
2. À l'aide du tableau de bord des API et services, activez l'API Local Rides and Deliveries.

Les comptes de service sont associés à un ou plusieurs rôles. Ils permettent de créer des jetons Web JSON qui accordent différents ensembles d'autorisations en fonction des rôles. En règle générale, pour réduire les risques d'utilisation abusive, vous pouvez créer plusieurs 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 doté de ce rôle sont généralement utilisés à partir des appareils mobiles de votre application mobile de partage de course ou de livraison.
Utilisateur du SDK pilote Fleet Engine roles/fleetengine.driverSdkUser	Accorde l'autorisation de mettre à jour l'emplacement des véhicules et les itinéraires, et de récupérer des informations sur les véhicules et les trajets. Les jetons créés par un compte de service doté de ce rôle sont généralement utilisés à partir de votre application mobile 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 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).
Super-utilisateur du service FlexEngine **(OBSOLÈTE)** roles/fleetengine.serviceSuperUser	Accorde l'autorisation à toutes les API liées aux véhicules et aux trajets. Les jetons générés par un compte de service doté de ce rôle sont généralement utilisés à partir de vos serveurs backend. Ce rôle est obsolète. Préférez roles/fleetengine.ondemandAdmin à la place.

Par exemple, créez un compte de service pour chacun des trois rôles et attribuez-leur 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:[e-mail] \
       --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:[e-mail] \
       --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:[e-mail] \
       --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 qui permettent de regrouper un ensemble arbitraire d'autorisations. Les SDK Driver et Consumer SDK affichent des messages d'erreur chaque fois qu'une autorisation requise est manquante. Par conséquent, nous vous recommandons vivement d'utiliser l'ensemble standard de rôles présenté ci-dessus et de ne pas utiliser de rôles personnalisés.

Pour plus de commodité, si vous devez créer des jetons JWT pour des clients non approuvés, ajouter des utilisateurs au rôle Créateur de jetons du compte de service leur permet de créer des jetons à l'aide des outils de ligne de commande gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Où [e-mail] est l'adresse e-mail utilisée pour l'authentification auprès de gcloud (gcloud auth list --format='value(account)').

Remarque :Cela permet au bénéficiaire d'emprunter l'identité de n'importe quel compte de service du projet. Pour définir des autorisations plus précises, consultez la documentation IAM sur la limitation du champ d'application des liaisons de rôle à un compte de service spécifique.

Bibliothèque d'authentification Fleet Engine

Fleet Engine utilise des jetons Web JSON (JWT, JSON Web Tokens) pour limiter l'accès aux API Fleet Engine. La nouvelle bibliothèque d'authentification Fleet Engine, disponible sur GitHub, simplifie la construction de jetons JWT Fleet Engine et les signe de manière 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 (par exemple, en empruntant l'identité d'un compte de service).
• Associe des jetons signés aux requêtes sortantes effectuées à partir d'un bouchon gRPC ou d'un client GAPIC.

Important :Nous vous recommandons vivement d'utiliser la bibliothèque Auth Fleet Engine avec toutes les implémentations Java.

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 créés directement dans votre codebase. Pour cela, vous devez avoir une connaissance approfondie des jetons JWT et de leur relation avec Fleet Engine. C'est pourquoi nous vous recommandons vivement d'utiliser la bibliothèque Auth Fleet Engine.

Dans Fleet Engine, les jetons Web JSON (JWT) fournissent une authentification de courte durée et garantissent que les appareils ne peuvent modifier que les véhicules, les trajets ou les tâches pour lesquels 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 la clé privée à utiliser (obtenue à partir des comptes de service) et l'algorithme de chiffrement. La section de revendication contient des informations telles que la date de création du jeton, la valeur TTL (Time To Live) des jetons, les services auxquels il demande l'accès et d'autres informations d'autorisation pour réduire l'accès (par exemple, l'ID du véhicule).

Une section d'en-tête JWT contient les champs suivants:

Champ	Description
alg	Algorithme à utiliser. "RS256".
typ	Type de jeton. "JWT".
enfant	ID de la clé privée de votre compte de service. Vous trouverez 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 l'horodatage est trop ancien ou trop éloigné dans le futur, le serveur peut signaler une erreur.
exp	Horodatage 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 l'horodatage est éloigné de plus d'une heure.
autorisation	Peut contenir "vehicleid" ou "tripid", selon le cas d'utilisation.

La création d'un jeton JWT fait référence à sa signature. Pour obtenir des instructions et des exemples de code sur la création et la signature du jeton JWT, consultez la page Autorisation de compte de service sans OAuth. Vous pouvez ensuite associer un jeton signé aux appels gRPC ou à d'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 la section d'autorisation avec la clé vehicleid ou tripid définie sur la valeur de l'ID du véhicule ou du trajet pour lequel l'appel est effectué.

Le SDK Driver utilise toujours la revendication vehicleid, qu'il s'agisse d'un trajet ou d'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 vehicleid ou tripid avec un "*" pour faire correspondre tous les véhicules et tous les trajets. Notez que le JWT peut contenir les deux jetons, même s'ils ne sont pas obligatoires, ce qui peut simplifier la mise en œuvre de la signature de 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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

• Dans le champ kid de l'en-tête, spécifiez l'ID de clé privée de votre compte de service. Vous trouverez cette valeur dans le champ private_key_id du fichier JSON de votre compte de service.
• Dans les champs iss et sub, indiquez l'adresse e-mail de votre compte de service. Vous trouverez cette valeur dans le champ client_email du fichier JSON de votre compte de service.
• Pour le champ aud, indiquez https://SERVICE_NAME/.
• Pour le champ iat, utilisez l'horodatage 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 code temporel est trop ancien ou futur, le serveur peut signaler une erreur.
• Pour le champ exp, utilisez le code temporel d'expiration du jeton, spécifié en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. La valeur maximale autorisée est iat + 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. Sinon, l'appareil mobile sera en mesure de modifier l'état qu'il ne devrait pas avoir.

De même, lorsque vous signez le jeton JWT à utiliser pour les appels privilégiés, assurez-vous d'utiliser le compte de service avec le rôle de super-utilisateur. Sinon, 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 compte utilisateur doit disposer du rôle Créateur de jetons du compte de service:

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Créez un fichier nommé unsigned_token.json avec le contenu ci-dessous. La propriété iat correspond à l'heure actuelle, exprimée en nombre de secondes, après l'epoch. Vous pouvez la récupérer en exécutant date +%s dans votre terminal. La propriété exp correspond au délai d'expiration en nombre de secondes après l'epoch. Il peut être calculé en ajoutant 3 600 à iat. Le délai d'expiration ne peut pas être fixé à plus d'une heure dans le futur.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Exécutez ensuite la commande gcloud suivante pour signer le jeton au nom de votre compte de service super-utilisateur:

gcloud beta iam service-accounts sign-jwt --iam-account=[e-mail] 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 le point de terminaison REST List Vehicles:

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, il n'est pas possible de suivre séparément un Conducteur et un véhicule. Le fournisseur de services de covoiturage ou de livraison crée un véhicule à l'aide d'un ID de fournisseur (qui doit être identique à l'ID de projet du projet Google Cloud contenant le compte de service utilisé pour appeler les API Fleet Engine) et d'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 sera automatiquement supprimé. Pour que votre véhicule reste disponible dans Fleet Engine, il est recommandé de mettre à jour sa position à intervalles réguliers. Les mises à jour de la plupart des autres champs de l'entité Vehicle prolongent également sa durée de vie, à condition que la nouvelle valeur de champ soit différente de la valeur existante.

REMARQUE: Certains champs de l'entité Vehicle, tels que device_settings, ne sont que des informations de débogage qui ne sont pas conservées par Fleet Engine. Leur mise à jour ne prolonge pas la durée de vie de l'entité Vehicle.

Vous ne pouvez pas appeler CreateVehicle avec une paire ID de fournisseur/ID de véhicule qui existe déjà. Le cas des véhicules qui ne sont pas mis à jour fréquemment peut être traité de deux manières: appeler fréquemment CreateVehicle avec une paire ID fournisseur/ID de véhicule attendue et supprimer l'erreur si le véhicule existe déjà, ou appeler CreateVehicle après une UpdateVehicle renvoyée avec une erreur NOT_FOUND.

Mises à jour de la position des véhicules

Pour optimiser les performances de Fleet Engine, fournissez-lui un flux de mises à jour de la position des véhicules. Pour fournir ces mises à jour, utilisez l'une des méthodes suivantes:

1. Utilisez le SDK Driver pour Android ou iOS. Il s'agit de l'option la plus simple.
2. Utilisez un code personnalisé : utile si les emplacements sont retransmis via votre backend, ou si vous utilisez des appareils autres qu'Android ou iOS.

Type de véhicule

L'entité "Véhicule" contient un champ obligatoire VehicleType, qui comporte une énumération Category pouvant être spécifiée comme AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE ou PEDESTRIAN. Le type de véhicule peut servir de critère de filtre dans SearchVehicles et ListVehicles.

Tous les itinéraires pour les véhicules utilisent le RouteTravelMode correspondant si 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 attributs ne sont pas interprétés par Fleet Engine. L'API SearchVehicles inclut un champ qui exige que la valeur Vehicles correspondante contienne tous 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, tels que vehicle_type et supported_trip_types.

Points de cheminement restants du véhicule

L'entité Véhicule contient un champ répété de TripWaypoint (RPC | REST), appelé waypoints(RPC | REST). Ce champ inclut les points de cheminement restants dans les trajets, dans l'ordre dans lequel le véhicule les atteigne. Fleet Engine calcule ce champ au fur et à mesure que les trajets sont attribués au véhicule et le met à jour à mesure que leur é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, les services de VTC ou du Prestataire de livraison sont chargés de mettre en correspondance les demandes de trajet et les véhicules. Le service peut utiliser les attributs du véhicule pour inclure un véhicule dans 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: is_bronze_level, is_silver_level et is_gold_level. Un véhicule peut être éligible à ces trois fonctionnalités. Lorsque Fleet Engine reçoit une demande de trajet nécessitant des capacités de niveau Argent, la recherche inclut ce véhicule. Une telle utilisation des attributs inclut les véhicules offrant diverses fonctionnalités.

Il existe deux façons de mettre à jour les attributs d'un véhicule. L'une d'elles est l'API UpdateVehicle. Lorsque vous utilisez cette API, l'ensemble des attributs du véhicule est 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 requête seront définis sur la nouvelle valeur ou ajoutés. 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 le CreateVehicleRequest pour créer un véhicule.

Remarque :CreateVehicle nécessite un compte doté du rôle Super-utilisateur Fleet Engine.

Le provider_id de Vehicle doit correspondre à l'ID du projet Google Cloud (par exemple, my-on-demand-project) contenant les 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 fournisseur de covoiturage ou de livraison, Fleet Engine n'accepte actuellement pas les comptes de service provenant de plusieurs projets Google Cloud accédant au même Vehicles.

Le Vehicle peut être créé à l'état OFFLINE ou ONLINE. S'il est créé ONLINE, il peut être immédiatement renvoyé en réponse aux requêtes SearchVehicles.

Un last_location initial peut être inclus dans l'appel CreateVehicle. Bien que cela soit autorisé, un Vehicle ne doit pas être créé à l'état ONLINE sans last_location.

Pour en savoir plus sur le champ "Type de véhicule", consultez Types de véhicules.

Consultez Attributs du véhicule pour en savoir plus sur le champ des 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

Consultez la documentation de référence sur providers.vehicles.create.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

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

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

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

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

Journaux Google Cloud Platform pour la création de véhicules

L'API Fleet Engine écrit une entrée de journal via les journaux Google Cloud Platform lorsqu'un appel 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 aboutit, les informations sur le Vehicle renvoyé sont également incluses.

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'un véhicule est créé. Pour recevoir ces notifications, veuillez suivre 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 appeler directement Fleet Engine en indiquant sa position. La position de chaque véhicule actif doit être mise à jour au moins une fois par minute et toutes les cinq secondes au maximum. Ces mises à jour ne nécessitent que des droits d'utilisateur pour le SDK pilote Fleet Engine.

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

Consultez la documentation de référence sur providers.vehicles.update.

Java

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

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

PROCÉDURE: Mettre à jour d'autres champs pour les véhicules

Les mises à jour d'autres attributs de l'état du véhicule se produisent moins souvent que les mises à jour de la position. Les mises à jour d'attributs autres que last_location nécessitent des droits de super-utilisateur Parc Engine.

Le UpdateVehicleRequest inclut un update_mask pour indiquer les champs à mettre à jour. Le comportement du champ est identique à celui indiqué dans la documentation Protobuf pour les masques de champ.

Remarque :Le champ update_mask doit toujours être défini. Si vous ne définissez pas le champ update_mask, tous les champs sont écrits par défaut. Cela peut entraîner un comportement inattendu.

Comme indiqué dans Attributs du véhicule, la mise à jour du champ attributes nécessite l'écriture de tous les attributs à conserver. Il n'est pas possible de simplement mettre à jour la valeur d'une paire clé-valeur dans un appel UpdateVehicle. Vous pouvez utiliser l'API UpdateVehicleAttributes pour mettre à jour les valeurs d'attributs spécifiques.

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

Consultez la documentation de référence sur providers.vehicles.update.

Java

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

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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

Journaux Google Cloud Platform pour les mises à jour de véhicules

L'API Fleet Engine écrit une entrée de journal via les journaux Google Cloud Platform lorsqu'un appel 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 aboutit, les informations sur le Vehicle renvoyé sont également incluses.

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 véhicule existant est mis à jour. Pour recevoir ces notifications, veuillez suivre ces instructions.

INSTRUCTIONS: Rechercher des véhicules

Fleet Engine permet de rechercher des véhicules. L'API SearchVehicles vous permet de trouver les chauffeurs à proximité disponibles qui conviennent le mieux à une tâche telle que le traitement d'un trajet ou d'une demande de livraison. L'API SearchVehicles renvoie une liste classée de conducteurs correspondant aux attributs de tâche et aux attributs de véhicules de votre parc. Pour en savoir plus, consultez Rechercher des conducteurs à proximité.

Exemple

Lorsque vous recherchez des véhicules disponibles, Fleet Engine exclut les véhicules des trajets actifs par défaut. Les services du fournisseur de services de VTC 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 entre le Grand Indonesia East Mall et le Balai Sidang Jakarta Convention Center.

shell

Commencez par modifier l'emplacement du véhicule que nous avons créé lors des étapes précédentes afin qu'il soit éligible. Dans le monde réel, cette opération serait effectuée par le SDK Driver exécuté 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

Consultez la documentation de référence sur providers.vehicles.search.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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

Requête de filtrage des véhicules

SearchVehicles et ListVehicles sont compatibles avec le filtrage des attributs de véhicule à l'aide d'une requête de filtre. Pour en savoir plus sur la syntaxe des requêtes de filtre, consultez la page AIP-160 pour obtenir des exemples.

Notez que les requêtes de filtre sont compatibles SEULEMENT avec le filtrage sur les attributs de véhicule et ne peuvent pas être utilisées 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.

Remarque :Nous vous recommandons vivement d'utiliser le champ de requête filter pour les champs required_attributes, required_one_of_attributes et required_one_of_attributes_sets, car filter est conçu pour remplacer ces champs. Si une valeur non vide est spécifiée dans le champ filter, les champs suivants doivent être vides: required_attributes, required_one_of_attributes et required_one_of_attributes_sets.

INSTRUCTIONS: Lister les véhicules

SearchVehicles est optimisé pour trouver très rapidement un petit nombre de véhicules dans l'ordre de classement. Il est principalement utilisé pour trouver les conducteurs à proximité les mieux adaptés à une tâche donnée. Cependant, il peut arriver que vous souhaitiez trouver tous les véhicules qui répondent à certains critères, même si la pagination des résultats est nécessaire. ListVehicles est conçu pour ce cas d'utilisation.

L'API ListVehicles vous permet de rechercher tous les véhicules qui répondent à certaines options de requête spécifiques. L'API ListVehicles renvoie une liste paginée des véhicules du projet, qui répond à certaines exigences.

Pour effectuer un filtrage en fonction des attributs des véhicules, veuillez consulter Requête de filtrage des véhicules.

Exemple

Cet exemple effectue un filtrage sur vehicle_type et sur les attributs à l'aide de la 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

Consultez la documentation de référence sur providers.vehicles.list.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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 covoiturage est chargé de créer des trajets à l'aide des interfaces de Fleet Engine. Fleet Engine fournit à la fois un service RPC TripService et des ressources REST, provider.trips. Ces interfaces permettent la création d'entités de trajet, les requêtes d'informations, les fonctionnalités de recherche et les fonctionnalités 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. Consultez trip_status pour 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. Un vehicle_id est facultatif. Comme pour les véhicules, les services suppriment automatiquement les trajets au bout de sept jours sans mise à jour. Si votre service tente de créer un trajet avec un ID qui existe déjà, une erreur est renvoyée. Un trajet est considéré comme "actif" s'il a un état autre que COMPLETE ou CANCELED. Cette distinction est importante dans le champ active_trips de l'entité "Véhicule" et dans SearchTripsRequest.

Votre service ne peut modifier la valeur vehicle_id attribuée à un trajet que lorsque celui-ci est actif. Par exemple, vous pouvez effectuer cette opération lorsqu'un conducteur annule un trajet en cours de route et que celui-ci est réattribué à un autre véhicule.

L'état est important lors de la mise en œuvre de la prise en charge des trajets effectués les uns après les autres. Cette prise en charge permet au fournisseur d'attribuer un nouveau trajet à un véhicule lorsque celui-ci est sur un trajet actif. Le code permettant de créer un trajet aller-retour est le même que pour un trajet unique et utilise le même identifiant de véhicule. Fleet Engine ajoute le point de départ et la destination du nouveau trajet aux points de cheminement du véhicule. Pour en savoir plus sur les trajets aller-retour, consultez la section Créer des trajets avec plusieurs points de cheminement.

Remarque :Fleet Engine ne permet pas de supprimer explicitement un trajet. Le service supprime automatiquement les trajets après sept jours sans être mis à jour. Google ne conserve pas les données à caractère personnel. Si vous souhaitez conserver les données sur les trajets, le fournisseur de services de VTC doit implémenter cette fonctionnalité.

Points de cheminement restants du trajet

L'entité "Trip" contient un champ répété de type 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épôt de ce trajet. Il effectue le calcul à partir des points de cheminement restants du véhicule. Dans les cas d'utilisation "Retour à dos" et "Carpool", cette liste contient les points de cheminement d'autres trajets qui seront traversés avant ce trajet, mais ne les exclut pas après ce trajet. Le point de cheminement dans la liste peut être identifié par ses éléments 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) sont mis à jour lorsque Fleet Engine reçoit une demande de modification d'état du trajet. Le point de cheminement précédent est supprimé de la liste des points de cheminement restants du véhicule lorsque tripStatus(RPC | REST) passe d'un autre état à ENROUTE_TO_XXX. Autrement dit, lorsque l'état du trajet passe de ENROUTE_TO_PICKUP à ARRIVED_AT_PICKUP, le point de prise en charge reste dans la liste des points de cheminement restants du véhicule. Toutefois, lorsque l'état du trajet est défini sur ENROUTE_TO_INTERMEDIATE_DESTINATION ou ENROUTE_TO_DROPOFF, son point de prise en charge est supprimé du chemin restant du véhicule.

Il en va de même pour ARRIVED_AT_INTERMEDIATE_DESTINATION et ENROUTE_TO_INTERMDEDIATE_DESTINATION. Lorsque la valeur est ARRIVED_AT_INTERMEDIATE_DESTINATION, la destination intermédiaire actuelle n'est pas supprimée de la liste des points de cheminement restants du véhicule tant que le véhicule n'a pas indiqué qu'il se dirige vers le point de cheminement suivant.

Lorsque l'état du trajet est défini sur COMPLETED, aucun point de cheminement de ce trajet ne figure 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 mise en correspondance avec les véhicules du parc. Utilisez le point de terminaison CreateTrip avec CreateTripRequest pour créer un trajet.

Les attributs suivants sont obligatoires pour créer un trajet:

• parent : spécifiez une chaîne incluant l'ID de fournisseur créé lors de la création du projet Google Cloud.
• 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 représentant si le trajet peut inclure d'autres usagers d'un point de départ et d'une destination différents dans le même véhicule (SHARED) ou d'un seul groupe (EXCLUSIVE).
  • pickup_point : valeur TerminalLocation représentant le point de départ du trajet. Consultez la documentation de référence sur RPC ou la documentation de référence sur REST.

Lorsque vous créez un voyage, vous pouvez fournir les éléments number_of_passengers, dropoff_point et vehicle_id. Bien que ces champs ne soient pas obligatoires, ils sont conservés si vous les fournissez. Tous les autres champs "Trip" sont ignorés. Par exemple, tous les trajets commencent par un trip_status de NEW, même si vous transmettez un trip_status de CANCELED dans la requête de création.

Remarque :L'utilisation de CreateTrip nécessite les identifiants du compte privilégié mentionné dans la configuration du projet Cloud.

Exemple

L'exemple suivant crée un trajet vers le Grand Indonesia East Mall. Le trajet est exclusif pour deux passagers. Le provider_id de Trip doit être identique à l'ID du projet. Dans l'exemple, le fournisseur de services de VTC a créé le projet Google Cloud project-id. Ce projet doit disposer des 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

Consultez la documentation de référence sur providers.trips.create.

Java

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

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

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

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

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

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'un appel 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 aboutit, les informations sur le Trip renvoyé sont également incluses.

PROCÉDURE: Mettre à jour un trajet

L'entité "Trip" contient des champs qui permettent le suivi par le service et permettent de signaler la progression du trajet par le SDK Driver et le SDK Consumer. Pour mettre à jour les propriétés, utilisez le message UpdateTripRequest. Les champs "Trip" sont alors mis à jour en fonction du field_mask de la requête. Consultez UpdateTripRequest.

Remarque :L'utilisation de UpdateTripRequest pour mettre à jour le trip_status ou le vehicle_id d'un trajet nécessite les identifiants du compte privilégié du fournisseur.

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, soit après avoir mis en correspondance le véhicule avec un trajet.
• 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
• Heure d'arrivée prévue
• 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'un appel 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, des informations sur le Trip renvoyé sont également incluses.

PROCÉDURE: Rechercher des trajets

Fleet Engine permet de rechercher des trajets. Comme indiqué précédemment, un trajet est automatiquement supprimé au bout de sept jours. SearchTrips n'affiche donc pas 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 le SearchTripsRequest, vehicle_id est défini sur le véhicule en question, et active_trips_only doit être défini sur true.

• Rapprochement du fournisseur et de l'état Fleet Engine : le fournisseur peut utiliser SearchTrips pour s'assurer que l'état de son trajet et celui de Fleet Engine correspondent. Cela est particulièrement important pour TripStatus. Si l'état d'un trajet attribué à un véhicule n'est pas correctement défini sur COMPLETE ou CANCELED, le véhicule n'est pas inclus dans SearchVehicles.

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 les trajets qui ne sont ni TERMINÉS, ni ANNULÉS, et qui n'ont pas été mis à jour depuis plus d'une heure. Le fournisseur doit examiner ces trajets pour s'assurer que leur état dans Fleet Engine est correctement mis à jour.

Dépannage

Dans le cas d'une erreur DEADLINE_EXCEEDED, l'état de Fleet Engine est inconnu. Le fournisseur doit appeler à nouveau CreateTrip, ce qui renvoie un code 201 (CREATED) ou 409 (CONFLICT). Dans ce dernier cas, la requête précédente a abouti avant DEADLINE_EXCEEDED. Consultez les guides de l'API Consumer pour en savoir plus 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 spécifier l'ordre de tous les points de cheminement non transmis pour tous les trajets attribués au véhicule dans ce trajet partagé via Trip.vehicle_waypoints lorsque vous attribuez le vehicle_id à un trajet partagé (dans une requête CreateTrip ou UpdateTrip). Reportez-vous à vehicle_waypoints pour RPC ou à vehicleWaypoints pour REST.

Remarque :Trip.vehicle_waypoints doit contenir tous les points de cheminement restants de tous les trajets attribués au véhicule, mais pas de points de cheminement supplémentaires. Ces points de cheminement doivent être ordonnés de sorte que, pour un trajet donné, le point de prise en charge se trouve avant les destinations intermédiaires, et toutes les destinations intermédiaires soient situées avant le point de dépose. Les points de cheminement du trajet EXCLUSIVE ne doivent pas entrelacer les autres trajets.

Compatibilité avec plusieurs destinations

Identifier une destination intermédiaire

Les champs intermediateDestinations et intermediateDestinationIndex dans Trip (RPC | REST) sont combinés pour être utilisés pour indiquer la destination.

Mettre à jour la destination intermédiaire

Vous pouvez mettre à jour les destinations intermédiaires via UpdateTrip. Lorsque vous mettez à jour des destinations intermédiaires, vous devez fournir une liste complète des destinations intermédiaires, y compris celles qui ont été visitées, et pas seulement celle que vous venez d'ajouter ou de modifier. Lorsque intermediateDestinationIndex pointe vers un indice après la position de la destination intermédiaire nouvellement ajoutée/modifiée, la destination intermédiaire nouvelle/mise à jour n'est pas ajoutée au waypoints du véhicule ni au remainingWaypoints du trajet. La raison est que toutes les destinations intermédiaires antérieures à intermediateDestinationIndex sont traitées comme déjà visitées.

Modifications de l'état des trajets

Le champ intermediateDestinationsVersion dans (RPC | REST) est obligatoire dans la requête de mise à jour de l'état du trajet envoyée à Fleet Engine pour indiquer qu'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 traverse. Lorsque tripStatus correspond à ARRIVED_AT_INTERMEDIATE_DESTINATION, un nombre compris entre [0..N-1] indique la destination intermédiaire à laquelle se trouve le véhicule.

Exemple

L'exemple de code suivant montre comment mettre à jour l'état d'un trajet pour qu'il mène à sa première destination intermédiaire, en supposant que vous avez créé un trajet à plusieurs destinations et que celui-ci ait 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 projet Google Cloud client. Pub/Sub n'est pas activé par défaut pour Fleet Engine dans votre projet Google Cloud. Veuillez déposer une demande d'assistance ou contacter votre ingénieur client pour activer Pub/Sub.

Remarque :Pub/Sub ne garantit pas l'ordre des messages.

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 même projet Cloud qui appelle les API Fleet Engine.

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 ajoutez 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 [e-mail] 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 sous deux formats de données différents : protobuf et json. Le format de données de chaque notification est indiqué dans les 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

• Véhicule
• FieldMask

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