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 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.

gcloud auth login

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.

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

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:

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, 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:

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 auprès de 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'identifiant du véhicule).

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

Une section de revendications JWT contient les champs suivants:

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 champ private_key_id de votre service fichier JSON du 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 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 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. 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:

1. Utiliser le SDK Driver – Android iOS est l'option la plus simple.
2. Utilisez un code personnalisé (utile si les lieux sont transmis via votre backend, ou si vous utilisez des appareils autres qu'Android ou iOS

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

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

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é.

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

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

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

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.

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

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é.

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.

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

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

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.

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

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

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.

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

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 à Tripdans 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, le vehicle_id est défini sur le véhicule en cours d'examen et active_trips_only doit être défini sur true.

• 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. Cela est particulièrement important pour TripStatus. Si l'état d'un trajet sur "Vehicle" n'est pas correctement défini sur COMPLETE ou CANCELED, le "Vehicle" n'est pas incluse 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 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 spécifier 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.

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

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

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