Route Overview API 是基于 DriverSDK。借助它,您可以检索指定车辆的路线信息, 采用一次性提取的方式,也可以使用监听器持续进行更新。通过 Route Overview API 支持以下类型的信息:
- 完整路线计划,包括车辆停靠站位置、行程时间、距离
- 各停靠站之间的路线多段线路径。
本文档介绍了针对您的应用与 API 集成的步骤。
前提条件
- 您必须使用 alpha 版运行您的 Android 应用
版本为 4.1.0 或更高版本的 DriverSDK。Alpha 渠道可供使用
为 Maven artifactId 使用
transportation-driver-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 之间的连接所必需的。路线
Overview API 应使用您用于初始化的上下文对象进行初始化,
在 DriverSDK 中初始化 DeliveryDriverApi
,因为该对象引用了
之前在 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 是在 disabled 状态,以避免不必要的网络带宽消耗。
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();