路徑總覽 API

Route Overview API 是 Last Mile Fleet Solution 產品， DriverSDK.使用這項功能擷取特定車輛的路線資訊 作為一次性擷取，或透過監聽器持續更新。 Route Overview API 支援下列類型的資訊：

  • 完整路線計畫，包括車輛停靠站位置、行程時間、距離
  • 每個停靠站之間的路線折線路徑。

本文件說明應用程式與 API 的整合步驟。

必要條件

  • 您必須使用 Alpha 版執行 Android 應用程式 DriverSDK v4.1.0 以上版本。Alpha 版已可使用 使用 transportation-driver-alpha 建立 Maven artifactId。
  • API 使用 Fleet Engine 透過 Deliveries API。可透過 DriverSDK 上的 API 提供。 (DeliveryDriverApi)，或是直接下載至 Fleet Engine。

整合步驟

本節介紹整合 Android 驅動程式應用程式所需的基本步驟 與 API 互動這些操作說明的假設如下：

  • 您目前有一個 Android 應用程式，已經與 驅動程式 SDK
  • 您已根據結構定義，在應用程式中初始化 DeliveryDriverApi Kubernetes 物件

詳情請見 開始使用 Android 適用的 Driver 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 會在 停用狀態以避免不必要的網路頻寬用量。

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