Tworzenie podróży obejmujących wiele miejsc docelowych

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

Podstawowe informacje o tworzeniu wycieczek

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

  • Metoda CreateTrip(): gRPC lub REST
  • CreateTripRequest message: gRPC only

Pola przejazdu

Aby utworzyć przejazd w Fleet Engine, użyj tych pól. W przypadku różnych rodzajów przejazdów możesz używać różnych pól: przejazdów do jednego lub wielu miejsc docelowych, przejazdów bezpośrednich lub przejazdów wspólnych. Pola opcjonalne możesz podać podczas tworzenia podróży lub ustawić je później, gdy będziesz aktualizować podróż.

Pola przejazdu
Nazwa Wymagany? Opis
parent Tak Ciąg tekstowy zawierający identyfikator projektu. Ten identyfikator musi być taki sam jak identyfikator używany w całej integracji z Fleet Engine, z tymi samymi rolami konta usługi.
trip_id Tak Utworzony przez Ciebie ciąg znaków, który w niepowtarzalny sposób identyfikuje tę podróż. Identyfikatory przejazdów podlegają pewnym ograniczeniom, o których mowa w dokumentacji.
trip_type Tak Ustaw wartość TripType na jedną z tych wartości w przypadku tworzonego typu podróży:
  • Pojedyncze miejsce docelowe: ustaw na SHARED lub EXCLUSIVE.
  • Wiele miejsc docelowych: ustaw na EXCLUSIVE.
  • Jeden po drugim: ustaw na EXCLUSIVE.
  • Pula współdzielona: ustaw na SHARED.
pickup_point Tak Punkt początkowy podróży.
Miejsca docelowe pośrednie Tak

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

Tylko przejazdy współdzielone: to pole obsługuje przeplatanie punktów pośrednich z wielu przejazdów. Zawiera wszystkie pozostałe punkty na trasie przypisanego pojazdu, a także punkty odbioru i wysiadki w przypadku tej podróży. Możesz ustawić to pole, dzwoniąc pod numer CreateTrip lub UpdateTrip. Możesz też zaktualizować punkty pośrednie pojazdu za pomocą pola waypoints, wywołując funkcję UpdateVehicle. Ze względu na ochronę prywatności usługa nie zwraca tych informacji w przypadku połączeń GetTrip.
number_of_passengers Nie Liczba pasażerów w przejeździe.
dropoff_point Nie Miejsce docelowe podróży.
vehicle_id Nie Identyfikator pojazdu przypisanego do przejazdu.

Przykład: tworzenie podróży do wielu miejsc docelowych

Poniżej znajdziesz przykład tworzenia ekskluzywnej podróży z wieloma miejscami docelowymi, która obejmuje miejsce odbioru, miejsce docelowe i 1 miejsce 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 przejazdu z wieloma miejscami docelowymi

Musisz skonfigurować przejazd z identyfikatorem pojazdu, aby Fleet Engine mógł śledzić pojazd na trasie. Szczegółowe informacje o aktualizowaniu wycieczki znajdziesz w artykule Aktualizowanie wycieczek i zarządzanie ich stanem.

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

Przykładowa aktualizacja przejazdu

Poniższy przykład pokazuje, jak zaktualizować przejazd, aby dodać listę pośrednich miejsc docelowych 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 przejazdu w przypadku przejazdów do wielu miejsc docelowych

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

W przypadku podróży z wieloma miejscami docelowymi oprócz aktualizacji stanu podróży, tak jak w przypadku podróży z jednym miejscem docelowym, musisz też za każdym razem, gdy pojazd dotrze do miejsca docelowego, zaktualizować te informacje:

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

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

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

Przykładowa podróż z miejscami docelowymi po drodze

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

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?