API Route Overview

Ce produit ou cette fonctionnalité est en phase expérimentale (pré-DG). La prise en charge des fonctionnalités et produits pré-DG peut être limitée, et il se peut que les modifications apportées à ces fonctionnalités ou produits ne soient pas compatibles avec d'autres versions pré-DG. Les offres en pré-DG sont couvertes par les Conditions spécifiques du service Google Maps Platform. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Important :L'API Route Overview n'est actuellement disponible que sur Android.

L'API Route Overview est un produit de solution Last Mile Fleet basé sur le DriverSDK. Vous pouvez ainsi récupérer les informations sur l'itinéraire d'un véhicule donné, soit en tant que récupération unique, soit en continu à l'aide d'un écouteur pour les mises à jour. L'API Route Overview accepte les types d'informations suivants:

• Plan complet de l'itinéraire, y compris l'emplacement des arrêts des véhicules, les temps de trajet et les distances
• Trajet de la polyligne d'itinéraire entre chaque arrêt.

Ce document décrit les étapes d'intégration à l'API pour votre application.

Conditions préalables

• Vous devez exécuter votre application Android à l'aide du canal alpha de DriverSDK 4.1.0 ou version ultérieure. Le canal alpha est disponible en utilisant transportation-driver-alpha comme ID de l'artefact Maven.
• L'API utilise les informations de routage fournies par Fleet Engine via l'API Deliveries. Ces informations peuvent être fournies via les API sur DriverSDK (DeliveryDriverApi) ou directement à Fleet Engine.

Étapes d'intégration

Cette section décrit les étapes de base nécessaires pour intégrer votre application pilote Android à l'API. Ces instructions reposent sur les hypothèses suivantes:

• Vous disposez d'une application Android existante qui est déjà intégrée au SDK Driver
• Vous avez initialisé DeliveryDriverApi dans votre application avec un objet de contexte que vous pouvez trouver

Pour en savoir plus, consultez Premiers pas avec le SDK Driver pour Android.

Étape 0 : Configurer le routage

Vous pouvez ignorer cette étape si vous avez déjà configuré Fleet Engine et que vous pouvez créer des arrêts de véhicule et des tâches de livraison.

Pour charger les informations sur les arrêts et les tâches dans Fleet Engine, vous devez disposer d'un véhicule de livraison affecté à un itinéraire valide. En effet, l'API Route Overview a besoin d'itinéraires valides pour récupérer des données. Les itinéraires valides sont composés d'une série de points de cheminement et d'arrêts. Un arrêt ne peut exister que s'il est associé à au moins une tâche. Consultez le guide d'intégration de l'API Fleet Engine pour plus d'informations.

Étape 1 : Initialiser l'API

Une fois que vous avez établi un itinéraire valide avec les arrêts et les tâches associés, vous pouvez initialiser l'API Route Overview. L'initialisation fournit le framework nécessaire à la connexion entre Fleet Engine et l'API. L'API Route Overview doit être initialisée avec le même objet de contexte que celui utilisé pour initialiser DeliveryDriverApi dans DriverSDK, car l'objet fait référence au même ID de véhicule défini précédemment dans votre objet DriverContext. L'exemple suivant montre comment créer une instance de RouteOverviewApi.

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

Remarque :Lorsque vous initialisez l'API Route Overview, elle est automatiquement désactivée pour éviter de consommer inutilement de la bande passante pendant la configuration.

Étape 2 : Enregistrer le véhicule pour les événements de modification d'itinéraire

Maintenant que vous avez initialisé l'API, vous pouvez utiliser l'objet VehicleRouteOverview pour interagir avec les fonctionnalités de présentation de l'itinéraire. Cela permet à votre application d'utiliser les informations de routage que vous avez fournies lors de la configuration du routage. Utilisez l'écouteur d'événements de l'API pour faciliter la mise à jour des événements et la récupération des routes.

Un événement de modification d'itinéraire se produit chaque fois que le chemin vers l'un des arrêts attribués au véhicule est mis à jour, qu'un arrêt est réorganisé ou que Fleet Engine met à jour les informations sur l'heure d'arrivée prévue.

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

Étape 3 : Activez l'API

Maintenant que vous êtes prêt à utiliser les informations sur les itinéraires, vous devez activer l'API pour l'autoriser à répondre aux événements de véhicule. N'oubliez pas que l'API est initialisée dans un état désactivé afin d'éviter une consommation inutile de bande passante réseau.

vehicleRouteOverview.setRouteOverviewEnabled(true);

Vous pouvez suspendre ces mises à jour à tout moment en appelant la même méthode avec la valeur false.

Étape 4 : Tracez l'itinéraire sur une carte Google Maps

Une fois que vous avez obtenu la liste des éléments RouteToVehicleStop, vous pouvez l'utiliser dans votre application. Par exemple, vous pouvez dessiner le tracé d'une polyligne d'itinéraire dans une instance de carte Google Maps. L'extrait de code suivant montre un exemple qui dessine la polyligne d'itinéraire sur la vue plan et ajoute des repères au-dessus de chaque emplacement d'arrêt.

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

Vous obtenez un affichage semblable à la capture d'écran de droite:

Étape 5 : Obtenez un instantané de route

Si vous souhaitez que votre application émette un appel unique pour récupérer un instantané des informations de l'itinéraire actuel, vous pouvez utiliser la méthode suivante pour récupérer ces données:

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

Vous pouvez le faire au lieu de vous abonner aux mises à jour des routes via des écouteurs d'événements.

Étape 6 : Effectuez un nettoyage

Si votre application n'a plus besoin de la fonctionnalité d'aperçu des routes, assurez-vous d'avoir effectué un nettoyage. Ce nettoyage évite des opérations de mémoire, de traitement et de consommation réseau inutiles dans votre application.

Supprimer un écouteur d'événements spécifique

Vous devez supprimer un écouteur d'événements lorsqu'un écouteur spécifique n'est plus nécessaire.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Effacer tous les écouteurs d'événements

Dans le cadre de votre routine de nettoyage, vous pouvez supprimer simultanément tous les différents écouteurs d'événements enregistrés.

vehicleRouteOverview.clearEventListeners();

Effacer l'instance de l'API Route Overview

Chaque fois que vous n'avez plus besoin de la présentation de l'itinéraire ou que l'identifiant du véhicule suivi a changé, vous pouvez appeler cette API pour effacer les références internes.

vehicleRouteOverview.clearInstance();