Crea viaggi di pooling condivisi

Questo documento descrive come creare una corsa in car pooling condivisa, impostare i campi corretti e assegnarla a un veicolo per l'evasione. Si presume che tu abbia configurato Fleet Engine, creato i veicoli, un'app per i conducenti funzionante e, facoltativamente, un'app per utenti finali. Dovresti anche avere familiarità con i vari scenari di corsa disponibili per le corse on demand. Per farlo, consulta le seguenti guide correlate:

Nozioni di base sulla creazione di un viaggio

Questa sezione descrive i dettagli della richiesta necessari per creare un percorso in Fleet Engine. Puoi inviare una richiesta di creazione utilizzando gRPC e REST.

  • Metodo CreateTrip(): gRPC o REST
  • Messaggio CreateTripRequest: solo gRPC

Campi della corsa

Utilizza i seguenti campi per creare una corsa in Fleet Engine. Puoi utilizzare campi diversi per i diversi tipi di corse: con una o più destinazioni, consecutive o in car pooling. Puoi fornire i campi facoltativi quando crei la corsa o impostarli in un secondo momento quando la aggiorni.

Campi della corsa
Nome Obbligatorio? Descrizione
parent Sì Una stringa che include l'ID progetto. Questo ID deve essere lo stesso utilizzato nell'intera integrazione di Fleet Engine, con gli stessi ruoli dell'account di servizio.
trip_id Sì Una stringa creata da te che identifica in modo univoco questa corsa. Gli ID corsa presentano alcune limitazioni, come indicato nel riferimento.
trip_type Sì Imposta TripType sui seguenti valori per il tipo di corsa che stai creando:
  • Destinazione singola: imposta su SHARED o EXCLUSIVE.
  • Multi-destination: impostato su EXCLUSIVE.
  • Back-to-back: imposta su EXCLUSIVE.
  • Condivisione condivisa: Impostato su SHARED.
pickup_point Sì Il punto di partenza della corsa.
Destinazioni intermedie Sì

Solo per corse con più destinazioni: l'elenco delle destinazioni intermedie che il conducente visita tra il ritiro e la consegna. Come per dropoff_point, questo campo può essere impostato anche in un secondo momento chiamando UpdateTrip, ma una corsa con più destinazioni per definizione contiene destinazioni intermedie.
vehicle_waypoints Sì

Solo corse con car pooling condiviso: questo campo supporta l'interfoliazione dei waypoint di più corse. Contiene tutti i waypoint rimanenti per il veicolo assegnato, nonché i waypoint di partenza e arrivo per questa corsa. Puoi impostare questo campo chiamando CreateTrip o UpdateTrip. Puoi anche aggiornare i waypoint del veicolo tramite il campo waypoints con una chiamata a UpdateVehicle. Il servizio non restituisce queste informazioni nelle chiamate GetTrip per motivi di privacy.
number_of_passengers No Il numero di passeggeri della corsa.
dropoff_point No La destinazione del percorso.
vehicle_id No L'ID del veicolo assegnato alla corsa.

Esempio: crea una corsa in car pooling condivisa

L'esempio di integrazione del backend riportato di seguito mostra come creare una corsa e assegnarla a un veicolo come corsa in car pooling condiviso.

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

Aggiorna le corse in car pooling condivise

Qualsiasi percorso creato in Fleet Engine deve essere assegnato a un veicolo affinché Fleet Engine possa calcolare gli ETA del percorso e monitorarlo. Puoi farlo durante la creazione del viaggio o in un secondo momento, quando aggiorni il viaggio.

Per le corse in pool condiviso, devi specificare un ordine per i waypoint non visitati nella raccolta di waypoint del veicolo della corsa (Trip.vehicle_waypoints). Fleet Engine utilizza questo elenco per aggiornare automaticamente i waypoint della corsa per tutte le corse nel pool condiviso.

Ad esempio, considera due corse in pool condiviso, Corsa A e Corsa B:

  • La corsa A è in viaggio verso la località di arrivo.
  • La corsa B viene quindi aggiunta allo stesso veicolo.

In un UpdateTripRequest per la corsa B, imposti vehicleId e anche Trip.vehicle_waypoints sull'ordine ottimale dei waypoint: B Ritiro → A Consegna → B Consegna.

  • La chiamata a getVehicle() restituisce remainingWaypoints che contengono:
    Ritiro B → Consegna A → Consegna B.
  • getTrip() o il callback onTripRemainingWaypointsUpdated per la corsa A restituisce remainingWaypoints che contiene:
    B Partenza → A Arrivo.
  • getTrip() o il callback onTripRemainingWaypointsUpdated per la corsa B restituisce remainingWaypoints che contiene:
    B Ritiro → A Arrivo → B Arrivo.

Esempio

L'esempio di integrazione del backend riportato di seguito mostra come aggiornare una corsa con l'ID veicolo e i waypoint per due corse in pool condiviso.

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

Passaggi successivi