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