API für Routenübersicht

Die Route Übersicht API ist eine Last Mile Fleet-Lösung, die auf dem DriverSDK basiert. Damit können Sie Routeninformationen für ein bestimmtes Fahrzeug abrufen – entweder einmalig oder kontinuierlich, indem Sie einen Listener für Aktualisierungen verwenden. Die Route Übersichts-API unterstützt die folgenden Arten von Informationen:

  • Vollständiger Routenplan, einschließlich Haltestellenpositionen, Fahrtzeiten und Entfernungen
  • Der Polylinienpfad der Route zwischen den einzelnen Haltestellen.

In diesem Dokument werden die Schritte zur Integration der API für Ihre Anwendung beschrieben.

Voraussetzungen

  • Sie müssen Ihre Android-Anwendung mit dem Alphakanal des DriverSDK 4.1.0 oder höher ausführen. Der Alphakanal ist verfügbar, wenn Sie transportation-driver-alpha für die Maven-Artefakt-ID verwenden.
  • Die API verarbeitet Routeninformationen, die von Fleet Engine über die Deliveries API bereitgestellt werden. Dies kann entweder über die APIs im DriverSDK (DeliveryDriverApi) oder direkt in der Fleet Engine erfolgen.

Integrationsschritte

In diesem Abschnitt werden die grundlegenden Schritte beschrieben, die erforderlich sind, um deine Android-Treiber-App in die API einzubinden. In dieser Anleitung wird von folgenden Annahmen ausgegangen:

  • Sie haben eine Android-App, in die das Driver SDK bereits integriert ist.
  • Sie haben das DeliveryDriverApi in Ihrer App mit einem Kontextobjekt initialisiert, das Sie finden können.

Weitere Informationen finden Sie unter Erste Schritte mit dem Driver SDK for Android.

Schritt 0 – Einrichtung der Route

Sie können diesen Schritt überspringen, wenn Sie Fleet Engine bereits eingerichtet haben und Fahrzeughalte und Lieferaufgaben erstellen können.

Zum Laden der Haltestellen- und Aufgabeninformationen in Fleet Engine benötigen Sie ein Lieferfahrzeug, das einer gültigen Route zugewiesen ist. Das liegt daran, dass die Route overview API gültige Routen erfordert, um Daten abzurufen. Gültige Routen bestehen aus einer Reihe von Wegpunkten und Haltestellen. Eine Haltestelle kann nur vorhanden sein, wenn ihr mindestens eine Aufgabe zugeordnet ist. Weitere Informationen finden Sie in der Integrationsanleitung für die Fleet Engine API.

Schritt 1 – API initialisieren

Nachdem Sie eine gültige Route mit zugehörigen Haltestellen und Aufgaben erstellt haben, können Sie die Route Survey API initialisieren. Die Initialisierung stellt das Framework bereit, das für die Verbindung zwischen Fleet Engine und der API erforderlich ist. Die Route Overview API sollte mit demselben Kontextobjekt initialisiert werden, das du zum Initialisieren von DeliveryDriverApi im DriverSDK verwendet hast, da das Objekt auf dieselbe Fahrzeug-ID verweist, die zuvor im DriverContext-Objekt definiert wurde. Das folgende Beispiel zeigt, wie eine Instanz von RouteOverviewApi erstellt wird.


RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

Schritt 2: Fahrzeug für Routenänderungsereignisse registrieren

Nachdem Sie die API initialisiert haben, können Sie das VehicleRouteOverview-Objekt verwenden, um mit Funktionen der Routenübersicht zu interagieren. Dadurch kann Ihre Anwendung die Routeninformationen nutzen, die Sie während der Routeneinrichtung angegeben haben. Verwenden Sie den API-Event-Listener, um Ereignisaktualisierungen und den Routenabruf zu vereinfachen.

Ein Routenänderungsereignis tritt auf, wenn der Pfad zu einer der dem Fahrzeug zugewiesenen Haltestellen aktualisiert wird, eine Haltestelle neu angeordnet wird oder wenn Fleet Engine die ETA-Informationen aktualisiert.


vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

Schritt 3: API aktivieren

Jetzt, wo du Routeninformationen abrufen kannst, musst du die API aktivieren, damit sie auf Fahrzeugereignisse reagieren kann. Die API wird deaktiviert initialisiert, um einen unnötigen Verbrauch von Netzwerkbandbreite zu vermeiden.

vehicleRouteOverview.setRouteOverviewEnabled(true);

Sie können diese Aktualisierungen jederzeit pausieren, indem Sie dieselbe Methode mit dem Wert false aufrufen.

Schritt 4: Route auf einer Google Maps-Karte zeichnen

Nachdem Sie eine Liste mit RouteToVehicleStops erhalten haben, können Sie sie in Ihrer Anwendung verwenden. Sie können beispielsweise den Polylinienpfad der Route in einer Google Maps-Instanz zeichnen. Das folgende Code-Snippet zeigt ein Beispiel, bei dem die Routenpolygone in der Kartenansicht gezeichnet und über jeder Haltestellenposition Markierungen hinzugefügt werden.

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

Screenshot der Routenübersicht

Das Ergebnis ist eine Ansicht ähnlich dem Screenshot rechts:

Schritt 5: Routen-Snapshot abrufen

Wenn Ihre Anwendung einen einmaligen Aufruf zum Abrufen eines Snapshots der aktuellen Routeninformationen ausgeben soll, können Sie diese Daten mit der folgenden Methode abrufen:

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

Das ist auch möglich, anstatt Routenaktualisierungen über Event-Listener zu abonnieren.

Schritt 6 – Bereinigung

Wenn Ihre App die Funktion „Routenübersicht“ nicht mehr benötigt, sollten Sie eine Bereinigung durchführen. Durch die Bereinigung vermeiden Sie unnötigen Arbeitsspeicher-, Verarbeitungs- und Netzwerkverbrauch in Ihrer Anwendung.

Bestimmten Event-Listener entfernen

Sie sollten einen Event-Listener entfernen, wenn ein bestimmter Listener nicht mehr benötigt wird.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Alle Event-Listener löschen

Im Rahmen der Bereinigung können Sie alle registrierten Ereignis-Listener gleichzeitig entfernen.

vehicleRouteOverview.clearEventListeners();

Löschung der Route Summary API-Instanz

Wenn die Routenübersicht nicht mehr benötigt wird oder sich die ID des verfolgten Fahrzeugs geändert hat, können Sie diese API aufrufen, um interne Verweise zu löschen.

vehicleRouteOverview.clearInstance();