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

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

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

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

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

Поля поездки

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

Поля поездки
Название Обязательно? Описание
parent Да Строка, содержащая идентификатор проекта. Этот идентификатор должен быть таким же, как и во всей интеграции Fleet Engine, с теми же ролями сервисного аккаунта.
trip_id Да Строка, которую вы создаете для уникальной идентификации этой поездки. Для идентификаторов поездок действуют определенные ограничения, указанные в справочной документации.
trip_type Да Задайте для TripType одно из следующих значений в зависимости от типа поездки:
  • Один пункт назначения. Укажите SHARED или EXCLUSIVE.
  • Multi-destination (Несколько пунктов назначения): EXCLUSIVE.
  • Back-to-back: установите значение EXCLUSIVE.
  • Общий пул. Задайте значение SHARED.
pickup_point Да Пункт отправления.
Промежуточные пункты Да

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

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

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