Как создавать поездки с общим маршрутом

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

Как создавать поездки

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

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

Поля поездки

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

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

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

Только для совместных поездок. В этом поле можно чередовать путевые точки из разных поездок. Он содержит все оставшиеся путевые точки для назначенного транспортного средства, а также путевые точки посадки и высадки для этой поездки. Это поле можно задать, вызвав метод CreateTrip или UpdateTrip. Вы также можете изменить промежуточные точки маршрута автомобиля, используя поле waypoints и вызывая функцию UpdateVehicle. Сервис не возвращает эту информацию при звонках на номер GetTrip из соображений конфиденциальности.
number_of_passengers Нет Количество пассажиров в поездке.
dropoff_point Нет Пункт назначения поездки.
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 использует этот список для автоматического обновления путевых точек для всех поездок в совместном пуле.

Например, рассмотрим две поездки с попутчиками: Поездка А и Поездка Б.

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

В одном UpdateTripRequest для поездки Б вы задаете vehicleId, а также устанавливаете для Trip.vehicle_waypoints оптимальный порядок путевых точек: Б Посадка → А Высадка → Б Высадка.

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

Пример

В примере интеграции с внутренними системами показано, как обновить информацию о поездке, добавив идентификатор автомобиля и точки маршрута для двух поездок с попутчиками.

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

Дальнейшие действия