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

В этом документе описывается, как создать поездку с несколькими пунктами назначения, задать необходимые поля и назначить ее транспортному средству для выполнения. Предполагается, что у вас уже настроена система 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 Нет Идентификационный номер транспортного средства, назначенного для поездки.

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

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

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

Что дальше?