API обзора маршрута

API обзора маршрутов — это продукт решения последней мили для парка транспортных средств, созданный на основе DriverSDK. С его помощью вы можете получать информацию о маршруте для данного транспортного средства либо однократно, либо постоянно, используя прослушиватель обновлений. API обзора маршрутов поддерживает следующие виды информации:

• Полный план маршрута, включая места остановок транспортных средств, время в пути, расстояния.
• Полилиния маршрута между каждой остановкой.

В этом документе описаны шаги интеграции с API для вашего приложения.

Предварительные условия

• Вы должны запускать приложение Android, используя альфа- канал DriverSDK v4.1.0 или выше . Альфа-канал доступен с помощью transportation-driver-alpha для идентификатора артефакта Maven.
• API использует информацию о маршруте, предоставленную Fleet Engine через API доставки. Это можно предоставить либо через API в DriverSDK ( DeliveryDriverApi ), либо непосредственно в Fleet Engine.

Этапы интеграции

В этом разделе описаны основные шаги, необходимые для интеграции вашего приложения-драйвера Android с API. Эти инструкции имеют следующие предположения:

• У вас есть приложение для Android, которое уже интегрировано с Driver SDK.
• Вы инициализировали DeliveryDriverApi в своем приложении с помощью объекта контекста, который вы можете найти.

Подробности см. в разделе «Начало работы с Driver SDK для Android ».

Шаг 0 — Настройка маршрута

Вы можете пропустить этот шаг, если вы уже настроили Fleet Engine и можете создавать остановки транспортных средств и задачи доставки.

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

Шаг 1. Инициализируйте API

После того как вы создадите действительный маршрут со связанными остановками и задачами, вы можете инициализировать API обзора маршрута. Инициализация обеспечивает основу, необходимую для соединения между Fleet Engine и API. API обзора маршрутов следует инициализировать с тем же объектом контекста, который вы использовали для инициализации DeliveryDriverApi в DriverSDK, поскольку этот объект ссылается на тот же идентификатор транспортного средства, определенный ранее в вашем объекте DriverContext . В следующем примере показано, как создать экземпляр RouteOverviewApi .

RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

Шаг 2. Зарегистрируйте транспортное средство для событий изменения маршрута.

Теперь, когда вы инициализировали API, вы можете использовать объект VehicleRouteOverview для взаимодействия с возможностями обзора маршрута. Это позволяет вашему приложению использовать информацию о маршруте, которую вы предоставили во время настройки маршрута. Используйте прослушиватель событий API для облегчения обновления событий и получения маршрутов.

Событие изменения маршрута происходит всякий раз, когда обновляется путь к любой из остановок, назначенных транспортному средству, перестановка остановки или когда Fleet Engine обновляет информацию о расчетном времени прибытия.

vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

Шаг 3. Включите API

Теперь, когда вы готовы использовать информацию о маршруте, вам необходимо включить API, чтобы он мог реагировать на события транспортного средства. Помните, что API инициализируется в отключенном состоянии, чтобы избежать ненужного потребления пропускной способности сети.

VehicleRouteOverview.setRouteOverviewEnabled(истина);

Вы можете приостановить эти обновления в любое время, вызвав тот же метод со значением false .

Шаг 4. Нарисуйте маршрут на карте Google.

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

    GoogleMap googleMap = … // Instance of the Map view you are using
    ImmutableList<RouteToVehicleStop> route = event.newRoute();

    PolylineOptions routePolyline = new PolylineOptions().color(Color.BLUE);
    for (RouteToVehicleStop stop : route) {
        routePolyline.addAll(stop.path());

        MarkerOptions marker =
            new MarkerOptions().position(stop.vehicleStop().getWaypoint().getPosition());
        googleMap.addMarker(marker);
    }

    googleMap.addPolyline(routePolyline);
}

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

Шаг 5. Получите снимок маршрута

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

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

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

Шаг 6 – Очистка

Если вашему приложению больше не нужна функция обзора маршрутов, вам следует убедиться, что вы все очистили. Выполнение очистки позволяет избежать ненужного потребления памяти, обработки и сети в вашем приложении.

Удаление определенного прослушивателя событий

Вам следует удалить прослушиватель событий, когда конкретный прослушиватель больше не нужен.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Очистить все прослушиватели событий

В рамках процедуры очистки вы можете одновременно удалить все зарегистрированные прослушиватели событий.

vehicleRouteOverview.clearEventListeners();

Очистить экземпляр API обзора маршрутов

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

vehicleRouteOverview.clearInstance();