Modifier des trajets et gérer leur état

Ce document explique comment mettre à jour un trajet et gérer son état, ce qui implique d'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 mises à jour de trajets

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

  • Lors de l'attribution d'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 mettez à jour les champs du trajet, tels que 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 de compte de service.

Mettre à jour les champs du trajet

Vous pouvez mettre à jour n'importe quel champ de trajet décrit dans la section Champs de trajet de la page Créer un trajet à destination unique. Par exemple, après avoir créé un trajet, il est courant de rechercher 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 mettre à jour. L'utilisation d'un FieldMask évite les tâches inutiles et améliore 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 tout au long de 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 mettez à jour l'état du trajet dans Fleet Engine. Le cycle de vie du 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. Dans ce cas, l'état de Fleet Engine est inconnu. Pour examiner ce problème, commencez par appeler à nouveau CreateTrip en utilisant l'ID du trajet que vous essayez de mettre à jour ou de surveiller. Cette commande doit 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