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, który ma go zrealizować. Zakładamy, że masz skonfigurowany Fleet Engine, utworzyłeś pojazdy, masz działającą aplikację dla kierowcy i opcjonalnie aplikację dla klienta. Powinieneś też znać różne scenariusze przejazdów dostępne w przypadku przejazdów na żądanie. Zapoznaj się z tymi przewodnikami:

Podstawowe informacje o tworzeniu podróży

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

  • CreateTrip() metoda: gRPC lub REST
  • CreateTripRequest komunikat: dotyczy tylko gRPC

Pola dotyczące podróży

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 z jednym lub wieloma miejscami docelowymi, przejazdów z powrotem lub przejazdów współdzielonych. Pola opcjonalne możesz podać podczas tworzenia podróży lub ustawić je później podczas jej aktualizowania.

Pola dotyczące podróży
Nazwa Wymagany? Opis
parent Tak Ciąg tekstowy zawierający identyfikator projektu. Identyfikator musi być taki sam we wszystkich integracjach z Fleet Engine, z tymi samymi rolami konta usługi.
trip_id Tak Tworzony przez Ciebie ciąg znaków, który jednoznacznie identyfikuje tę podróż. Identyfikatory podróży podlegają pewnym ograniczeniom, o których mowa w dokumentacji.
trip_type Tak Ustaw TripType na jedną z tych wartości, aby utworzyć odpowiedni typ podróży:
  • Jedno miejsce docelowe: ustaw wartość na SHARED lub EXCLUSIVE.
  • Wiele miejsc docelowych: ustaw na EXCLUSIVE.
  • Back-to-back (z powrotem): ustaw na EXCLUSIVE.
  • Udostępnianie zasobów: ustaw na SHARED.
pickup_point Tak Punkt początkowy podróży.
Miejsca docelowe pośrednie Tak

Tylko w przypadku przejazdów z wieloma miejscami docelowymi: lista miejsc docelowych pośrednich, które kierowca odwiedza w międzyczasie przejazdu od miejsca odbioru do miejsca docelowego. Podobnie jak w przypadku dropoff_point to pole można też ustawić później, wywołując funkcję UpdateTrip, ale przejazd z wieloma miejscami docelowymi z definicji zawiera miejsca docelowe pośrednie.
vehicle_waypoints Tak

Tylko w przypadku przejazdów współdzielonych: to pole obsługuje przeplatanie punktów pośrednich z różnych przejazdów. Zawiera wszystkie pozostałe punkty pośrednie dla przypisanego pojazdu, a także punkty odbioru i zwrotu w ramach tej podróży. To pole możesz ustawić, wywołując funkcję CreateTrip lub UpdateTrip. Możesz też zaktualizować punkty drogi 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 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 przejazdu.

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

Poniżej pokazujemy, jak utworzyć wyjazd z kilkoma miejscami docelowymi, który obejmuje punkt odbioru, punkt docelowy i jeden punkt pośredni.

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 silnik floty mógł śledzić pojazd na jego trasie. Szczegółowe informacje o aktualizowaniu podróży znajdziesz w artykule Aktualizowanie podróży i zarządzanie ich stanem.

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

Przykładowa aktualizacja podróży

Poniżej znajdziesz instrukcje aktualizowania podróży w celu dodania listy pośrednich miejsc docelowych i ustawienia identyfikatora 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 w przypadku podróży z wieloma miejscami docelowymi

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

W przypadku podróży z wieloma miejscami docelowymi oprócz aktualizacji stanu podróży w taki sam sposób jak w przypadku podróży z jednym miejscem docelowym musisz też aktualizować te informacje za każdym razem, gdy pojazd dotrze do miejsca docelowego pośredniego:

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

Aby to zrobić, użyj jednej z podanych niżej wartości z enumeracji TripStatus.

  • 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 opisujemy, jak utworzyć przejazd z wieloma miejscami docelowymi, który minął już punkt odbioru i jest teraz 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?