Crea corse con più destinazioni

Questo documento descrive come creare un percorso con più destinazioni, impostare i campi corretti e assegnarlo a un veicolo per l'esecuzione. 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:

• Configura Fleet Engine
• Crea un veicolo
• Scenari di percorso nella panoramica dei percorsi on demand

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

Nota: l'utilizzo di CreateTrip() richiede le credenziali per l'account con privilegi menzionato in Fleet Engine: ruoli dei service account.

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. Pooling condiviso: 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: 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 un viaggio con più destinazioni

Di seguito viene mostrato come creare una corsa esclusiva con più destinazioni che ha 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;
}

Sperimentale: come funzionalità sperimentale, il campo TerminalLocation (gRPC o REST) ora supporta l'utilizzo di place (gRPC o REST), insieme a LatLng o al suo posto.

Aggiorna un percorso con più destinazioni

Devi configurare la corsa con un ID veicolo in modo che Fleet Engine possa monitorare il veicolo lungo il suo percorso. Per maggiori dettagli sull'aggiornamento di una corsa, consulta Aggiorna le corse e gestisci il loro stato.

Se non specifichi una destinazione di arrivo o delle destinazioni intermedie quando crei la corsa, puoi sempre farlo in questo momento.

Nota: ogni volta che imposti o aggiorni intermediate_destinations in una corsa, Fleet Engine compila intermediate_destinations_version nell'entità della corsa creata. Devi memorizzare nella cache questo campo nel tuo sistema e passare il valore UpdateTripRequest quando aggiorni intermediate_destination_index in un secondo momento. In questo modo, le destinazioni intermedie vengono sincronizzate tra il client del conducente e Fleet Engine.

Esempio di aggiornamento di una corsa

Di seguito viene mostrato come aggiornare una corsa 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;
}

Sperimentale: come funzionalità sperimentale, il campo TerminalLocation (gRPC o REST) ora supporta l'utilizzo di place (gRPC o REST), insieme a LatLng o al suo posto.

Gestisci lo stato della corsa per le corse con più destinazioni

Puoi specificare lo stato di una corsa utilizzando uno dei valori di enumerazione TripStatus. Quando lo stato di una corsa cambia, ad esempio da ENROUTE_TO_PICKUP a ARRIVED_AT_PICKUP, devi aggiornare lo stato della corsa in Fleet Engine. Lo stato della corsa inizia sempre con un valore NEW e termina con un valore COMPLETE o CANCELED.

Per una corsa con più destinazioni, oltre ad aggiornare lo stato della corsa come faresti per una corsa con una sola destinazione, devi anche aggiornare 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

Nota: il percorso deve passare attraverso ENROUTE_TO_INTERMEDIATE_DESTINATION e ARRIVED_AT_INTERMEDIATE_DESTINATION una volta per ogni destinazione intermedia.

Esempio di percorso con destinazioni intermedie

Di seguito viene mostrato come creare una corsa con più destinazioni che ha superato il punto di partenza e 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

• Crea corse consecutive
• Configura l'SDK Driver