Reisen mit mehreren Zielen erstellen

In diesem Dokument wird beschrieben, wie Sie eine Fahrt mit mehreren Zielen erstellen, die richtigen Felder festlegen und sie einem Fahrzeug zur Ausführung zuweisen. Es wird davon ausgegangen, dass Sie Fleet Engine eingerichtet, Fahrzeuge erstellt und eine funktionierende Fahrer-App und optional eine Verbraucher-App haben. Außerdem sollten Sie mit den verschiedenen Szenarien für On-Demand-Fahrten vertraut sein. Weitere Informationen finden Sie in den folgenden zugehörigen Leitfäden:

Grundlagen der Reiseplanung

In diesem Abschnitt werden die für das Erstellen einer Fahrt in Fleet Engine erforderlichen Anfragedetails beschrieben. Sie senden eine Erstellungsanfrage entweder über gRPC oder REST.

  • CreateTrip()-Methode: gRPC oder REST
  • CreateTripRequest-Nachricht: Nur gRPC

Felder für Fahrten

Verwenden Sie die folgenden Felder, um eine Fahrt in Fleet Engine zu erstellen. Sie können für die verschiedenen Arten von Fahrten unterschiedliche Felder verwenden: Fahrten mit einem oder mehreren Zielen, aufeinanderfolgende Fahrten oder Fahrten mit Sammelpunkten. Sie können die optionalen Felder beim Erstellen der Fahrt angeben oder sie später beim Aktualisieren der Fahrt festlegen.

Fahrtfelder
Name Erforderlich? Beschreibung
parent Ja Ein String, der die Projekt-ID enthält. Diese ID muss in Ihrer gesamten Fleet Engine-Integration mit denselben Dienstkontorollen verwendet werden.
trip_id Ja Ein String, den Sie erstellen und der diese Fahrt eindeutig identifiziert. Für Fahrt-IDs gelten bestimmte Einschränkungen, die in der Referenz angegeben sind.
trip_type Ja Legen Sie TripType auf die folgenden Werte für den zu erstellenden Reisetyp fest:
  • Einzelnes Ziel: Legen Sie SHARED oder EXCLUSIVE fest.
  • Mehrere Ziele: Legen Sie EXCLUSIVE fest.
  • Back-to-back: Legen Sie EXCLUSIVE fest.
  • Gemeinsame Nutzung von Kontingenten: Legen Sie SHARED fest.
pickup_point Ja Der Ausgangspunkt der Reise.
Zwischenziele Ja

Nur Fahrten mit mehreren Zielen: Die Liste der Zwischenziele, die der Fahrer zwischen Abhol- und Zielort anfährt. Wie bei dropoff_point kann dieses Feld auch später durch Aufrufen von UpdateTrip festgelegt werden. Eine Fahrt mit mehreren Zielen enthält jedoch per Definition Zwischenziele.
vehicle_waypoints Ja

Nur Fahrten mit gemeinsamer Nutzung: In diesem Feld können die Wegpunkte mehrerer Fahrten verschachtelt werden. Sie enthält alle verbleibenden Wegpunkte für das zugewiesene Fahrzeug sowie die Abhol- und Absetzwegpunkte für diese Fahrt. Sie können dieses Feld festlegen, indem Sie CreateTrip oder UpdateTrip aufrufen. Sie können auch Fahrzeug-Wegpunkte über das Feld waypoints mit einem Aufruf von UpdateVehicle aktualisieren. Aus Datenschutzgründen werden diese Informationen bei GetTrip-Anrufen nicht zurückgegeben.
number_of_passengers Nein Die Anzahl der Passagiere auf der Reise.
dropoff_point Nein Das Ziel der Reise.
vehicle_id Nein Die ID des Fahrzeugs, das der Fahrt zugewiesen ist.

Beispiel: Reise mit mehreren Zielen erstellen

Im Folgenden wird gezeigt, wie Sie eine exklusive Reise mit mehreren Zielen erstellen, die einen Abholort, einen Zielort und ein Zwischenziel hat.

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

Fahrt mit mehreren Zielen aktualisieren

Sie müssen die Fahrt mit einer Fahrzeug-ID konfigurieren, damit die Fleet Engine das Fahrzeug auf seiner Route verfolgen kann. Weitere Informationen zum Aktualisieren einer Fahrt finden Sie unter Fahrten aktualisieren und ihren Status verwalten.

Wenn Sie beim Erstellen der Fahrt keine Abgabe- oder Zwischenziele angegeben haben, können Sie das jetzt nachholen.

Beispiel für eine Fahrtaktualisierung

Im Folgenden wird gezeigt, wie Sie eine Fahrt aktualisieren, um eine Liste von Zwischenzielen hinzuzufügen und eine Fahrzeug-ID festzulegen.

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

Status von Fahrten mit mehreren Zielen verwalten

Sie geben den Status einer Fahrt mit einem der Enumerationswerte TripStatus an. Wenn sich der Status einer Fahrt ändert, z. B. von ENROUTE_TO_PICKUP zu ARRIVED_AT_PICKUP, müssen Sie den Fahrtstatus in Fleet Engine aktualisieren. Der Status einer Reise beginnt immer mit dem Wert NEW und endet mit dem Wert COMPLETE oder CANCELED.

Bei einer Fahrt mit mehreren Zielen müssen Sie nicht nur den Fahrtstatus wie bei einer Fahrt mit einem Ziel aktualisieren, sondern auch Folgendes, wenn Ihr Fahrzeug ein Zwischenziel erreicht:

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

Verwenden Sie dazu die folgenden Werte aus der TripStatus-Aufzählung.

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

Beispiel für eine Route mit Zwischenzielen

Im Folgenden wird gezeigt, wie Sie eine Fahrt mit mehreren Zielen erstellen, deren Abholort bereits passiert wurde und die sich jetzt auf dem Weg zum ersten Zwischenziel befindet.

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

Nächste Schritte