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 所需的基本步驟。這些操作說明的假設如下:
- 現有的 Android 應用程式已經與驅動程式 SDK 整合
- 您已使用情境物件初始化應用程式中的
DeliveryDriverApi
詳情請參閱「開始使用 Android 適用的驅動程式 SDK」。
步驟 0:路徑設定
如果您已設定 Fleet Engine 並且可以建立車輛停靠站和配送工作,可以略過這個步驟。
如要將停靠站和工作資訊載入 Fleet Engine,您需要指派給有效路徑的運輸車輛。這是因為 Route Overview API 需要有效的路徑才能擷取資料。有效路徑由一系列路線控點和停靠站組成,而停靠站至少要有一項相關任務,才會存在。詳情請參閱 Fleet Engine API 整合指南。
步驟 1:初始化 API
與相關聯的停靠站和工作建立有效路徑後,您就可以初始化 Route Overview API。初始化可提供 Fleet Engine 和 API 之間連線所需的架構。由於物件參照先前在 DriverContext
物件中定義的相同車輛 ID,因此 Route Overview API 應使用您用來初始化 DriverSDK 中 DeliveryDriverApi
的結構定義物件。以下範例說明如何建立 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();