路徑總覽 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 所需的基本步驟。這些操作說明的假設如下：

現有的 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();