Créer des trajets multidestinations

Ce document explique comment créer un trajet multidestination, définir les champs appropriés et l'attribuer à un véhicule pour qu'il soit effectué. Nous supposons que vous avez configuré Fleet Engine, que vous avez créé des véhicules, que vous disposez d'une application conducteur fonctionnelle et, éventuellement, d'une application client. Vous devez également connaître les différents scénarios de trajets disponibles pour les trajets à la demande. Consultez les guides associés suivants pour que:

Principes de base de la création de voyages

Cette section décrit les détails de la requête nécessaires pour créer un trajet dans Fleet Engine. Vous envoyez une requête de création à l'aide de gRPC ou de REST.

  • Méthode CreateTrip(): gRPC ou REST
  • Message CreateTripRequest : gRPC uniquement

Champs de trajet

Utilisez les champs suivants pour créer un trajet dans Fleet Engine. Vous pouvez utiliser différents champs pour les différents types de trajets : à destination unique ou multiple, en série ou en pool partagé. Vous pouvez fournir les champs facultatifs lorsque vous créez le trajet ou les définir plus tard lorsque vous le mettez à jour.

Champs de trajet
Nom Obligatoire ? Description
parent Oui Chaîne incluant l'ID du projet. Cet ID doit être identique à celui utilisé pour l'ensemble de l'intégration de Fleet Engine, avec les mêmes rôles de compte de service.
trip_id Oui Chaîne que vous créez pour identifier de manière unique ce trajet. Les ID de trajet comportent certaines restrictions, comme indiqué dans la référence.
trip_type Oui Définissez TripType sur les valeurs suivantes pour le type de voyage que vous créez:
  • Destination unique: définissez SHARED ou EXCLUSIVE.
  • Multi-destination (Multi-destination) : défini sur EXCLUSIVE.
  • Retour à dos: défini sur EXCLUSIVE.
  • Pooling partagé: définissez cette option sur SHARED.
pickup_point Oui Point de départ du trajet.
Destinations intermédiaires Oui

Trajets multidestination uniquement : liste des destinations intermédiaires que le conducteur visite entre le ramassage et le dépôt. Comme pour dropoff_point, ce champ peut également être défini ultérieurement en appelant UpdateTrip, mais un trajet multidestination contient par définition des destinations intermédiaires.
vehicle_waypoints Oui

Shared-pooling trips only (Trajets avec pooling partagé uniquement) : ce champ permet d'entrelacer les points de cheminement de plusieurs trajets. Il contient tous les points de cheminement restants pour le véhicule attribué, ainsi que comme points de cheminement de prise en charge et de dépose pour ce trajet. Vous pouvez définir ce champ en appelant CreateTrip ou UpdateTrip. Vous pouvez également modifiez les points de cheminement du véhicule dans le champ waypoints avec une à UpdateVehicle. Le service ne renvoie pas cette information lors des appels GetTrip. pour des raisons de confidentialité.
number_of_passengers Non Nombre de passagers du voyage.
dropoff_point Non Destination du trajet.
vehicle_id Non Identifiant du véhicule attribué au trajet.

Exemple : créer un trajet multidestination

Vous trouverez ci-dessous la procédure à suivre pour créer un trajet multidestination exclusif. qui comprend un point de prise en charge, un point de dépose et une destination intermédiaire.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip initial settings.
String parent = "providers/" + PROJECT_ID;

Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE)
    .setPickupPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.195139).setLongitude(106.820826)))
    .setNumberOfPassengers(1)
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.1275).setLongitude(106.6537)))
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .build();

// Create the Trip request.
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_ID)  // Trip ID assigned by the Provider server.
    .setTrip(trip)       // Initial state is NEW.
    .build();

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

Modifier un trajet multidestination

Vous devez configurer le trajet avec un ID de véhicule pour que le moteur de parc puisse suivre le véhicule tout au long de son trajet. Pour en savoir plus sur la mise à jour d'un trajet, consultez Mettre à jour les trajets et gérer leur état

Si vous ne spécifiez pas de destination de dépose ou de destination intermédiaire lorsque vous créer le trajet, vous pouvez toujours le faire à ce stade.

Exemple de mise à jour de trajet

L'exemple suivant montre comment mettre à jour un trajet pour ajouter une liste de destinations intermédiaires et définir un ID de véhicule.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

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

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(
        FieldMask.newBuilder()
            .addPaths("intermediate_destinations")
            .addPaths("vehicle_id")
            .build())
    .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 PERMISSION_DENIED:
      break;
  }
  return;
}

Gérer l'état des trajets multidestinations

Vous spécifiez l'état d'un trajet à l'aide de l'une des énumérations TripStatus. valeurs. 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. L'état du trajet commence toujours par une valeur de NEW et se termine par une valeur de COMPLETE ou CANCELED.

Pour un trajet multidestination, en plus de mettre à jour l'état du trajet comme vous le feriez pour un trajet à destination unique, vous devez également mettre à jour les éléments suivants chaque fois que votre véhicule atteint une destination intermédiaire :

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

Pour ce faire, utilisez les valeurs suivantes de l'énumération TripStatus.

  • ENROUTE_TO_PICKUP
  • ARRIVED_AT_PICKUP
  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETE

Exemple de trajet avec des destinations intermédiaires

L'exemple suivant montre comment créer un trajet multi-destination qui a passé son point de prise en charge et qui se dirige maintenant vers sa première destination intermédiaire.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

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

// Get the trip object from either the Fleet Engine or storage.
Trip trip = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Trip status cannot return to a previous state once it has passed.
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)

    // Enroute to the first intermediate destination.
    .setIntermediateDestinationIndex(0)

    // You must provide an intermediate_destinations_version to ensure that you
    // have the same intermediate destinations list as the Fleet Engine.
    .setIntermediateDestinationsVersion(
         trip.getIntermediateDestinationsVersion())
    .build();

// The 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:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // Either the trip status is invalid, or the
                               // intermediate_destinations_version doesn't
                               // match Fleet Engine's.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Étape suivante