路徑總覽 API

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