Tworzenie wspólnych przejazdów

Z tego dokumentu dowiesz się, jak utworzyć przejazd z udostępnianiem puli, ustawić odpowiednie pola i przypisać go do pojazdu. Zakładamy, że masz już skonfigurowany Fleet Engine, utworzone pojazdy, działającą aplikację dla kierowców i opcjonalnie aplikację dla konsumentów. 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 podróży

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

  • CreateTrip() metoda: gRPC lub REST
  • CreateTripRequest wiadomość: tylko gRPC

Pola 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 do jednego lub wielu miejsc docelowych, przejazdów bezpośrednich lub przejazdów współdzielonych. Pola opcjonalne możesz podać podczas tworzenia wycieczki lub ustawić je później, gdy będziesz aktualizować wycieczkę.

Pola dotyczące podróży
Nazwa Wymagany? Opis
parent Tak Ciąg tekstowy zawierający identyfikator projektu. 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 utworzony przez Ciebie, który jednoznacznie identyfikuje tę podróż. Identyfikatory przejazdów podlegają pewnym ograniczeniom, o których mowa w dokumentacji.
trip_type Tak Ustaw wartość TripType na te wartości dla tworzonego typu przejazdu:
  • Pojedyncze miejsce docelowe: ustaw na SHARED lub EXCLUSIVE.
  • Wiele miejsc docelowych: ustaw na EXCLUSIVE.
  • Jeden po drugim: ustaw na EXCLUSIVE.
  • Pula współdzielona: ustawiona 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 trasy przypisanego pojazdu, a także punkty odbioru i wysadzenia pasażera w przypadku tej podróży. To pole możesz ustawić, dzwoniąc pod numer CreateTrip lub UpdateTrip. Możesz też zaktualizować punkty na trasie 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: tworzenie wspólnego przejazdu

Poniższy przykład integracji backendu pokazuje, jak utworzyć przejazd i przypisać go do pojazdu jako przejazd wspólny.

// 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 przejazdów wspólnych

Każda podróż utworzona w Fleet Engine musi być przypisana do pojazdu, aby Fleet Engine mógł obliczać szacowany czas przyjazdu i śledzić podróż. Możesz to zrobić podczas tworzenia wycieczki lub później, gdy ją zaktualizujesz.

W przypadku przejazdów z wspólnym przejazdem musisz określić kolejność nieodwiedzonych punktów pośrednich w kolekcji punktów pośrednich pojazdu (Trip.vehicle_waypoints). Fleet Engine używa tej listy do automatycznego aktualizowania punktów pośrednich przejazdu dla wszystkich przejazdów we wspólnym przejeździe.

Rozważmy na przykład 2 podróże w ramach wspólnych przejazdów: Podróż A i Podróż B:

  • Przejazd A jest w drodze do miejsca docelowego.
  • Przejazd B zostanie dodany do tego samego pojazdu.

W przypadku przejazdu B w jednym UpdateTripRequest ustawiasz vehicleId, a także Trip.vehicle_waypoints w optymalnej kolejności punktów pośrednich: B miejsce odbioru → A miejsce docelowe → B miejsce docelowe.

  • Wywołanie getVehicle() zwraca remainingWaypoints, które zawiera:
    B Odbiór → A Miejsce docelowe → B Miejsce docelowe.
  • Funkcja getTrip() lub funkcja zwrotna onTripRemainingWaypointsUpdated dla przejazdu A zwraca remainingWaypoints zawierające:
    B Miejsce odbioru → A Miejsce docelowe.
  • Wywołanie zwrotne getTrip() lub onTripRemainingWaypointsUpdated dla przejazdu B zwraca remainingWaypoints zawierające:
    B Miejsce odbioru → A Miejsce docelowe → B Miejsce docelowe.

Przykład

Ten przykładowy kod integracji backendu pokazuje, jak zaktualizować przejazd, podając identyfikator pojazdu i punkty pośrednie w przypadku 2 przejazdów współdzielonych.

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?