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 zuweisen, um sie auszuführen. Es wird davon ausgegangen, dass Sie die Fleet Engine eingerichtet, Fahrzeuge erstellt, eine funktionierende Fahrer-App und optional eine Verbraucher-App haben. Außerdem sollten Sie mit den verschiedenen Fahrtenszenarien für On-Demand-Fahrten vertraut sein. Weitere Informationen finden Sie in den folgenden Leitfäden:

• Fleet Engine einrichten
• Fahrzeug erstellen
• Fahrtszenarien in der Übersicht On-Demand-Fahrten

Grundlagen der Erstellung von Reisen

In diesem Abschnitt werden die Anfragedetails beschrieben, die zum Erstellen einer Fahrt in Fleet Engine erforderlich sind. Sie stellen eine Erstellungsanfrage entweder über gRPC oder REST.

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

Hinweis: Für die Verwendung von CreateTrip() sind die Anmeldedaten für das privilegierte Konto erforderlich, das unter Fleet Engine: Dienstkontorollen erwähnt wird.

Fahrtfelder

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

Felder für Fahrten

Name	Erforderlich?	Beschreibung
parent	Ja	Ein String, der die Projekt-ID enthält. Diese ID muss mit der ID übereinstimmen, die in Ihrer gesamten Fleet Engine-Integration verwendet wird, und dieselben Dienstkontorollen haben.
trip_id	Ja	Ein von Ihnen erstellter String, der diese Fahrt eindeutig identifiziert. Für Fahrt-IDs gelten bestimmte Einschränkungen, die in der Referenz angegeben sind.
trip_type	Ja	Legen Sie für TripType die folgenden Werte für den von Ihnen erstellten Reisetyp fest: Einzelnes Ziel: Legen Sie dafür SHARED oder EXCLUSIVE fest. Mehrere Ziele: Legen Sie EXCLUSIVE fest. Back-to-back: Legen Sie EXCLUSIVE fest. Gemeinsames Pooling: Auf SHARED festgelegt.
pickup_point	Ja	Der Startpunkt der Fahrt.
Zwischenziele	Ja	Nur Fahrten mit mehreren Zielen: Die Liste der Zwischenziele, die der Fahrer zwischen Abholung und Absetzen 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 mehreren Fahrgästen: In diesem Feld können die Wegpunkte mehrerer Fahrten verschachtelt werden. Sie enthält alle verbleibenden Wegpunkte für das zugewiesene Fahrzeug sowie die Wegpunkte für die Abholung und den Zielort für diese Fahrt. Sie können dieses Feld festlegen, indem Sie CreateTrip oder UpdateTrip aufrufen. Sie können Fahrzeugwegpunkte auch über das Feld waypoints mit einem Aufruf von UpdateVehicle aktualisieren. Der Dienst gibt diese Informationen bei GetTrip-Aufrufen aus Datenschutzgründen nicht zurück.
number_of_passengers	Nein	Die Anzahl der Fahrgäste auf der Fahrt.
dropoff_point	Nein	Das Ziel der Fahrt.
vehicle_id	Nein	Die ID des Fahrzeugs, das der Fahrt zugewiesen ist.

Beispiel: Fahrt mit mehreren Zielen erstellen

Im Folgenden wird gezeigt, wie Sie eine exklusive Fahrt mit mehreren Zielen erstellen, die einen Abholpunkt, einen Absetzpunkt 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;
}

Experimentell: Als experimentelles Feature unterstützt das Feld TerminalLocation (gRPC oder REST) jetzt die Verwendung von place (gRPC oder REST), entweder zusätzlich zu oder anstelle von LatLng.

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 kein Ziel oder keine Zwischenziele angegeben haben, können Sie das jetzt nachholen.

Hinweis: Wenn Sie intermediate_destinations für eine Fahrt festlegen oder aktualisieren, füllt die Fleet Engine die intermediate_destinations_version in der erstellten Fahrtentität aus. Du musst dieses Feld in deinem System im Cache speichern und den UpdateTripRequest übergeben, wenn du später den intermediate_destination_index aktualisierst. So bleiben die Zwischenziele zwischen Ihrem Fahrer-Client und Fleet Engine synchronisiert.

Beispiel für eine Fahrtaktualisierung

Im folgenden Beispiel 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;
}

Experimentell: Als experimentelles Feature unterstützt das Feld TerminalLocation (gRPC oder REST) jetzt die Verwendung von place (gRPC oder REST), entweder zusätzlich zu oder anstelle von LatLng.

Fahrtstatus für Fahrten mit mehreren Zielen verwalten

Sie geben den Status einer Fahrt mit einem der TripStatus-Aufzählungswerte 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 Fahrtstatus beginnt immer mit dem Wert NEW und endet entweder mit dem Wert COMPLETE oder CANCELED.

Bei einer Fahrt mit mehreren Zielen müssen Sie zusätzlich zur Aktualisierung des Fahrtstatus wie bei einer Fahrt mit einem Ziel auch jedes Mal, wenn Ihr Fahrzeug ein Zwischenziel erreicht, Folgendes aktualisieren:

• intermediateDestinationIndex
• intermediateDestinationsVersion

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

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

Hinweis: Die Fahrt sollte für jedes Zwischenziel einmal ENROUTE_TO_INTERMEDIATE_DESTINATION und ARRIVED_AT_INTERMEDIATE_DESTINATION durchlaufen.

Beispiel für eine Fahrt mit Zwischenzielen

Im Folgenden wird gezeigt, wie Sie eine Fahrt mit mehreren Zielen erstellen, bei der der 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

• Aufeinanderfolgende Fahrten erstellen
• Driver SDK einrichten