Route Overview API は、DriverSDK 上に構築されたラスト ワンマイルのフリート ソリューション プロダクトです。これを使用すると、特定の車両のルート情報を 1 回限りの取得として取得できます。また、更新用のリスナーを使用して継続的に取得することもできます。Route Overview API は、次の種類の情報をサポートしています。
- 車両の停車場所、移動時間、距離を含む完全なルート計画
- 各駅 / 停留所間のルートのポリラインのパス。
このドキュメントでは、アプリケーション用の API との統合手順について説明します。
前提条件
- DriverSDK v4.1.0 以降の alpha チャンネルを使用して Android アプリを実行している必要があります。アルファ版チャンネルを使用するには、Maven artifactId に
transportation-driver-alpha
を使用します。 - この API は、Deliveries API を介して Fleet Engine から提供されるルート情報を使用します。これは、DriverSDK の API(
DeliveryDriverApi
)を介して提供することも、Fleet Engine に直接提供することもできます。
統合の手順
このセクションでは、Android ドライバアプリを API と統合するために必要な基本的な手順について説明します。この手順では、次のことを前提としています。
- Driver SDK とすでに統合されている既存の Android アプリがある
- アプリ内の
DeliveryDriverApi
をコンテキスト オブジェクトで初期化している。
詳細については、Driver SDK for Android のスタートガイドをご覧ください。
ステップ 0 - ルートの設定
Fleet Engine がすでに設定されていて、車両の停車場所と配達タスクを作成できる場合は、この手順をスキップできます。
停車地とタスクの情報を Fleet Engine に読み込むには、有効なルートに割り当てられている配達車両が必要です。これは、Route Overview API でデータを取得するには有効なルートが必要なためです。有効なルートは一連のウェイポイントと停車地で構成され、停車地は 1 つ以上のタスクが関連付けられている場合にのみ存在できます。詳細については、Fleet Engine API 統合ガイドをご覧ください。
ステップ 1 - API を初期化する
関連する停車地とタスクを含む有効なルートを確立したら、Route Overview API を初期化できます。初期化により、Fleet Engine と API 間の接続に必要なフレームワークが提供されます。Route 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 - ルート スナップショットを取得する
アプリで 1 回限りの呼び出しを発行して現在のルート情報のスナップショットを取得する場合は、次の方法でそのデータを取得できます。
ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();
これは、イベント リスナーでルートの更新情報をサブスクライブする代わりに行えます。
ステップ 6 - クリーンアップ
アプリでルートの概要機能が不要になった場合は、クリーンアップする必要があります。クリーンアップにより、アプリでの不要なメモリ、処理、ネットワークの消費を回避できます。
特定のイベント リスナーを削除する
特定のリスナーが不要になった場合は、イベント リスナーを削除する必要があります。
vehicleRouteOverview.removeOnRouteChangedEventListener(listener);
すべてのイベント リスナーを消去する
クリーンアップ ルーティンの一環として、登録されたさまざまなイベント リスナーを一度にすべて削除できます。
vehicleRouteOverview.clearEventListeners();
Route Overview API インスタンスを消去
Route Overview が不要になった場合や、追跡している車両の ID が変更された場合は、この API を呼び出して内部参照を消去できます。
vehicleRouteOverview.clearInstance();