Создавайте общие групповые поездки

В этом документе описывается, как создать совместную поездку, заполнить необходимые поля и назначить её транспортному средству для выполнения. Предполагается, что у вас настроена система Fleet Engine, созданы транспортные средства, есть работающее приложение для водителей и, при необходимости, приложение для клиентов. Вам также следует ознакомиться с различными сценариями поездок, доступными для поездок по запросу. См. следующие руководства по этой теме:

Основы создания поездок

В этом разделе описываются детали запроса, необходимые для создания поездки в Fleet Engine. Запрос на создание поездки можно отправить, используя gRPC или REST.

  • Метод CreateTrip() : gRPC или REST
  • Сообщение CreateTripRequest : только для gRPC

Поля поездок

Для создания поездки в Fleet Engine используйте следующие поля. Вы можете использовать разные поля для разных типов поездок: с одним или несколькими пунктами назначения, непрерывные поездки или поездки с совместным использованием транспортных средств. Вы можете указать необязательные поля при создании поездки или задать их позже при обновлении поездки.

Поля поездок
Имя Необходимый? Описание
родитель Да Строка, содержащая идентификатор проекта. Этот идентификатор должен совпадать с идентификатором, используемым во всей интеграции Fleet Engine, с теми же ролями учетных записей служб.
trip_id Да Созданная вами строка, которая однозначно идентифицирует эту поездку. Идентификаторы поездок имеют определенные ограничения, как указано в справочной информации.
trip_type Да Для создаваемого типа поездки установите для параметра TripType следующие значения:
  • Единое место назначения : установите значение SHARED или EXCLUSIVE .
  • Многоадресная рассылка : установить режим EXCLUSIVE .
  • Последовательно : установить режим EXCLUSIVE .
  • Общий пул : установите значение SHARED .
точка выдачи Да Начальная точка поездки.
Промежуточные пункты назначения Да

Только для поездок с несколькими пунктами назначения : список промежуточных пунктов назначения, которые водитель посещает между местом посадки и высадки. Как и в случае с dropoff_point , это поле также можно установить позже, вызвав UpdateTrip , но поездка с несколькими пунктами назначения по определению включает промежуточные пункты назначения.

путевые точки транспортного средства Да

Только для совместных поездок : это поле поддерживает чередование путевых точек из нескольких поездок. Оно содержит все оставшиеся путевые точки для назначенного транспортного средства, а также путевые точки отправления и прибытия для этой поездки. Вы можете установить это поле, вызвав функции CreateTrip или UpdateTrip . Вы также можете обновить путевые точки транспортного средства через поле waypoints с помощью вызова функции UpdateVehicle . Сервис не возвращает эту информацию при вызовах GetTrip по соображениям конфиденциальности.

количество_пассажиров Нет Количество пассажиров в поездке.
точка высадки Нет Пункт назначения поездки.
vehicle_id Нет Идентификационный номер транспортного средства, назначенного для поездки.

Пример: создать поездку для совместного использования автомобиля.

Приведенный ниже пример интеграции с бэкэндом демонстрирует, как создать поездку и назначить ее транспортному средству в рамках совместного использования транспортных средств.

// 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;
}

Обновить информацию о совместных поездках.

Для того чтобы Fleet Engine мог рассчитать предполагаемое время прибытия и отслеживать поездку, любая созданная в Fleet Engine поездка должна быть привязана к транспортному средству. Это можно сделать либо во время создания поездки, либо позже при ее обновлении.

Для совместных поездок необходимо указать порядок непройденных путевых точек в коллекции путевых точек транспортного средства ( Trip.vehicle_waypoints ). Fleet Engine использует этот список для автоматического обновления путевых точек для всех поездок в общем пуле.

Например, рассмотрим две поездки в общий бассейн, поездку А и поездку Б :

  • Поезд А направляется к месту высадки.
  • Затем к тому же транспортному средству добавляется поездка B.

В одном из UpdateTripRequest для поездки B вы устанавливаете vehicleId , а также задаете Trip.vehicle_waypoints в оптимальном порядке путевых точек: B Pickup → A Drop-off → B Drop-off .

  • Вызов функции getVehicle() возвращает remainingWaypoints , содержащие:
    B — место посадки → A — место высадки → B — место высадки .
  • Либо getTrip() , либо функция обратного вызова onTripRemainingWaypointsUpdated для поездки A возвращают remainingWaypoints , содержащие:
    B — место посадки → A — место высадки .
  • Метод getTrip() или функция обратного вызова onTripRemainingWaypointsUpdated для поездки B возвращают remainingWaypoints , содержащие:
    B — место посадки → A — место высадки → B — место высадки .

Пример

Приведенный ниже пример интеграции с бэкэндом демонстрирует, как обновить данные о поездке, добавив идентификатор транспортного средства и путевые точки для двух поездок в рамках общего пользования.

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;
}

Что дальше?