Создавайте поездки по нескольким направлениям

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

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

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

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

Поля поездок

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

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

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

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

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

количество_пассажиров Нет Количество пассажиров в поездке.
точка_высадки Нет Цель поездки.
идентификатор_транспортного_средства Нет Идентификатор транспортного средства, назначенного для поездки.

Пример: создание поездки с несколькими пунктами назначения

Ниже показано, как создать эксклюзивную поездку с несколькими пунктами назначения, включающую пункт отправления, пункт назначения и один промежуточный пункт назначения.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip initial settings.
String parent = "providers/" + PROJECT_ID;

Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE)
    .setPickupPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.195139).setLongitude(106.820826)))
    .setNumberOfPassengers(1)
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.1275).setLongitude(106.6537)))
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .build();

// Create the Trip request.
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_ID)  // Trip ID assigned by the Provider server.
    .setTrip(trip)       // Initial state is NEW.
    .build();

// Error handling.
try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:  // Trip already exists.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Обновить поездку с несколькими пунктами назначения

Необходимо настроить поездку с идентификатором транспортного средства, чтобы Fleet Engine мог отслеживать транспортное средство на маршруте. Подробнее об обновлении поездки см. в разделе Обновление поездок и управление их состоянием .

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

Пример обновления поездки

Ниже показано, как обновить поездку, добавив список промежуточных пунктов назначения и задав идентификатор транспортного средства.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(
        FieldMask.newBuilder()
            .addPaths("intermediate_destinations")
            .addPaths("vehicle_id")
            .build())
    .build();

// Error handling.
try {
  Trip updatedTrip =
      tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:            // The trip doesn't exist.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Управление состоянием поездки для поездок с несколькими пунктами назначения

Состояние поездки указывается с помощью одного из значений перечисления TripStatus . При изменении состояния поездки, например, с ENROUTE_TO_PICKUP на ARRIVED_AT_PICKUP , необходимо обновить состояние поездки в Fleet Engine. Состояние поездки всегда начинается со значения NEW и заканчивается значением COMPLETE или CANCELED .

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

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

Для этого используйте следующие значения из перечисления TripStatus .

  • ENROUTE_TO_PICKUP
  • ARRIVED_AT_PICKUP
  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETE

Пример поездки с промежуточными пунктами назначения

Ниже показано, как создать поездку с несколькими пунктами назначения, которая уже прошла пункт отправления и теперь находится на пути к первому промежуточному пункту назначения.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

// Get the trip object from either the Fleet Engine or storage.
Trip trip = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Trip status cannot return to a previous state once it has passed.
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)

    // Enroute to the first intermediate destination.
    .setIntermediateDestinationIndex(0)

    // You must provide an intermediate_destinations_version to ensure that you
    // have the same intermediate destinations list as the Fleet Engine.
    .setIntermediateDestinationsVersion(
         trip.getIntermediateDestinationsVersion())
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(
        FieldMask.newBuilder()
            .addPaths("trip_status")
            .addPaths("intermediate_destination_index")
            // intermediate_destinations_version must not be in the update mask.
            .build())
    .build();

// Error handling.
try {
  Trip updatedTrip =
      tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // Either the trip status is invalid, or the
                               // intermediate_destinations_version doesn't
                               // match Fleet Engine's.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Что дальше?