Tworzenie wspólnych przejazdów

Z tego dokumentu dowiesz się, jak utworzyć wspólną podróż w ramach wspólnego przejazdu, ustawić odpowiednie pola i przypisać ją do pojazdu, który chcesz 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

Ta sekcja opisuje szczegóły żądania niezbędne do utworzenia podróży we Fleet Engine. Wysyłasz żądanie utworzenia za pomocą gRPC lub REST.

  • Metoda CreateTrip(): gRPC lub REST
  • Komunikat CreateTripRequest: 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, które podano w pliku referencyjnym.
trip_type Tak W polu TripType ustaw te wartości dla tworzonego typu podróży:
  • Pojedyncze miejsce docelowe: ustaw SHARED lub EXCLUSIVE.
  • Wiele miejsc docelowych: ustaw wartość EXCLUSIVE.
  • Back-to-back (z powrotem): ustaw na EXCLUSIVE.
  • Wspólne udostępnianie: ustaw 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 podróże w ramach wspólnego puli: to pole obsługuje przeplatanie punktów pośrednich z wielu przejazdów. Zawiera wszystkie pozostałe punkty pośrednie dla przypisanego pojazdu, a także punkty odbioru i zwrotu w ramach tej podróży. Możesz ustawić to pole, wywołując funkcję CreateTrip lub UpdateTrip. Możesz też aktualizować 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 Cel podróży.
vehicle_id Nie Identyfikator pojazdu przypisanego do przejazdu.

Przykład: tworzenie wspólnej podróży z wielu odcinków

Poniższy przykład integracji backendu pokazuje, jak utworzyć podróż i przypisać ją do pojazdu w ramach wspólnego korzystania.

// Vehicle with VEHICLE_ID ID is already created and it is assigned Trip A.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "shared-trip-A";
static final String VEHICLE_ID = "your-vehicle-id";
static final String TRIP_A_ID = "trip-a-id";
static final String TRIP_B_ID = "trip-b-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;

LatLng tripBPickup =
    LatLng.newBuilder().setLatitude(-12.12314).setLongitude(88.142123).build();
LatLng tripBDropoff =
    LatLng.newBuilder().setLatitude(-14.12314).setLongitude(90.142123).build();

TerminalLocation tripBPickupTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBPickup).build();
TerminalLocation tripBDropoffTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBDropoff).build();

// TripA already exists and it's assigned to a vehicle with VEHICLE_ID ID.
Trip tripB = Trip.newBuilder()
    .setTripType(TripType.SHARED)
    .setVehicleId(VEHICLE_ID)
    .setPickupPoint(tripBPickupTerminalLocation)
    .setDropoffPoint(tripBDropoffTerminalLocation)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripBPickupTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripBDropoffTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// Create Trip request
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_B_ID)
    .setTrip(tripB)
    .build();

try {
  // createdTrip.remainingWaypoints will contain shared-pool waypoints.
  // [tripB.pickup, tripA.dropoff, tripB.dropoff]
  Trip createdTrip = tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Aktualizowanie wspólnych przejazdów w grupach

Aby Fleet Engine mógł obliczyć przewidywany czas dojazdu i śledzić go, każda podróż utworzona w Fleet Engine musi zostać przypisana do pojazdu. Możesz to zrobić podczas tworzenia podróży lub później, gdy ją aktualizujesz.

W przypadku wspólnych przejazdów w ramach wspólnego użytkowania musisz określić kolejność nieodwiedzionych punktów pośrednich w zbiorze punktów pośrednich pojazdu (Trip.vehicle_waypoints). Fleet Engine używa tej listy do automatycznej aktualizacji punktów pośrednich wszystkich przejazdów w ramach wspólnego użytkowania.

Rozważmy na przykład 2 wycieczki w ramach wspólnego basenu, Podróż A i Podróż B:

  • Podróż A jest w drodze do miejsca docelowego.
  • Następnie zostanie dodana Podróż B do tego samego pojazdu.

W jednym UpdateTripRequest dla Podróż B ustawiasz vehicleId, a także Trip.vehicle_waypoints na optymalną kolejność punktów orientacyjnych: B Odbiór → A Wysiadanie → B Wysiadanie.

  • Wywołanie getVehicle() zwraca remainingWaypoints zawierające:
    B Odbiór → A Odbiór → B Odbiór.
  • Wywołanie getTrip() lub onTripRemainingWaypointsUpdated dla Podróży A zwraca remainingWaypoints, które zawierają:
    B Odbiór → A Droga do zwrotu.
  • getTrip() lub wywołanie funkcji onTripRemainingWaypointsUpdated w Podróż B zwraca remainingWaypoints zawierające:
    Odbiór B → Odstawienie A → Odstawienie B.

Przykład

Ten przykład integracji z backendem pokazuje, jak zaktualizować przejazd z identyfikatorem pojazdu i punktami drogi w przypadku 2 przejazdów w wspólnej taksówce.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_A_ID = "share-trip-A";
static final String TRIP_B_ID = "share-trip-B";
static final String VEHICLE_ID = "Vehicle";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_B_ID;

// Get Trip A and Trip B objects from either the Fleet Engine or storage.
Trip tripA = …;
Trip tripB = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId(VEHICLE_ID)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getPickupPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getDropoffPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_id")
        .addPaths("vehicle_waypoints"))
    .build();

// Error handling. If Fleet Engine has both a trip and vehicle with the IDs,
// and if the credentials validate, and if the given vehicle_waypoints list
// is valid, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:          // Either the trip or vehicle does not exist.
      break;
    case PERMISSION_DENIED:
      break;
    case INVALID_REQUEST:    // vehicle_waypoints is invalid.
      break;
  }
  return;
}

Co dalej?