Créer des voyages de pooling partagés

Ce document explique comment créer un trajet partagé, définir les champs appropriés et l'attribuer à un véhicule pour l'effectuer. Il suppose que vous avez configuré Fleet Engine, créé des véhicules, que vous disposez d'une application chauffeur fonctionnelle et, éventuellement, d'une application consommateur. Vous devez également connaître les différents scénarios de trajet disponibles pour les trajets à la demande. Pour en savoir plus, consultez les guides associés suivants :

Principes de base de la création de trajets

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 et 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 : trajets à une ou plusieurs destinations, trajets consécutifs ou trajets partagés. Vous pouvez fournir les champs facultatifs lorsque vous créez le trajet ou les définir ultérieurement lorsque vous le mettez à jour.

Champs de trajet
Nom Obligatoire ? Description
parent Oui Chaîne incluant l'ID du projet. Cet ID doit être le même que celui utilisé dans l'ensemble de votre intégration Fleet Engine, avec les mêmes rôles de compte de service.
trip_id Oui Chaîne que vous créez et qui identifie de manière unique ce trajet. Les ID de trajet sont soumis à certaines restrictions, comme indiqué dans la documentation de référence.
trip_type Oui Définissez TripType sur les valeurs suivantes pour le type de trajet que vous créez :
  • Destination unique : définissez sur SHARED ou EXCLUSIVE.
  • Plusieurs destinations : définissez sur EXCLUSIVE.
  • Trajets consécutifs : définissez sur EXCLUSIVE.
  • Trajet partagé : définissez sur SHARED.
pickup_point Oui Point de départ du trajet.
Destinations intermédiaires Oui

Trajets à plusieurs destinations uniquement : liste des destinations intermédiaires que le chauffeur visite entre le point de départ et le point d'arrivée. Comme pour dropoff_point, ce champ peut également être défini ultérieurement en appelant UpdateTrip, mais un trajet à plusieurs destinations contient par définition des destinations intermédiaires.
vehicle_waypoints Oui

Trajets partagés 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 les points de cheminement de départ et d'arrivée pour ce trajet. Vous pouvez définir ce champ en appelant CreateTrip ou UpdateTrip. Vous pouvez également mettre à jour les points de cheminement du véhicule via le champ waypoints en appelant UpdateVehicle. Le service ne renvoie pas ces informations lors des appels GetTrip pour des raisons de confidentialité.
number_of_passengers Non Nombre de passagers lors du trajet.
dropoff_point Non Destination du trajet.
vehicle_id Non ID du véhicule attribué au trajet.

Exemple : Créer un trajet partagé

L'exemple d'intégration de backend suivant montre comment créer un trajet et l'attribuer à un véhicule en tant que trajet partagé.

// Vehicle with VEHICLE_ID ID is already created and it is assigned Trip A.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "shared-trip-A";
static final String VEHICLE_ID = "your-vehicle-id";
static final String TRIP_A_ID = "trip-a-id";
static final String TRIP_B_ID = "trip-b-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;

LatLng tripBPickup =
    LatLng.newBuilder().setLatitude(-12.12314).setLongitude(88.142123).build();
LatLng tripBDropoff =
    LatLng.newBuilder().setLatitude(-14.12314).setLongitude(90.142123).build();

TerminalLocation tripBPickupTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBPickup).build();
TerminalLocation tripBDropoffTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBDropoff).build();

// TripA already exists and it's assigned to a vehicle with VEHICLE_ID ID.
Trip tripB = Trip.newBuilder()
    .setTripType(TripType.SHARED)
    .setVehicleId(VEHICLE_ID)
    .setPickupPoint(tripBPickupTerminalLocation)
    .setDropoffPoint(tripBDropoffTerminalLocation)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripBPickupTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripBDropoffTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// Create Trip request
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_B_ID)
    .setTrip(tripB)
    .build();

try {
  // createdTrip.remainingWaypoints will contain shared-pool waypoints.
  // [tripB.pickup, tripA.dropoff, tripB.dropoff]
  Trip createdTrip = tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Mettre à jour les trajets partagés

Tout trajet créé dans Fleet Engine doit être attribué à un véhicule pour que Fleet Engine puisse calculer les ETA du trajet et le suivre. Vous pouvez le faire lors de la création du trajet ou ultérieurement lorsque vous le mettez à jour.

Pour les trajets partagés, vous devez spécifier un ordre pour les points de cheminement non visités dans la collection de points de cheminement du véhicule du trajet (Trip.vehicle_waypoints). Fleet Engine utilise cette liste pour mettre à jour automatiquement les points de cheminement du trajet pour tous les trajets du pool partagé.

Prenons l'exemple de deux trajets partagés, le trajet A et le trajet B :

  • Le trajet A est en cours vers son point d'arrivée.
  • Le trajet B est ensuite ajouté au même véhicule.

Dans une UpdateTripRequest pour le trajet B, vous définissez le vehicleId, ainsi que Trip.vehicle_waypoints sur l'ordre optimal des points de cheminement : point de départ B → point d'arrivée A → point d'arrivée B.

  • L'appel de getVehicle() renvoie remainingWaypoints qui contient :
    point de départ B → point d'arrivée A → point d'arrivée B.
  • `getTrip()` ou le rappel onTripRemainingWaypointsUpdated pour le trajet A renvoie remainingWaypoints qui contient :
    point de départ B → point d'arrivée A.    getTrip()
  • getTrip() ou le onTripRemainingWaypointsUpdated rappel pour le trajet B renvoie remainingWaypoints qui contient :
    point de départ B → point d'arrivée A → point d'arrivée B.

Exemple

L'exemple d'intégration de backend suivant montre comment mettre à jour un trajet avec l'ID du véhicule et les points de cheminement pour deux trajets partagés.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_A_ID = "share-trip-A";
static final String TRIP_B_ID = "share-trip-B";
static final String VEHICLE_ID = "Vehicle";

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

// Get Trip A and Trip B objects from either the Fleet Engine or storage.
Trip tripA = …;
Trip tripB = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId(VEHICLE_ID)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getPickupPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getDropoffPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

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

// Error handling. If Fleet Engine has both a trip and vehicle with the IDs,
// and if the credentials validate, and if the given vehicle_waypoints list
// is valid, 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:          // Either the trip or vehicle does not exist.
      break;
    case PERMISSION_DENIED:
      break;
    case INVALID_REQUEST:    // vehicle_waypoints is invalid.
      break;
  }
  return;
}

Étape suivante