Modifier des trajets et gérer leur état

Ce document explique comment mettre à jour un trajet et gérer son état. Pour ce faire, vous devez utiliser un masque de champ pour définir les champs pertinents d'un trajet. Il suppose que vous avez configuré Fleet Engine comme décrit sur ce site et que vous travaillez avec un véhicule attribué à un trajet.

Principes de base des informations sur les trajets

Votre système utilise Fleet Engine pour mettre à jour un trajet dans les situations suivantes :

  • Lorsque vous attribuez un véhicule à un trajet après sa création.
  • Lorsque l'état du trajet change (par exemple, lorsque le véhicule passe par des points de cheminement).
  • Lorsque vous modifiez des champs du trajet, comme le nombre de passagers et le point de dépose.

Pour mettre à jour un trajet, envoyez une requête à l'aide de gRPC ou de REST.

  • Méthode UpdateTrip() : gRPC ou REST
  • Message UpdateTripRequest : gRPC uniquement

Utilisez les identifiants appropriés pour le compte de service de votre projet, comme décrit dans Fleet Engine : rôles des comptes de service.

Mettre à jour les champs de trajet

Vous pouvez mettre à jour n'importe quel champ de trajet décrit dans Champs de trajet dans Créer un trajet à une seule destination. Par exemple, après avoir créé un trajet, il est courant de trouver d'abord un véhicule, puis de mettre à jour le champ vehicle_id du trajet pour l'associer au véhicule qui effectuera le trajet.

Utiliser des masques de champ

Les masques de champ permettent aux appelants d'API de lister les champs qu'une requête doit obtenir ou mettre à jour. L'utilisation d'un FieldMask permet d'éviter les opérations inutiles et d'améliorer les performances. Fleet Engine utilise des masques de champ pour mettre à jour les champs de toutes les ressources.

Mettre à jour le trajet avec l'ID du véhicule

Vous devez configurer un trajet avec un ID de véhicule pour que Fleet Engine puisse suivre le véhicule sur son itinéraire. L'exemple de code suivant montre comment mettre à jour le trajet avec un ID de véhicule.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()      // No need for the header.
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(FieldMask.newBuilder().addPaths("vehicle_id"))
        .build();

// Error handling.
// If the Fleet Engine has both a trip and vehicle with IDs, and if the
// credentials validate, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:                    // Neither the trip nor vehicle exist.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Gérer l'état des trajets

Vous spécifiez l'état d'un trajet à l'aide de l'une des valeurs d'énumération TripStatus. Lorsque l'état d'un trajet change (par exemple, de ENROUTE_TO_PICKUP à ARRIVED_AT_PICKUP), vous devez mettre à jour l'état du trajet dans Fleet Engine. Le cycle de vie d'un trajet commence toujours par une valeur d'état NEW et se termine par une valeur COMPLETE ou CANCELED.

Exemple de mise à jour de trajet

L'exemple suivant montre comment mettre à jour l'état d'un trajet consécutif dans Fleet Engine.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to be updated.
Trip trip = Trip.newBuilder()
    .setTripStatus(TripStatus.ARRIVED_AT_PICKUP)
    .build();

// Trip update request
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder().addPaths("trip_status"))
    .build();

// Error handling.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Vous trouverez d'autres exemples de mise à jour des trajets dans la section Autres types de trajets.

Gérer les erreurs de trajet

Lorsque vous mettez à jour ou recherchez des trajets existants, vous pouvez rencontrer une erreur DEADLINE_EXCEEDED, auquel cas l'état de Fleet Engine est inconnu. Pour examiner ce problème, appelez d'abord CreateTrip à nouveau en utilisant le même ID de trajet que celui que vous essayez de mettre à jour ou de surveiller. Cette opération devrait renvoyer un code 201 (CREATED) ou 409 (CONFLICT). Dans ce dernier cas, la requête précédente a abouti avant DEADLINE_EXCEEDED.

Consultez la liste des erreurs réseau dans le SDK Consumer pour Android ou iOS.

Étape suivante