Tworzenie wspólnych przejazdów

Ten dokument opisuje, jak utworzyć przejazd współdzielony, ustawić odpowiednie pola i przypisać go do pojazdu, który ma go zrealizować. Zakładamy, że masz skonfigurowany Fleet Engine, utworzone pojazdy, działającą aplikację dla kierowców i opcjonalnie aplikację użytkownika. Powinnaś 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 opisano szczegóły żądania niezbędne do utworzenia przejazdu w Fleet Engine. Wysyłasz żądanie utworzenia za pomocą gRPC i REST.

  • Metoda CreateTrip(): gRPC lub REST
  • Komunikat CreateTripRequest: tylko gRPC

Pola dotyczące przejazdu

Aby utworzyć przejazd w Fleet Engine, użyj tych pól. Możesz używać różnych pól w przypadku różnych rodzajów przejazdów: z jednym lub wieloma miejscami docelowymi, przejazdów łączonych lub przejazdów współdzielonych. Możesz podać pola opcjonalne podczas tworzenia przejazdu lub ustawić je później, gdy będziesz go aktualizować.

Pola dotyczące 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 Fleet Engine i mieć te same role konta usługi.
trip_id Tak Utworzony przez Ciebie ciąg znaków, który jednoznacznie identyfikuje dany przejazd. Identyfikatory przejazdów podlegają pewnym ograniczeniom, które są opisane w dokumentacji.
trip_type Tak Ustaw TripType na te wartości dla typu przejazdu, który tworzysz:
  • Pojedyncze miejsce docelowe: ustaw na SHARED lub EXCLUSIVE.
  • Multi-destination (Wiele miejsc docelowych): ustaw wartość EXCLUSIVE.
  • Back-to-back (Jedna po drugiej): ustaw na EXCLUSIVE.
  • Wspólne miejsce na dane: ustawiono na SHARED.
pickup_point Tak Punkt początkowy przejazdu.
Miejsca pośrednie Tak

Tylko przejazdy z wieloma miejscami docelowymi: lista miejsc docelowych, które kierowca odwiedza między odbiorem a wysiadaniem. 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 pośrednie przypisanego pojazdu, a także punkty odbioru i wysiadki dla tego przejazdu. Możesz ustawić to pole, wywołując CreateTrip lub UpdateTrip. Możesz też zaktualizować punkty pośrednie pojazdu w polu waypoints, wywołując UpdateVehicle. Ze względu na ochronę prywatności usługa nie zwraca tych informacji w wywołaniach GetTrip.
number_of_passengers Nie Liczba pasażerów podczas przejazdu.
dropoff_point Nie Miejsce docelowe podróży.
vehicle_id Nie Identyfikator pojazdu przypisanego do przejazdu.

Przykład: tworzenie przejazdu ze współdzieleniem przejazdów

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

// 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 ze współdzieleniem przejazdu

Każdy przejazd utworzony w Fleet Engine musi być przypisany do pojazdu, aby Fleet Engine mógł obliczyć szacowany czas dotarcia na miejsce i śledzić przejazd. Możesz to zrobić podczas tworzenia przejazdu lub później, gdy go aktualizujesz.

W przypadku przejazdów współdzielonych musisz określić kolejność nieodwiedzonych punktów orientacyjnych w kolekcji punktów orientacyjnych pojazdu (Trip.vehicle_waypoints). Fleet Engine używa tej listy do automatycznego aktualizowania punktów orientacyjnych wszystkich przejazdów w puli współdzielonej.

Rozważmy na przykład 2 przejazdy we wspólnej puli: przejazd A i przejazd B:

  • Przejazd A jest w trakcie realizacji.
  • Następnie do tego samego pojazdu dodawany jest przejazd B.

W jednym wywołaniu UpdateTripRequest dla przejazdu B ustawiasz vehicleId, a także Trip.vehicle_waypoints na optymalną kolejność punktów pośrednich: odbiór B → wysiadanie A → wysiadanie B.

  • Wywołanie getVehicle() zwraca remainingWaypoints, które zawierają:
    B Odbiór → A Wysiadka → B Wysiadka.
  • Wywołanie zwrotne getTrip() lub onTripRemainingWaypointsUpdated dla przejazdu A zwraca remainingWaypoints , które zawierają:
    Odbiór B → wysiadka A.
  • Wywołanie zwrotne getTrip() lub onTripRemainingWaypointsUpdated dla przejazdu B zwraca remainingWaypoints, które zawierają:
    odbiór B → wysiadka A → wysiadka B.

Przykład

Poniższy przykład integracji backendu pokazuje, jak zaktualizować przejazd, podając identyfikator pojazdu i punkty pośrednie dla 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?