Tworzenie podróży obejmujących wiele miejsc docelowych

Z tego dokumentu dowiesz się, jak utworzyć podróż z wieloma miejscami docelowymi, ustawić prawidłowe pola i przypisać ją do pojazdu. Zakładamy, że masz skonfigurowaną usługę Fleet Engine, utworzone pojazdy, działającą aplikację kierowcy i opcjonalnie aplikację użytkownika. Powinieneś też znać różne scenariusze podróży dostępne w przypadku podróży na żądanie. Więcej informacji znajdziesz w tych powiązanych przewodnikach:

Podstawy tworzenia podróży

W tej sekcji opisujemy szczegóły żądania niezbędne do utworzenia podróży w Fleet Engine. Żądanie utworzenia wysyłasz za pomocą gRPC lub REST.

  • Metoda CreateTrip(): gRPC lub REST
  • Wiadomość CreateTripRequest: gRPC tylko

Pola podróży

Aby utworzyć podróż w Fleet Engine, użyj tych pól. Możesz używać różnych pól w przypadku różnych rodzajów podróży: z 1 lub kilkoma miejscami docelowymi, bezpośrednich lub wspólnych. Pola opcjonalne możesz podać podczas tworzenia podróży lub ustawić je później podczas aktualizowania podróży.

Pola podróży
Nazwa Wymagany? Opis
parent Tak Ciąg znaków zawierający identyfikator projektu. Ten identyfikator musi być taki sam w całej integracji z Fleet Engine i musi mieć te same role konta usługi.
trip_id Tak Ciąg znaków, który tworzysz i który jednoznacznie identyfikuje tę podróż. Identyfikatory podróży podlegają pewnym ograniczeniom, które są opisane w dokumentacji.
trip_type Tak Ustaw TripType na te wartości w zależności od tworzonego typu podróży:
  • 1 miejsce docelowe: ustaw na SHARED lub EXCLUSIVE.
  • Wiele miejsc docelowych: ustaw na EXCLUSIVE.
  • Bezpośrednia: ustaw na EXCLUSIVE.
  • Wspólna: ustaw na SHARED.
pickup_point Tak Punkt początkowy podróży.
Miejsca docelowe pośrednie Tak

Tylko podróże z wieloma miejscami docelowymi: lista miejsc docelowych pośrednich, do których kierowca jedzie między miejscem odbioru a miejscem docelowym. Podobnie jak w przypadku dropoff_point, to pole można ustawić później, wywołując UpdateTrip, ale podróż z wieloma miejscami docelowymi z definicji zawiera miejsca docelowe pośrednie.
vehicle_waypoints Tak

Tylko podróże wspólne: to pole obsługuje przeplatanie punktów na trasie z wielu podróży. Zawiera wszystkie pozostałe punkty na trasie przypisanego pojazdu, a także punkty odbioru i docelowe tej podróży. To pole możesz ustawić wywołując CreateTrip lub UpdateTrip. Punkty na trasie pojazdu możesz też zaktualizować za pomocą pola waypoints, wywołując UpdateVehicle. Ze względu na ochronę prywatności usługa nie zwraca tych informacji w przypadku wywołań GetTrip.
number_of_passengers Nie Liczba pasażerów w podróży.
dropoff_point Nie Miejsce docelowe podróży.
vehicle_id Nie Identyfikator pojazdu przypisanego do podróży.

Przykład: tworzenie podróży z wieloma miejscami docelowymi

Poniżej pokazujemy, jak utworzyć podróż z wieloma miejscami docelowymi, która ma punkt odbioru, miejsce docelowe i 1 miejsce docelowe pośrednie.

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

Aktualizowanie podróży z wieloma miejscami docelowymi

Musisz skonfigurować podróż z identyfikatorem pojazdu, aby Fleet Engine mógł śledzić pojazd na trasie. Więcej informacji o aktualizowaniu podróży znajdziesz w artykule Aktualizowanie podróży i zarządzanie ich stanem.

Jeśli podczas tworzenia podróży nie określisz miejsca docelowego ani miejsc docelowych pośrednich, możesz to zrobić w tym momencie.

Przykład aktualizacji podróży

Poniżej pokazujemy, jak zaktualizować podróż, aby dodać listę miejsc docelowych pośrednich i ustawić identyfikator pojazdu.

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

Zarządzanie stanem podróży z wieloma miejscami docelowymi

Stan podróży określasz za pomocą jednej z TripStatus wartości wyliczenia. Gdy stan podróży się zmieni, np. z ENROUTE_TO_PICKUP na ARRIVED_AT_PICKUP, musisz zaktualizować stan podróży w Fleet Engine. Stan podróży zawsze zaczyna się od wartości NEW i kończy wartością COMPLETE lub CANCELED.

W przypadku podróży z wieloma miejscami docelowymi oprócz aktualizowania stanu podróży tak jak w przypadku podróży z 1 miejscem docelowym musisz też aktualizować te elementy za każdym razem, gdy pojazd dotrze do miejsca docelowego pośredniego:

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

Aby to zrobić, użyj tych wartości z TripStatus wyliczenia.

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

Przykład podróży z miejscami docelowymi pośrednimi

Poniżej pokazujemy, jak utworzyć podróż z wieloma miejscami docelowymi, która minęła punkt odbioru i jest w drodze do pierwszego miejsca docelowego pośredniego.

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

Co dalej?