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 集成所需的基本步骤。这些说明具有以下假设：

您的现有 Android 应用已与驱动程序 SDK 集成
您已使用一个上下文对象在应用中初始化了 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();

清除路由概览 API 实例

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

vehicleRouteOverview.clearInstance();