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

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

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

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

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

Поля поездки

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

Поля поездки
Название Обязательно? Описание
parent Да Строка, содержащая идентификатор проекта. Этот идентификатор должен быть одинаковым для всех интеграций Fleet Engine и иметь те же роли сервисного аккаунта.
trip_id Да Строка, которую вы создаете для уникальной идентификации этой поездки. Для идентификаторов поездок действуют определенные ограничения, указанные в справочной документации.
trip_type Да Задайте для параметра TripType одно из следующих значений в зависимости от типа поездки:
  • Один целевой URL. Задайте значение 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;
}

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