Route Overview API 是以 DriverSDK 建構的 Last Mile Fleet 解決方案產品。您可以利用這個方式擷取特定車輛的路線資訊,無論是一次性擷取,還是使用事件監聽器進行更新,都沒問題。Route Overview API 支援以下類型的資訊:
- 完整路線計畫,包括車輛停靠站位置、交通時間和距離
- 每個停靠站之間的路線折線路徑。
本文件說明應用程式的 API 整合步驟。
必要條件
- 您必須使用 DriverSDK v4.1.0 或 以上版本的 alpha 管道執行 Android 應用程式。Alpha 版本可透過
transportation-driver-alpha
做為 Maven artifactId 來使用。 - API 會使用 Fleet Engine 透過 Deliveries API 提供的路線資訊。這可透過 DriverSDK 上的 API (
DeliveryDriverApi
) 或直接提供給 Fleet Engine。
整合步驟
本節說明整合 Android 驅動程式應用程式與 API 所需的基本步驟。這些操作說明的假設如下:
- 您已經有已與 Driver SDK 整合的現有 Android 應用程式
- 您已使用結構定義物件在應用程式中初始化
DeliveryDriverApi
詳情請參閱「開始使用 Android 適用的驅動程式 SDK」一文。
步驟 0 - 路線設定
如果您已設定 Fleet Engine,且可建立車輛停靠站和外送工作,可以略過這個步驟。
如要將停靠站和工作資訊載入 Fleet Engine,您需要將外送車輛指派給有效路線。這是因為 Route Overview API 需要有效的路徑才能擷取資料。有效的路徑由一系列路線控點和停靠站組成,只有在至少具備一項相關任務的情況下,停靠站才能存在。詳情請參閱 Fleet Engine API 整合指南。
步驟 1 - 初始化 API
建立含有相關停靠站和工作的有效路徑後,就可以初始化 Route Overview API。初始化作業會提供 Fleet Engine 與 API 之間連線所需的架構。因此 Route Overview API 應透過在 DriverSDK 中初始化 DeliveryDriverApi
的結構定義物件初始化,因為物件參照的車輛 ID 與先前在 DriverContext
物件中定義的相同車輛 ID。以下範例說明如何建立 RouteOverviewApi
的執行個體。
RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
api = RouteOverviewApi.createInstance(context);
}
步驟 2 - 註冊車輛以用於路線變更事件
現在您已初始化 API,可以使用 VehicleRouteOverview
物件與路徑總覽功能互動。這樣應用程式就能使用您在設定路徑時提供的路線資訊。使用 API 事件監聽器協助更新事件和路徑擷取。
每當指派給車輛的任何停靠站路徑更新、停靠站重新排列,或機群引擎更新預計到達時間資訊時,就會發生路線變更事件。
vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
// handle route update events
});
步驟 3 - 啟用 API
準備好使用路線資訊後,您必須啟用 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 總覽 API 執行個體
每當不再需要路徑總覽,或者正在追蹤的車輛 ID 有所變更時,您可以呼叫這個 API 來清除內部參照。
vehicleRouteOverview.clearInstance();