Crea corse con più destinazioni

Questo documento descrive come creare un viaggio con più destinazioni, impostare i campi corretti e assegnarlo a un veicolo da completare. Presuppone che tu abbia configurato Fleet Engine, creato veicoli, che tu abbia un'app per i conducenti funzionante e, facoltativamente, un'app per i consumatori. Devi anche conoscere i vari scenari di viaggio disponibili per i viaggi on demand. Per questo, consulta le seguenti guide correlate:

Nozioni di base sulla creazione del viaggio

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

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

Campi viaggio

Utilizza i seguenti campi per creare un viaggio in Fleet Engine. Puoi utilizzare campi diversi per i diversi tipi di viaggi: con una o più destinazioni, consecutivi o in pool condiviso. Puoi fornire i campi facoltativi quando crei il viaggio oppure puoi impostarli in un secondo momento quando aggiorni il viaggio.

Campi del viaggio
Nome Obbligatorio? Descrizione
parent Sì Una stringa che include l'ID progetto. Questo ID deve essere lo stesso utilizzato in tutta l'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 questo viaggio. Gli ID viaggio hanno determinate limitazioni, come indicato nel riferimento.
trip_type Sì Imposta TripType sui seguenti valori per il tipo di viaggio che stai creando:
  • Singola destinazione: imposta su SHARED o EXCLUSIVE.
  • Più destinazioni: impostato su EXCLUSIVE.
  • Back-to-back: imposta su EXCLUSIVE.
  • Pooling condiviso: impostato su SHARED.
pickup_point Sì Il punto di partenza del viaggio.
Destinazioni intermedie Sì

Solo viaggi con più destinazioni: l'elenco delle destinazioni intermedie che l'autista visita tra il punto di partenza e quello di arrivo. Come per dropoff_point, anche questo campo può essere impostato in un secondo momento chiamando UpdateTrip, ma un viaggio con più destinazioni per definizione contiene destinazioni intermedie.
vehicle_waypoints Sì

Solo viaggi in condivisione: questo campo supporta l'interleaving dei waypoint di più viaggi. Contiene tutti i waypoint rimanenti per il veicolo assegnato, nonché i waypoint di ritiro e riconsegna per questo viaggio. Puoi impostare questo campo chiamando il numero 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 sulle chiamate GetTrip per motivi di privacy.
number_of_passengers No Il numero di passeggeri del viaggio.
dropoff_point No La destinazione del viaggio.
vehicle_id No L'ID del veicolo assegnato al viaggio.

Esempio: creare un viaggio con più destinazioni

Di seguito viene illustrato come creare un viaggio esclusivo con più destinazioni che include un punto di partenza, un punto di arrivo e una destinazione intermedia.

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

Aggiornare un viaggio con più destinazioni

Devi configurare la corsa con un ID veicolo in modo che Fleet Engine possa monitorare il veicolo lungo il percorso. Per informazioni dettagliate sull'aggiornamento di un viaggio, vedi Aggiornare i viaggi e gestirne lo stato.

Se non specifichi una destinazione intermedia o di arrivo quando crei il viaggio, puoi sempre farlo a questo punto.

Esempio di aggiornamento della corsa

Di seguito viene illustrato come aggiornare un viaggio per aggiungere un elenco di destinazioni intermedie e impostare un ID veicolo.

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

Gestire lo stato del viaggio per i viaggi con più destinazioni

Specifichi lo stato di un viaggio utilizzando uno dei valori di enumerazione TripStatus. Quando lo stato di un viaggio cambia, ad esempio da ENROUTE_TO_PICKUP a ARRIVED_AT_PICKUP, devi aggiornarlo in Fleet Engine. Lo stato del viaggio inizia sempre con un valore di NEW e termina con un valore di COMPLETE o CANCELED.

Per un viaggio con più destinazioni, oltre ad aggiornare lo stato del viaggio come faresti per un viaggio con una sola destinazione, devi aggiornare anche quanto segue ogni volta che il veicolo raggiunge una destinazione intermedia:

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

Per farlo, utilizza i seguenti valori dell'enumerazione TripStatus.

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

Esempio di viaggio con destinazioni intermedie

Di seguito viene mostrato come creare un viaggio con più destinazioni che ha superato il punto di ritiro ed è ora in viaggio verso la prima destinazione intermedia.

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

Passaggi successivi