Route Overview API

Route Overview API 是基于 DriverSDK 构建的最后一公里舰队解决方案产品。借助此功能，您可以检索给定车辆的路线信息，既可以一次性提取，也可以使用监听器进行更新。Route Overview API 支持以下类型的信息：

完整路线计划，包括车辆停靠站位置、行程时间、距离
各停靠站之间的路线多段线路径。

本文档介绍了针对您的应用与 API 集成的步骤。

前提条件

您必须使用 DriverSDK v4.1.0 或更高版本的 alpha 渠道运行 Android 应用。对于 Maven artifactId，可使用 transportation-driver-alpha 获取 Alpha 渠道。
该 API 会使用 Fleet Engine 通过 Deliveries API 提供的路线信息。这可以通过 DriverSDK 上的 API (DeliveryDriverApi) 提供，也可以直接提供给 Fleet Engine。

集成步骤

本部分介绍了将 Android 驱动程序应用与该 API 集成所需的基本步骤。这些说明做出以下假设：

您有一个已经与驱动程序 SDK 集成的现有 Android 应用
您已在应用中初始化了 DeliveryDriverApi，使用找到的上下文对象

如需了解详情，请参阅 Android 版驱动程序 SDK 使用入门。

第 0 步 - 路线设置

如果您已设置 Fleet Engine，并且可以创建车辆停靠和交付任务，则可以跳过此步骤。

如需将站点和任务信息加载到 Fleet Engine，您需要分配一辆交付车辆并将其分配到有效路线。这是因为 Route Overview API 需要有效的路由才能提取数据。有效路线由一系列航点和经停点组成，停靠站只有在至少有一个关联的任务时才能存在。如需了解详情，请参阅 Fleet Engine API 集成指南。

第 1 步 - 初始化 API

建立包含相关经停点和任务的有效路线后，您可以初始化 Route Overview API。初始化提供了 Fleet Engine 与 API 之间的连接所需的框架。您应使用您在 DriverSDK 中初始化 DeliveryDriverApi 时所用的同一上下文对象来初始化 Route Overview API，因为该对象引用的是之前在 DriverContext 对象中定义的同一车辆 ID。以下示例说明了如何创建 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(true);

您可以随时暂停这些更新，只需使用 false 值调用同一方法即可。

第 4 步 - 在 Google 地图上绘制路线

获取 RouteToVehicleStop 列表后，即可在应用中使用它。例如，您可以在 Google 地图实例中绘制路线多段线路径。以下代码段举例说明了如何在地图视图中绘制路线多段线，并在每个经停点位置顶部添加标记。

    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();

Clear Route Overview API 实例

每当不再需要路线概览或所跟踪的车辆的 ID 发生更改时，您可以调用此 API 来清除内部引用。

vehicleRouteOverview.clearInstance();