Tworzenie wspólnych przejazdów

Z tego dokumentu dowiesz się, jak utworzyć podróż w ramach wspólnego przejazdu, ustawić odpowiednie pola i przypisać ją do pojazdu. Zakładamy, że masz już skonfigurowaną usługę Fleet Engine, utworzone pojazdy, działającą aplikację kierowcy i opcjonalnie aplikację użytkownika. Powinieneś też znać różne scenariusze podróży dostępne w przypadku podróży na żądanie. Więcej informacji znajdziesz w tych powiązanych przewodnikach:

Podstawowe informacje o tworzeniu podróży

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

  • Metoda CreateTrip(): gRPC lub REST
  • Wiadomość CreateTripRequest: gRPC tylko

Pola podróży

Aby utworzyć podróż w Fleet Engine, użyj tych pól. Możesz używać różnych pól w przypadku różnych rodzajów podróży: z 1 lub kilkoma miejscami docelowymi, bezpośrednich lub wspólnych. Pola opcjonalne możesz podać podczas tworzenia podróży lub ustawić je później podczas aktualizowania podróży.

Pola podróży
Nazwa Wymagany? Opis
parent Tak Ciąg znaków 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 Ciąg znaków, który tworzysz i który jednoznacznie identyfikuje tę podróż. Identyfikatory podróży podlegają pewnym ograniczeniom, które są opisane w dokumentacji.
trip_type Tak W przypadku tworzonego typu podróży ustaw TripType na te wartości:
  • 1 miejsce docelowe: ustaw na SHARED lub EXCLUSIVE.
  • Wiele miejsc docelowych: ustaw na EXCLUSIVE.
  • Bezpośrednia: ustaw na EXCLUSIVE.
  • Wspólna: ustaw na SHARED.
pickup_point Tak Punkt początkowy podróży.
Miejsca docelowe pośrednie Tak

Tylko podróże z wieloma miejscami docelowymi: lista miejsc docelowych pośrednich, 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 podróż z wieloma miejscami docelowymi z definicji zawiera miejsca docelowe pośrednie.
vehicle_waypoints Tak

Tylko podróże wspólne: to pole obsługuje przeplatanie punktów na trasie z wielu podróży. Zawiera wszystkie pozostałe punkty na trasie przypisanego pojazdu, a także punkty odbioru i docelowe tej podróży. To pole możesz ustawić wywołując CreateTrip lub UpdateTrip. Punkty na trasie pojazdu możesz też zaktualizować za pomocą pola waypoints, wywołując 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 podróży.

Przykład: tworzenie podróży wspólnej

Ten przykładowy kod integracji backendu pokazuje, jak utworzyć podróż i przypisać ją do pojazdu jako podróż wspólną.

// 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 podróży wspólnych

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

W przypadku podróży wspólnych musisz określić kolejność nieodwiedzonych punktów na trasie w kolekcji punktów na trasie pojazdu (Trip.vehicle_waypoints). Fleet Engine używa tej listy do automatycznego aktualizowania punktów na trasie wszystkich podróży we wspólnym przejeździe.

Załóżmy, że masz 2 podróże wspólne: podróż A i podróż B:

  • Podróż A jest w drodze do miejsca docelowego.
  • Podróż B jest dodawana do tego samego pojazdu.

W jednym UpdateTripRequest dla podróży B, ustawiasz vehicleId, a także ustawiasz Trip.vehicle_waypoints na optymalną kolejność punktów na trasie: odbiór B → miejsce docelowe A → miejsce docelowe B.

  • Wywołanie getVehicle() zwraca remainingWaypoints które zawierają:
    odbiór B → miejsce docelowe A → miejsce docelowe B.
  • Wywołanie getTrip() lub wywołanie zwrotne onTripRemainingWaypointsUpdated dla podróży A zwraca remainingWaypoints które zawierają:
    odbiór B → miejsce docelowe A.
  • Wywołanie getTrip() lub wywołanie zwrotne onTripRemainingWaypointsUpdated dla podróży B zwraca remainingWaypoints które zawierają:
    odbiór B → miejsce docelowe A → miejsce docelowe B.

Przykład

Ten przykładowy kod integracji backendu pokazuje, jak zaktualizować podróż za pomocą identyfikatora pojazdu i punktów na trasie w przypadku 2 podróży wspólnych.

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?