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

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

• Настройка Fleet Engine
• Создать автомобиль
• Сценарии поездок в обзоре поездок по требованию

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

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

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

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

Поля поездки

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

Поля поездки

Имя	Необходимый?	Описание
родитель	Да	Строка, включающая идентификатор проекта. Этот идентификатор должен совпадать с тем же идентификатором, который используется во всей вашей интеграции Fleet Engine, с теми же ролями учетной записи службы.
trip_id	Да	Созданная вами строка, которая однозначно идентифицирует эту поездку. Идентификаторы поездок имеют определенные ограничения, как указано в справке.
тип_путешествия	Да	Установите для TripType следующие значения для создаваемого типа поездки: Один пункт назначения : установите значение SHARED или EXCLUSIVE . Несколько пунктов назначения : установите значение EXCLUSIVE . Взаимно : установите значение EXCLUSIVE . Общий пул : установите значение SHARED .
точка_подачи	Да	Начальная точка поездки.
Промежуточные направления	Да	Только поездки с несколькими пунктами назначения : список промежуточных пунктов назначения, которые водитель посещает между посадкой и высадкой. Как и в случае с dropoff_point , это поле также можно установить позже, вызвав UpdateTrip , но поездка с несколькими пунктами назначения по определению содержит промежуточные пункты назначения.
Vehicle_waypoints	Да	Только поездки с общим пулом : это поле поддерживает чередование путевых точек из нескольких поездок. Он содержит все оставшиеся путевые точки для назначенного транспортного средства, а также путевые точки посадки и высадки для этой поездки. Вы можете установить это поле, вызвав CreateTrip или UpdateTrip . Вы также можете обновить путевые точки транспортного средства через поле waypoints с помощью вызова UpdateVehicle . Служба не возвращает эту информацию при звонках GetTrip по соображениям конфиденциальности.
количество_пассажиров	Нет	Количество пассажиров в поездке.
dropoff_point	Нет	Пункт назначения поездки.
идентификатор транспортного средства	Нет	Идентификатор транспортного средства, назначенного для поездки.

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

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

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 мог отслеживать транспортное средство по его маршруту. Подробную информацию об обновлении поездки см. в разделе Обновление поездок и управление их состоянием .

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

Примечание. Каждый раз, когда вы устанавливаете или обновляете intermediate_destinations в поездке, Fleet Engine заполняет intermediate_destinations_version в созданном объекте поездки. Вы должны кэшировать это поле в своей системе и передать ему UpdateTripRequest при последующем обновлении intermediate_destination_index . Это обеспечивает синхронизацию промежуточных пунктов назначения между вашим клиентом водителя и 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

Примечание. Поездка должна проходить через ENROUTE_TO_INTERMEDIATE_DESTINATION и ARRIVED_AT_INTERMEDIATE_DESTINATION один раз для каждого промежуточного пункта назначения.

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

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

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

Что дальше

• Создавайте последовательные поездки
• Настройте SDK драйверов