Premiers pas avec Fleet Engine pour optimiser les performances du parc

Modélisez les activités de votre parc pour le premier et le dernier kilomètre de livraisons à l'aide de l'API Fleet Engine Deliveries. Vous pouvez utiliser cette API à l'aide du SDK Driver pour Android et iOS, ou directement à l'aide d'appels HTTP REST ou gRPC.

Configuration initiale

Vous configurez l'API Fleet Engine Deliveries dans la console Google Cloud.

Vérifier votre configuration

Une fois les comptes de service créés, vérifiez que la configuration est terminée et que vous pouvez créer un véhicule de livraison. En validant immédiatement votre configuration, vous vous assurez que vous avez résolu les problèmes d'autorisation courants pouvant survenir lors de la configuration de votre projet. Il existe deux façons de vérifier votre configuration:

Bibliothèques clientes

Pour améliorer l'expérience des développeurs avec gRPC ou REST brut, utilisez les bibliothèques clientes dans plusieurs langages de programmation courants. Pour savoir comment obtenir des bibliothèques clientes pour votre application serveur, consultez la page Bibliothèques clientes.

Les exemples Java de cette documentation supposent que vous connaissez gRPC.

Structures de données

L'API Fleet Engine Deliveries utilise deux structures de données pour modéliser le retrait et la livraison des expéditions:

  • Véhicule de livraison utilisé pour transporter le colis.
  • Les tâches de retrait et de livraison des envois.

Vous pouvez également utiliser des tâches pour modéliser les pauses et les arrêts planifiés tout au long de la journée.

Véhicules de livraison

Les véhicules de livraison transportent les envois d'un dépôt à un lieu de livraison, et d'un lieu de retrait au dépôt. Dans certains cas, ils peuvent également transporter un colis directement du lieu de retrait au lieu de livraison.

Utilisez le SDK Driver pour créer un objet DeliveryVehicle dans Fleet Engine et envoyer des mises à jour de position pour l'expédition et le suivi de la flotte.

Remarque: Vous pouvez attribuer jusqu'à 500 tâches et 300 segments de trajet de véhicule restants à des objets DeliveryVehicle.

Tâches

Pour les actions effectuées par un véhicule au cours de la journée, vous attribuez des tâches en fonction du type d'action:

  • Pour les retraits et les livraisons, attribuez des tâches de livraison.
  • Pour les moments où les conducteurs ne sont pas disponibles, comme les pauses obligatoires, attribuez des tâches d'indisponibilité.
  • Pour les tâches non liées aux véhicules dans des boîtes de dépôt ou des sites client, attribuez des tâches d'arrêt planifiées.

Chaque tâche que vous attribuez doit avoir un ID de tâche unique, mais les tâches peuvent partager le même ID de suivi. Lorsque Fleet Engine calcule les périodes de suivi de l'heure d'arrivée prévue pour chaque tâche, il utilise toutes les tâches et l'ordre dans lequel elles sont planifiées pour effectuer des estimations. Pour en savoir plus sur les ID de tâche, consultez les consignes relatives aux ID de tâche.

Pour créer des tâches dans Fleet Engine, utilisez le gestionnaire de tâches du SDK pilote.

Tâches d'expédition

Créez des tâches d'expédition pour le retrait et la livraison d'un envoi, et incluez les informations suivantes:

  • Lieu de retrait ou de livraison.
  • Un numéro de suivi ou un ID
  • Durée de présence pour prendre en compte le temps supplémentaire nécessaire pour effectuer la tâche, rechercher une place de stationnement ou marcher jusqu'au lieu de transfert.
  • ID de tâche unique. Consultez les consignes relatives à l'ID de tâche.

Pour plus d'informations, consultez les articles suivants :

Android

iOS

Tâches liées à l'indisponibilité

Les tâches liées à l'indisponibilité couvrent les périodes pendant lesquelles un véhicule n'est pas disponible pour le retrait ou la livraison (par exemple, les pauses pour faire le plein ou les pauses du conducteur).

Créez une tâche d'indisponibilité avec les informations suivantes:

  • Durée de la coupure.
  • L'emplacement de la coupure (facultatif) Vous n'avez pas besoin de fournir d'emplacement spécifique, mais cela vous permet d'obtenir des intervalles d'arrivée prévue plus précis tout au long de la journée.

Pour plus d'informations, consultez les articles suivants :

Android

iOS

Tâches d'arrêt planifiées

Créez des tâches d'arrêt planifiées pour modéliser les arrêts qu'un véhicule de livraison doit effectuer. Par exemple, créez une tâche d'arrêt planifiée pour un arrêt planifié quotidien à un emplacement spécifique, indépendamment des autres livraisons ou retraits au même endroit. Vous pouvez également créer des tâches d'arrêt programmées pour les collectes effectuées à partir de boîtes de dépôt, pour modéliser les transferts entre véhicules, ou les arrêts dans des centres et points de service.

Pour plus d'informations, consultez les articles suivants :

Android

iOS

Consignes concernant l'ID de tâche

Lorsque vous créez des ID de tâche, suivez ces consignes relatives au contenu et au format:

  • Créer des ID de tâche uniques
  • N'exposez pas d'informations permettant d'identifier personnellement l'utilisateur ni de données en texte clair.
  • Utilisez des chaînes Unicode valides.
  • Utilisez 64 caractères au maximum.
  • N'incluez aucun des caractères ASCII suivants: "/", ":", "\", "?" ou "#".
  • Effectuez la normalisation en respectant le formulaire de normalisation Unicode C.

Voici quelques exemples d'ID de tâches corrects:

  • 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
  • e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
  • NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk

Le tableau suivant présente des exemples d'ID de tâches non compatibles:

ID de tâches non compatibles Motif
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 Non-respect des exigences en matière d'informations permettant d'identifier personnellement l'utilisateur et de caractères: virgules, points, deux-points et barres obliques.
JohnDoe-577b484da26f-Cupertino-SantaCruz Non-respect des exigences relatives aux informations permettant d'identifier personnellement l'utilisateur.
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a Non-respect des exigences en matière d'informations permettant d'identifier personnellement l'utilisateur et de caractères: espaces blancs, virgules et guillemets. Il doit comporter plus de 64 caractères.

Autres ressources

Pour connaître les champs spécifiques contenus dans chaque structure de données, consultez la documentation de référence de l'API pour DeliveryVehicle (gRPC, REST) et Task (gRPC, REST).

Cycle de vie d'un véhicule

L'objet DeliveryVehicle représente un véhicule de livraison du premier ou du dernier kilomètre. Vous créez un objet DeliveryVehicle à l'aide de la commande suivante:

  • ID du projet Google Cloud contenant le compte de service utilisé pour appeler les API Fleet Engine.
  • ID du véhicule appartenant au client.

Utilisez un ID unique pour chaque véhicule. Ne réutilisez pas un ID de véhicule, sauf s'il n'existe aucune tâche active pour le véhicule d'origine.

Fleet Engine supprime automatiquement les objets DeliveryVehicle qui n'ont pas été mis à jour à l'aide de UpdateDeliveryVehicle après sept jours. Pour vérifier si un véhicule existe:

  1. Appelez UpdateDeliveryVehicle.
  2. Si vous obtenez une erreur NOT_FOUND, appelez CreateDeliveryVehicle pour recréer le véhicule. Si l'appel renvoie un véhicule, vous pouvez toujours le mettre à jour.

Attributs du véhicule

L'entité DeliveryVehicle contient un champ répété de DeliveryVehicleAttribute. L'API ListDeliveryVehicles inclut un champ filter qui permet de limiter les entités DeliveryVehicle renvoyées à celles ayant les attributs spécifiés. DeliveryVehicleAttribute n'a aucune incidence sur le comportement de routage de Fleet Engine.

N'incluez pas d'informations permettant d'identifier personnellement l'utilisateur ni d'informations sensibles dans les attributs, car ce champ peut être visible par les utilisateurs.

Cycle de vie d'une tâche

Vous pouvez créer, mettre à jour et interroger des tâches dans Fleet Engine avec les interfaces gRPC ou REST de l'API Deliveries.

Un objet Task comporte un champ d'état pour suivre sa progression tout au long de son cycle de vie. Les valeurs passent de OPEN à CLOSED. Les tâches sont créées à l'état OUVERT, ce qui indique que:

  • La tâche n'a pas encore été attribuée à un véhicule de livraison.
  • Le véhicule de livraison n'est pas encore passé à l'arrêt attribué à la tâche.

Consignes concernant les tâches

Vous ne pouvez attribuer une tâche à un véhicule que lorsque celui-ci est à l'état OUVERT.

Pour annuler une tâche, supprimez-la de la liste des arrêts de véhicule, ce qui définit automatiquement son état sur CLOSED (FERMÉE).

Lorsque le véhicule de la tâche termine l'arrêt de la tâche:

  1. Définissez le champ de résultat de la tâche sur SUCCEEDED (Réussite) ou FAILED (ÉCHEC).

  2. Indiquez le code temporel de l'événement.

    La bibliothèque JavaScript Fleet Tracking indique ensuite le résultat de la tâche, et son état est automatiquement défini sur CLOSED (FERMÉE). Pour en savoir plus, consultez la page Suivre votre parc avec la bibliothèque de suivi de parc JavaScript.

Comme pour les véhicules, Fleet Engine supprime les tâches qui n'ont pas été mises à jour après sept jours. Si vous essayez de créer une tâche avec un ID qui existe déjà, il renvoie une erreur.

Remarque:Fleet Engine ne permet pas de supprimer explicitement une tâche. Le service supprime automatiquement les tâches au bout de sept jours sans mises à jour. Si vous souhaitez conserver les données de tâches pendant plus de sept jours, vous devez implémenter cette fonctionnalité vous-même.

Attributs de la tâche

L'entité Task contient un champ répété de TaskAttribute, qui peut avoir une valeur de l'un des trois types suivants: chaîne, nombre et valeur booléenne. L'API ListTasks inclut un champ filter qui permet de limiter les entités Task renvoyées à celles ayant les attributs spécifiés. Les attributs de tâche n'ont pas d'incidence sur le comportement de routage de Fleet Engine.

N'incluez pas d'informations permettant d'identifier personnellement l'utilisateur ni d'autres informations sensibles dans les attributs, car ces attributs peuvent être visibles par les utilisateurs.

Gérer le cycle de vie des véhicules et des tâches

Rappel: Votre système interne sert de source fiable des données que l'API Fleet Engine Deliveries améliore en votre nom.

Pour gérer le cycle de vie des véhicules et des tâches dans votre système, utilisez l'API Fleet Engine Deliveries pour créer, mettre à jour et suivre vos véhicules et leurs tâches associées.

Dans le même temps, l'application du pilote communique directement avec Fleet Engine pour mettre à jour les informations sur l'emplacement et l'itinéraire de l'appareil. Ce modèle permet à Fleet Engine de gérer efficacement la localisation en temps réel. Elle envoie la position directement à la bibliothèque de suivi, que vous pouvez ensuite utiliser pour informer les consommateurs sur l'état de leur commande.

Par exemple, supposons que vous ayez le scénario suivant:

  • Un chauffeur s'approche d'un arrêt de livraison. L'application de pilote envoie son emplacement à Fleet Engine.
  • Fleet Engine envoie la position de l'appareil à la bibliothèque de suivi, que votre application consommateur utilise pour alerter le consommateur de la proximité de son package.
  • Une fois que le livreur a terminé l'expédition, il clique sur le bouton "Expédition livrée" dans l'application du pilote.
  • L'action "Expédition livrée" envoie les informations à votre système backend, qui effectue les étapes de validation et de vérification de l'activité nécessaires.
  • Votre système confirme que la tâche a bien été exécutée comme RÉUSSITE et met à jour Fleet Engine à l'aide de l'API Deliveries.

Le schéma suivant illustre ces processus à un niveau générique. Il indique également la relation standard entre votre système, le client et Fleet Engine.

Schéma sur l'intégration de l'API Deliveries >

Gérer les jetons client

Les mises à jour d'emplacement provenant de l'application de pilote et envoyées directement à Fleet Engine nécessitent des jetons d'autorisation. Voici l'approche recommandée pour gérer les mises à jour du client vers Fleet Engine:

  1. Générez le jeton à l'aide du rôle de compte de service Utilisateur non approuvé Fleet Engine Delivery.

  2. Fournissez à l'application de pilote un jeton de portée limitée. Ce champ d'application ne lui permet de mettre à jour que la position de l'appareil dans Fleet Engine.

Cette approche garantit que les appels provenant d'appareils mobiles, considérés comme des environnements de faible confiance, respectent le principe du moindre privilège.

Autres rôles de compte de service

Si vous souhaitez autoriser les applications de pilote à effectuer des mises à jour Fleet Engine directes autres que celles limitées au rôle de Conducteur non approuvé, par exemple pour certaines modifications de tâches, vous pouvez utiliser le rôle Conducteur de confiance. Pour en savoir plus sur un modèle qui utilise le rôle de Conducteur de confiance, consultez la section Modèle de Conducteur de confiance.

Pour en savoir plus sur les utilisations des rôles de pilote non approuvés et approuvés, consultez la page Configurer un projet Cloud.

Modélisez une journée de travail

Le tableau suivant décrit à quoi pourrait ressembler une journée de travail pour les chauffeurs sur le premier ou le dernier kilomètre dans une entreprise de livraison et de logistique. Les détails de votre entreprise peuvent différer, mais vous pouvez voir comment modéliser une journée de travail.

TempsActivitéModélisation
Dans les 24 heures qui suivent le début de la journée Le coordinateur attribue les expéditions aux véhicules ou aux itinéraires de livraison. Vous pouvez créer à l'avance des tâches pour les livraisons, les retraits, les pauses et d'autres tâches dans Fleet Engine. Par exemple, vous pouvez créer une tâche de retrait du colis, une tâche de livraison de la livraison, une indisponibilité planifiée ou un arrêt planifié.

Attribuez des tâches à un véhicule une fois que l'ensemble des colis de livraison et l'ordre dans lequel ils doivent être livrés sont finalisés.
Début de journée Le conducteur commence la journée au dépôt en se connectant à son application. Initialisez l'API Delivery Driver. Créez le véhicule de livraison dans Fleet Engine si nécessaire.
Le chauffeur charge les colis sur le véhicule de livraison et scanne les colis. Si les tâches de livraison des livraisons n'ont pas été créées à l'avance, créez-en des tâches de livraison au moment de l'analyse.
Le conducteur confirme l'ordre des tâches à effectuer. S'ils n'ont pas été créés à l'avance, créez des tâches de retrait des colis, des indisponibilités planifiées et des arrêts planifiés.
Le conducteur quitte le dépôt et valide le nombre de tâches à effectuer. Attribuez toutes les tâches ou un sous-ensemble de tâches au véhicule en validant leur ordre d'exécution.
Le chauffeur livre un colis. Une fois arrivé à l'arrêt de livraison, effectuez les actions liées à l'arrivée d'un véhicule à un arrêt. Après avoir livré l'expédition, fermez la tâche de livraison et, éventuellement, l'état de l'expédition en magasin et d'autres méta-informations. Après avoir effectué toutes les tâches à l'arrêt et avant de commencer à rouler jusqu'au prochain arrêt, effectuez les opérations liées au véhicule termine un arrêt et au véhicule qui mène au prochain arrêt.
Le conducteur rencontre un véhicule d'alimentation pour transférer d'autres colis sur le véhicule de livraison. Le point de rendez-vous d'une correspondance entre les véhicules d'alimentation et de livraison doit être modélisé comme un arrêt programmé.

Après avoir transféré et analysé les livraisons, créez des tâches de livraison si ce n'est pas déjà fait. Modifiez ensuite l'ordre d'exécution des tâches en attribuant des tâches à un véhicule et en mettant à jour l'ordre des tâches.
Le conducteur reçoit une notification d'une demande de retrait. Après avoir accepté la demande de retrait, créez une tâche de retrait de livraison. Modifiez ensuite l'ordre d'exécution des tâches en attribuant des tâches à un véhicule et en mettant à jour l'ordre des tâches.
Midi Conducteur en train de déjeuner. Si un emplacement est associé à la tâche d'indisponibilité, traitez-la comme n'importe quelle autre tâche. Effectuez des actions liées à un véhicule arrivant à un arrêt, à un véhicule qui termine un arrêt ou à un véhicule qui mène à l'arrêt suivant.

Sinon, aucune autre action n'est requise avant la fin de la coupure. Supprimez la tâche en confirmant les tâches suivantes et restantes, puis en mettant à jour l'ordre des tâches.
Le chauffeur récupère un colis. Celui-ci est modélisé comme un arrêt de livraison. Effectuez des actions liées à l'arrivée d'un véhicule à un arrêt et à la fermeture d'une tâche. Vous pouvez éventuellement stocker l'état de la livraison ainsi que d'autres méta-informations. Après avoir effectué toutes les tâches à l'arrêt et avant de commencer à rouler jusqu'au prochain arrêt, effectuez les opérations liées au véhicule avec un arrêt terminé et au véhicule qui mène au prochain arrêt. Remarque: Pour que la facturation soit correcte, tous les retraits doivent être associés à une tâche de livraison. Si le retrait doit être livré à un autre endroit sur le même itinéraire que le chauffeur ce jour-là, nous vous recommandons de modéliser cette tâche de livraison comme toute autre tâche de livraison sur l'itinéraire. Si le chauffeur retourne le retrait au dépôt, nous vous recommandons de créer une tâche de livraison à la destination du dépôt.
Le conducteur s'arrête pour récupérer les colis dans une boîte de dépôt. Celui-ci est modélisé comme n'importe quel autre point de prise en charge. Effectuez des actions liées à l'arrivée d'un véhicule à un arrêt et à la fermeture d'une tâche. Une fois que vous avez effectué toutes les tâches à l'arrêt et commencé à circuler jusqu'au prochain arrêt, effectuez les opérations liées au véhicule termine un arrêt et au véhicule qui mène au prochain arrêt.
Le chauffeur reçoit une notification indiquant qu'un colis a été dérouté vers un autre lieu. Définissez l'état de la tâche de livraison d'expédition d'origine sur COMPLETED et créez une tâche de livraison pour le nouveau lieu de livraison. Pour en savoir plus, consultez la section Réacheminer un envoi.
Le chauffeur a tenté de livrer un colis, mais n'y est pas parvenu. La modélisation d'un arrêt de livraison est semblable à celle d'un arrêt de livraison réussi, indiquant que la tâche de livraison est terminée. Effectuez des actions liées à un véhicule arrivant à un arrêt. En cas d'échec de la livraison, fermez la tâche et, éventuellement, l'état de l'expédition en magasin et d'autres méta-informations. Après avoir effectué toutes les tâches à l'arrêt et avant de commencer à rouler jusqu'au prochain arrêt, effectuez les opérations liées au véhicule avec un arrêt terminé et au véhicule qui mène au prochain arrêt.
Le chauffeur a été informé qu'un colis serait mis en attente (et non livré). Une fois la notification reçue et confirmée, définissez l'état de la tâche sur COMPLETED.
Le livreur a été informé de la livraison d'un certain colis par la suite, ce qui a modifié la commande de livraison prévue. Mettez à jour l'ordre des tâches.
Le chauffeur choisit de livrer un colis dans le désordre. Mettez à jour l'ordre des tâches, puis procédez normalement.
Le chauffeur livre plusieurs colis au même endroit. La modélisation de ce paramètre est semblable à celle d'un arrêt de livraison par livraison unique. Une fois arrivé à l'arrêt, effectuez les actions liées à un véhicule arrivant à un arrêt. Après avoir livré chaque envoi, fermez chaque tâche et, éventuellement, l'état de l'expédition en magasin et d'autres méta-informations. Après avoir effectué toutes les tâches à l'arrêt et avant de commencer à rouler jusqu'au prochain arrêt, effectuez les opérations liées au véhicule avec un arrêt terminé et au véhicule qui mène au prochain arrêt.
Fin de journée Le chauffeur retourne au dépôt. Si le chauffeur retourne au dépôt avec des colis récupérés sur son trajet, vous devez également créer et fermer chaque colis en tant que tâche de livraison pour que la facturation soit correcte. Pour ce faire, modélisez le dépôt comme n'importe quel autre arrêt de livraison. Si le dépôt n'est pas utilisé comme arrêt de livraison, vous pouvez éventuellement le modéliser comme un arrêt planifié. La modélisation de l'arrêt permet aux chauffeurs de voir l'itinéraire vers le dépôt et d'afficher leur heure d'arrivée prévue.

Fonctionnement des mises à jour de la position

Pour optimiser les performances avec Fleet Engine, fournissez-lui un flux de mises à jour de la position des véhicules. Pour fournir ces mises à jour, procédez de l'une des façons suivantes:

  1. Utilisez l'option la plus simple pour le SDK Driver (Android, iOS).
  2. Utilisez du code personnalisé. Cette option est utile si les emplacements sont transmis via votre backend, ou si vous utilisez des appareils autres qu'Android ou iOS.

Quelle que soit la manière dont vous fournissez les mises à jour de la position des véhicules, votre backend est chargé de mettre à jour Fleet Engine lorsqu'un véhicule de livraison s'en route vers un arrêt (y compris le dépôt) et lorsqu'il arrive à un arrêt. Fleet Engine ne détecte pas ces événements automatiquement.

Arrêts des véhicules et lieux de livraison

Un arrêt de véhicule est celui où un véhicule de livraison effectue une tâche d'expédition ou une autre tâche. Il peut s'agir d'un point d'accès tel qu'un quai de chargement ou d'un lieu signalé par une route.

Le lieu de livraison est le lieu où le colis est livré ou récupéré. Aller et se rendre au lieu de livraison peut nécessiter un peu de marche depuis l'arrêt du véhicule.

Par exemple, lorsqu'un chauffeur livre un colis à un magasin d'un centre commercial, le véhicule de livraison s'arrête sur le parking du centre commercial près de l'entrée la plus proche. Il s'agit de l'arrêt du véhicule. Le chauffeur se rend ensuite à pied de l'arrêt du véhicule jusqu'à l'emplacement du magasin dans le centre commercial. Il s'agit du lieu de livraison.

Pour une expérience de suivi des livraisons optimale pour vos utilisateurs, réfléchissez à la manière dont les tâches de livraison sont attribuées aux arrêts des véhicules. N'oubliez pas que le nombre d'arrêts restants pour les tâches d'expédition est communiqué à l'utilisateur afin de l'aider à voir la progression de l'expédition.

Par exemple, si un chauffeur effectue plusieurs livraisons dans un même immeuble de bureaux, envisagez d'attribuer toutes les tâches de livraison à un seul arrêt de véhicule. Si chaque tâche de livraison est attribuée à son propre arrêt de véhicule, votre expérience de suivi des livraisons sera moins utile pour vos utilisateurs, car le suivi n'est disponible que lorsque le véhicule se trouve dans un nombre limité d'arrêts avant sa destination. Lorsque de nombreux arrêts sont effectués en peu de temps, l'utilisateur n'a pas beaucoup de temps à consacrer au suivi de la livraison.

Utiliser les SDK pour mobile

Avant d'appeler le SDK Driver, veillez à l'initialiser.

Initialiser l'API Delivery Driver

Avant d'initialiser l'API Delivery Driver dans le SDK Driver, veillez à initialiser le SDK Navigation. Ensuite, initialisez l'API Delivery Driver comme illustré dans l'exemple suivant:

static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";

NavigationApi.getNavigator(
   this, // Activity.
   new NavigatorListener() {
     @Override
     public void onNavigatorReady(Navigator navigator) {
       DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
         .setNavigator(navigator)
         .setProviderId(PROVIDER_ID)
         .setVehicleId(VEHICLE_ID)
         .setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
         .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
         .setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
         .setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
             Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
         .build));
     }
     @Override
     public void onError(int errorCode) {
       Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
     }
   });

Cas d'utilisation

Cette section explique comment utiliser l'API Deliveries pour modéliser des cas d'utilisation courants.

Identifiants d'entité uniques

Le format et la valeur des identifiants d'entité uniques utilisés dans les appels REST sont opaques pour Fleet Engine. Évitez d'utiliser des ID d'incrémentation automatique et assurez-vous qu'ils ne contiennent aucune information permettant d'identifier personnellement l'utilisateur, telle que le numéro de téléphone du conducteur.

Créer un véhicule

Vous pouvez créer un véhicule à partir du SDK Driver ou d'un environnement de serveur à l'aide de gRPC ou REST.

gRPC

Pour créer un véhicule, vous devez effectuer un appel CreateDeliveryVehicle à Fleet Engine. Utilisez l'objet CreateDeliveryVehicleRequest pour définir les attributs du nouveau véhicule de livraison. Notez que toute valeur spécifiée pour le champ Name est ignorée, conformément aux instructions de l'API pour les ID spécifiés par l'utilisateur. Vous devez utiliser le champ DeliveryVehicleId pour définir l'ID du véhicule.

Lorsque vous créez un DeliveryVehicle, vous pouvez éventuellement spécifier les champs suivants:

  • Attributs
  • LastLocation
  • Type

Ne définissez pas d'autres champs. Dans ce cas, Fleet Engine renvoie une erreur, car ces champs sont en lecture seule ou ne peuvent être mis à jour qu'avec un appel à UpdateDeliveryVehicle.

Pour créer un véhicule sans définir de champ facultatif, vous pouvez laisser le champ DeliveryVehicle non défini dans CreateDeliveryVehicleRequest.

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour créer un véhicule:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    String parent = "providers/" + PROJECT_ID;
    DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
      .addAttributes(DeliveryVehicleAttribute.newBuilder()
        .setKey("route_number").setValue("1"))  // Opaque to the Fleet Engine
      .build();

    // Vehicle request
    CreateDeliveryVehicleRequest createVehicleRequest =
      CreateDeliveryVehicleRequest.newBuilder()  // No need for the header
          .setParent(parent)
          .setDeliveryVehicleId(VEHICLE_ID)     // Vehicle ID assigned by the Provider
          .setDeliveryVehicle(vehicle)
          .build();

    // Error handling
    // If Fleet Engine does not have vehicle with that ID and the credentials of the
    // requestor pass, the service creates the vehicle successfully.

    try {
      DeliveryVehicle createdVehicle =
        deliveryService.createDeliveryVehicle(createVehicleRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

Pour créer un véhicule à partir d'un environnement de serveur, envoyez un appel HTTP REST à CreateDeliveryVehicle:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>

<id> est un identifiant unique attribué à un véhicule de livraison dans votre parc.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps POST représente l'entité DeliveryVehicle à créer. Vous pouvez spécifier les champs facultatifs suivants:

  • attributs
  • lastLocation
  • Type

Exemple de commande curl :

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
  "attributes": [{"key": "model", "value": "sedan"}],
  "lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM

Fleet Engine ignore le champ name de l'entité DeliveryVehicle, conformément aux instructions de l'API pour les ID spécifiés par l'utilisateur. Ne définissez pas d'autres champs. Dans ce cas, Fleet Engine renvoie une erreur, car ces champs sont en lecture seule ou ne peuvent être mis à jour qu'à l'aide d'un appel à UpdateDeliveryVehicle.

Pour créer un véhicule sans définir de champ, laissez le corps de la requête POST vide. Le véhicule nouvellement créé extrait ensuite un ID de véhicule à partir du paramètre deliveryVehicleId de l'URL POST.

Exemple de commande curl :

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}"

Créer une tâche de retrait d'expédition

Vous pouvez créer une tâche de retrait d'une livraison à partir du SDK Driver ou d'un environnement de serveur à l'aide de gRPC ou REST.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour créer une tâche de retrait de livraison:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour créer une tâche de retrait de livraison à partir d'un environnement de serveur, envoyez un appel HTTP REST à CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> est un identifiant unique pour la tâche. Il ne doit pas s'agir du numéro de suivi du colis. Si vous ne disposez pas d'ID de tâches dans votre système, vous pouvez générer un identifiant unique universel (UUID).

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité Task:

  • Champs obligatoires :

    ChampValeur
    Type Type.PICKUP
    state State.OPEN
    trackingId Numéro ou identifiant que vous utilisez pour suivre un envoi.
    plannedLocation Le lieu où la tâche doit être effectuée, dans ce cas le lieu de retrait du colis.
    taskDuration Durée prévue, en secondes, pour récupérer le colis au point retrait.

  • Champs facultatifs :

    ChampValeur
    targetTimeWindow Période pendant laquelle la tâche doit être terminée. Cela n'affecte pas le comportement de routage.
    attributs Liste d'attributs Task personnalisés. Chaque attribut doit avoir une clé unique.

Tous les autres champs de l'entité sont ignorés pour la création. Fleet Engine génère une exception si la requête inclut un deliveryVehicleId attribué. Vous attribuez des tâches à l'aide de UpdateDeliveryVehicleRequest. Pour en savoir plus, consultez Attribuer des tâches à un véhicule et UpdateDeliveryVehicleRequest.

Exemple de commande curl :

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "PICKUP",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Créer une tâche de livraison d'expédition

Créez une tâche de livraison des livraisons à partir du SDK Driver ou d'un environnement de serveur à l'aide de gRPC ou REST.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour créer une tâche de livraison:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour créer une tâche de livraison de livraison à partir d'un environnement de serveur à l'aide de gRPC ou REST, envoyez un appel HTTP REST à CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> est un identifiant unique pour la tâche. Il ne doit pas s'agir du numéro de suivi du colis. Si vous ne disposez pas d'ID de tâches dans votre système, vous pouvez générer un identifiant unique universel (UUID).

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité Task:

  • Champs obligatoires :

    ChampValeur
    Type Type.DELIVERY
    state State.OPEN
    trackingId Numéro ou identifiant que vous utilisez pour suivre un envoi.
    plannedLocation Lieu où la tâche doit être effectuée, dans ce cas le lieu de livraison de la livraison.
    taskDuration Délai prévu, en secondes, pour déposer le colis à l'adresse de livraison.

  • Champs facultatifs :

    ChampValeur
    targetTimeWindow Période pendant laquelle la tâche doit être terminée. Cela n'affecte pas le comportement de routage.
    attributs Liste d'attributs Task personnalisés. Chaque attribut doit avoir une clé unique.

Tous les autres champs de l'entité sont ignorés pour la création. Fleet Engine génère une exception si la requête inclut un deliveryVehicleId attribué. Vous attribuez des tâches à l'aide de UpdateDeliveryVehicleRequest. Pour en savoir plus, consultez Attribuer des tâches à un véhicule et UpdateDeliveryVehicleRequest.

Exemple de commande curl :

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "DELIVERY",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Tâches de création groupée

Vous pouvez créer un lot de tâches à partir d'un environnement de serveur à l'aide de gRPC ou REST.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour créer deux tâches, l'une pour une livraison et l'autre pour un retrait au même emplacement:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Delivery Task settings
Task deliveryTask = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("delivery-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8312508")  // Task ID assigned by the Provider
      .setTask(deliveryTask)      // Initial state
      .build();

// Pickup Task settings
Task pickupTask = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("pickup-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(pickupTask)        // Initial state
      .build();

// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;

// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
  BatchCreateTasksRequest.newBuilder()
      .setParent(parent)
      .addRequests(createDeliveryTaskRequest)
      .addRequests(createPickupTaskRequest)
      .build();

// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.

try {
  BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
    batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour créer une tâche de livraison et de retrait à partir d'un environnement de serveur, effectuez un appel HTTP REST à BatchCreateTasks:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité BatchCreateTasksRequest:

  • Champs obligatoires :

    ChampValeur
    requêtes Tableau<CreateTasksRequest>

  • Champs facultatifs :

    ChampValeur
    en-tête "DeliveryRequestHeader"

Chaque élément CreateTasksRequest dans requests doit transmettre les mêmes règles de validation qu'une requête CreateTask, à l'exception du fait que les champs parent et header sont facultatifs. S'ils sont définis, ils doivent être identiques à leurs champs respectifs dans l'élément BatchCreateTasksRequest de niveau supérieur. Consultez les sections Créer une tâche de retrait d'expédition et Créer une tâche de livraison pour connaître les règles de validation spécifiques à chacune d'elles.

Pour en savoir plus, consultez la documentation de référence de l'API pour BatchCreateTasks (gRPC, REST).

Exemple de commande curl :

# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "requests" : [
    {
      "taskId": "${DELIVERY_TASK_ID}",
      "task" : {
        "type": "DELIVERY",
        "state": "OPEN",
        "trackingId": "${DELIVERY_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    },
    {
      "taskId": "${PICKUP_TASK_ID}",
      "task" : {
        "type": "PICKUP",
        "state": "OPEN",
        "trackingId": "${PICKUP_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    }
  ]
}
EOM

Indisponibilité planifiée

Vous pouvez créer une tâche indiquant une indisponibilité (par exemple, pour les pauses du conducteur ou le ravitaillement d'un véhicule) à partir du SDK Driver, ou d'un environnement de serveur utilisant gRPC ou REST. Une tâche d'indisponibilité planifiée ne doit pas inclure d'ID de suivi. Vous pouvez, si vous le souhaitez, indiquer un lieu.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour créer une tâche d'indisponibilité:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String parent = "providers/" + PROJECT_ID;
    Task task = Task.newBuilder()
      .setType(Task.Type.UNAVAILABLE)
      .setState(Task.State.OPEN)
      .setTaskDuration(
        Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
      .build();

    // Task request
    CreateTaskRequest createTaskRequest =
      CreateTaskRequest.newBuilder()  // No need for the header
          .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
          .setTaskId("task-8241890")  // Task ID assigned by the Provider
          .setTask(task)              // Initial state
          .build();

    // Error handling
    // If Fleet Engine does not have task with that ID and the credentials of the
    // requestor pass, the service creates the task successfully.

    try {
      Task createdTask = deliveryService.createTask(createTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

Pour créer une tâche d'indisponibilité à partir d'un environnement de serveur, envoyez un appel HTTP REST à CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> est un identifiant unique pour la tâche. Si vous n'avez pas d'ID de tâche dans votre système, vous pouvez générer un identifiant unique universel (UUID).

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité Task:

  • Champs obligatoires :

    ChampValeur
    Type Type.UNAVAILABLE
    state State.OPEN
    taskDuration Durée de la coupure en secondes.

  • Champs facultatifs :

    ChampValeur
    plannedLocation Lieu de la coupure si elle doit être prise à un endroit spécifique.

Tous les autres champs de l'entité sont ignorés pour la création. Fleet Engine génère une exception si la requête inclut un deliveryVehicleId attribué. Vous attribuez des tâches à l'aide de UpdateDeliveryVehicleRequest. Pour en savoir plus, consultez Attribuer des tâches à un véhicule et UpdateDeliveryVehicleRequest.

Exemple de commande curl :

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "UNAVAILABLE",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "300s"
    }
    EOM

Arrêts planifiés

Vous pouvez créer une tâche d'arrêt planifiée à partir du SDK Driver, ou à partir d'un environnement de serveur utilisant gRPC ou REST. Une tâche d'arrêt planifiée ne peut pas inclure d'ID de suivi.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour créer une tâche d'arrêt planifiée:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.SCHEDULED_STOP)
  .setState(Task.State.OPEN)
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTrip(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour créer une tâche d'arrêt planifiée à partir d'un environnement de serveur, envoyez un appel HTTP REST à CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> est un identifiant unique pour la tâche. Si vous ne disposez pas d'ID de tâche dans votre système, vous pouvez générer un identifiant unique universel (UUID).

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité Task:

  • Champs obligatoires :

    ChampValeur
    Type Type.SCHEDULED_STOP
    state State.OPEN
    plannedLocation Emplacement de l'arrêt.
    taskDuration Durée prévue de l'arrêt, en secondes.

  • Champs facultatifs :

    • Aucun

Tous les autres champs de l'entité sont ignorés pour la création. Fleet Engine génère une exception si la requête inclut un deliveryVehicleId attribué. Vous attribuez des tâches à l'aide de UpdateDeliveryVehicleRequest. Pour en savoir plus, consultez Attribuer des tâches à un véhicule et UpdateDeliveryVehicleRequest.

Exemple de commande curl :

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "SCHEDULED_STOP",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "600s"
    }
    EOM

Définir une période cible

La fenêtre temporelle cible correspond à la valeur TimeWindow au cours de laquelle la tâche doit être terminée. Par exemple, si vous indiquez un délai de livraison aux destinataires, vous pouvez utiliser le créneau horaire cible de la tâche pour capturer cette fenêtre temporelle et générer des alertes ou analyser les performances post-trajet à l'aide du champ.

La fenêtre temporelle cible se compose d'une heure de début et d'une heure de fin, et peut être définie pour n'importe quel type de tâche. La fenêtre temporelle cible n'affecte pas le comportement du routage.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour définir une fenêtre de temps de tâche:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String TASK_ID = "task-8241890";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
    Task task = Task.newBuilder()
      .setName(taskName)
      .setTargetTimeWindow(
        TimeWindow.newBuilder()
          .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
          .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
      .build();

    // Task request
    UpdateTaskRequest updateTaskRequest =
      UpdateTaskRequest.newBuilder()  // No need for the header
          .setTask(task)
          .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
          .build();

    try {
      Task updatedTask = deliveryService.updateTask(updateTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case NOT_FOUND:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

Pour définir une fenêtre de temps de tâche à l'aide du protocole HTTP, appelez UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`

<id> est un identifiant unique pour la tâche.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité Task:

  • Champs obligatoires :

    ChampValeur
    targetTimeWindow Période pendant laquelle la tâche doit être terminée. Ce paramètre n'affecte pas le comportement de routage

  • Champs facultatifs :

    • Aucun

Tous les autres champs de l'entité sont ignorés pour la mise à jour.

Exemple de commande curl :

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Définir la configuration de la visibilité du suivi des tâches

La visibilité des données dans la bibliothèque Shipment Tracking et de celles renvoyées par un appel à GetTaskTrackingInfo peut être contrôlée pour chaque tâche en définissant un TaskTrackingViewConfig pour la tâche. Pour en savoir plus, consultez Tâches actives d'un véhicule. Vous pouvez le faire lors de la création ou de la mise à jour de la tâche. Voici un exemple de mise à jour de la tâche avec cette configuration:

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour définir la configuration de la vue de suivi des tâches:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}

REST

Pour définir la fenêtre de configuration de la vue de suivi des tâches à l'aide du protocole HTTP, appelez UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`

<id> est un identifiant unique pour la tâche.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité Task:

  • Champs obligatoires :

    ChampValeur
    taskTrackingViewConfig Configuration du suivi des tâches qui spécifie les éléments de données visibles par les utilisateurs finaux dans quelles circonstances.

  • Champs facultatifs :

    • Aucun

Tous les autres champs de l'entité sont ignorés pour la mise à jour.

Exemple de commande curl :

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

Attribuer des tâches à un véhicule

Pour attribuer des tâches à un véhicule de livraison, mettez à jour l'ordre des tâches pour le véhicule. L'ordre des tâches d'un véhicule est déterminé par la liste des arrêts du véhicule de livraison. Vous pouvez attribuer une ou plusieurs tâches à chaque arrêt du véhicule. Pour en savoir plus, consultez Mettre à jour l'ordre des tâches.

Pour modifier un envoi d'un véhicule à un autre, fermez la tâche d'origine, puis recréez-la avant de lui attribuer le nouveau véhicule. Si vous mettez à jour l'ordre des tâches pour une tâche déjà attribuée à un autre véhicule, un message d'erreur s'affiche.

Mettre à jour l'ordre des tâches

Vous pouvez mettre à jour les tâches attribuées à un véhicule à partir du SDK Driver ou de l'environnement du serveur. N'utilisez pas les deux méthodes pour éviter les conditions de concurrence et maintenir une source unique de vérité.

Lorsque vous modifiez l'ordre des tâches d'un véhicule, il effectue également les opérations suivantes:

  • Attribue les tâches nouvellement ajoutées au véhicule.
  • Ferme toutes les tâches précédemment attribuées au véhicule, mais qui ne figurent pas dans l'ordre mis à jour.

Pour modifier un envoi d'un véhicule à un autre, fermez la tâche d'origine, puis recréez-la avant de lui attribuer le nouveau véhicule. Si vous mettez à jour l'ordre des tâches pour une tâche déjà attribuée à un autre véhicule, un message d'erreur s'affiche.

Vous pouvez modifier l'ordre des tâches à tout moment.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour mettre à jour l'ordre des tâches du véhicule:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.NEW)))
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour mettre à jour l'ordre des tâches d'un véhicule à partir d'un environnement de serveur, envoyez un appel HTTP REST à UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> est un identifiant unique d'un véhicule de livraison de votre parc pour lequel vous souhaitez mettre à jour l'ordre des tâches. Il s'agit de l'identifiant que vous avez spécifié lors de la création du véhicule.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité DeliveryVehicle:

  • Champs obligatoires :

    ChampValeur
    remainingVehicleJourneySegments Une liste de segments de parcours pour les tâches dans l'ordre dans lequel elles doivent être exécutées. La première tâche de la liste est exécutée en premier.
    VehicleJourneySegments[i].stop restant[i] Point de la tâche i dans la liste.
    restantVehicleJourneySegments[i].stop.plannedLocation Emplacement prévu de l'arrêt.
    VehicleJourneySegments[i].stop.tasks restantes Liste des tâches à effectuer à cet arrêt du véhicule.
    remainingVehicleJourneySegments[i].stop.state State.NEW

  • Champs facultatifs :

    • Aucun

Tous les autres champs de l'entité sont ignorés pour la mise à jour.

Exemple de commande curl :

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Véhicule en route vers le prochain arrêt

Fleet Engine doit être averti lorsqu'un véhicule quitte un arrêt ou démarre la navigation. Vous pouvez envoyer une notification à Fleet Engine à partir du SDK pilote, ou depuis un environnement de serveur utilisant gRPC ou REST. N'utilisez pas les deux méthodes pour éviter les conditions de concurrence et maintenir une source unique de vérité.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque gRPC Java pour avertir Fleet Engine qu'un véhicule est en route vers son prochain arrêt.

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String VEHICLE_ID = "vehicle-8241890";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
        // Next stop marked as ENROUTE
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.7749)
                       .setLongitude(122.4194)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
               .setState(VehicleStop.State.ENROUTE)))
        // All other stops marked as NEW
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.3382)
                       .setLongitude(121.8863)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
               .setState(VehicleStop.State.NEW)))
        .build();

    // DeliveryVehicle request
    UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
      UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
          .setName(vehicleName)
          .setDeliveryVehicle(deliveryVehicle)
          .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
          .build();

    try {
      DeliveryVehicle updatedDeliveryVehicle =
          deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case NOT_FOUND:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

Pour avertir Fleet Engine qu'un véhicule est en route vers son prochain arrêt depuis un environnement de serveur, envoyez un appel HTTP REST à UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> est un identifiant unique du véhicule de livraison de votre parc pour lequel vous souhaitez mettre à jour l'ordre des tâches. Il s'agit de l'identifiant que vous avez spécifié lors de la création du véhicule.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité DeliveryVehicle:

  • Champ obligatoire:

    ChampValeur
    remainingVehicleJourneySegments Liste des arrêts de véhicule restants, dont les états sont marqués comme State.NEW. L'état du premier arrêt de la liste doit être State.ENROUTE.

  • Champs facultatifs :

    • Aucun

Tous les autres champs de l'entité sont ignorés pour la notification.

Exemple de commande curl :

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ENROUTE",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Mettre à jour la position du véhicule

Si vous n'utilisez pas le SDK Driver pour mettre à jour l'emplacement du véhicule, vous pouvez appeler directement Fleet Engine en indiquant sa position. Pour tout véhicule actif, Fleet Engine s'attend à une mise à jour de la position au moins une fois toutes les minutes et au maximum une fois toutes les cinq secondes.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour mettre à jour l'emplacement d'un véhicule dans Fleet Engine:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
    .setLastLocation(DeliveryVehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(myDeliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("last_location"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour mettre à jour l'emplacement d'un véhicule dans Fleet Engine à l'aide de HTTP REST, appelez UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`

<id> est un identifiant unique pour le véhicule de livraison de votre parc ou pour lequel vous souhaitez mettre à jour l'emplacement. Il s'agit de l'identifiant que vous avez spécifié lors de la création du véhicule.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité DeliveryVehicle:

  • Champ obligatoire:

    ChampValeur
    lastLocation.supplementalLocation L'emplacement du véhicule
    lastLocation.supplementalLocationTime Dernier horodatage connu du véhicule à cet endroit
    lastLocation.supplementalLocationSensor Doit être renseigné avec CUSTOMER_SUPPLIED_LOCATION.

  • Champs facultatifs :

    ChampValeur
    lastLocation.supplementalLocationAccuracy Précision de la position fournie, en mètres.

Exemple de commande curl :

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
  }
}
EOM

Le véhicule arrive à un arrêt

Fleet Engine doit recevoir une notification lorsqu'un véhicule arrive à un arrêt. Vous pouvez envoyer une notification à Fleet Engine à l'aide du SDK pilote ou d'un environnement de serveur utilisant gRPC ou REST. N'utilisez pas les deux méthodes pour éviter les conditions de concurrence et maintenir une source unique de vérité.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque gRPC Java pour avertir Fleet Engine qu'un véhicule est arrivé à l'arrêt:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Marking the arrival at stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour avertir Fleet Engine de l'arrivée d'un véhicule à un arrêt depuis un environnement de serveur, envoyez un appel HTTP REST à UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> est un identifiant unique du véhicule de livraison de votre parc pour lequel vous souhaitez mettre à jour l'ordre des tâches. Il s'agit de l'identifiant que vous avez spécifié lors de la création du véhicule.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité DeliveryVehicle:

  • Champs obligatoires :

    ChampValeur
    remainingVehicleJourneySegments Arrêt où vous êtes arrivé, dont l'état est défini sur State.ARRIVED, suivi de la liste des arrêts restants (dont les états sont indiqués) "State.NEW".

  • Champs facultatifs :

    • Aucun

Tous les autres champs de l'entité sont ignorés pour la mise à jour.

Exemple de commande curl :

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ARRIVED",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Le véhicule effectue un arrêt

Fleet Engine doit être averti lorsqu'un véhicule s'arrête. Toutes les tâches associées à l'arrêt sont alors définies sur l'état CLOSED. Vous pouvez notifier Fleet Engine à partir du SDK pilote ou d'un environnement de serveur à l'aide de gRPC ou REST. N'utilisez pas les deux méthodes pour éviter les conditions de concurrence et maintenir une source unique de vérité.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour avertir Fleet Engine qu'un véhicule a terminé un arrêt.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // This stop has been completed and is commented out to indicate it
    // should be removed from the list of vehicle journey segments.
    // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
    //    .setStop(VehicleStop.newBuilder()
    //        .setPlannedLocation(LocationInfo.newBuilder()
    //            .setPoint(LatLng.newBuilder()
    //                .setLatitude(37.7749)
    //                .setLongitude(122.4194)))
    //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
    //        .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    // The next stop could be marked as ENROUTE if the vehicle has begun
    // its journey to the next stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // no need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour avertir Fleet Engine qu'un arrêt s'est effectué à partir d'un environnement de serveur, envoyez un appel HTTP REST à UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`

<id> est un identifiant unique du véhicule de livraison de votre parc pour lequel vous souhaitez mettre à jour l'ordre des tâches. Il s'agit de l'identifiant que vous avez spécifié lors de la création du véhicule.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité DeliveryVehicle:

  • Champs obligatoires :

    ChampValeur
    remaining_vehicle_journey_segments L'arrêt que vous avez terminé ne doit plus figurer dans la liste des arrêts restants pour véhicules.

  • Champs facultatifs :

    • Aucun

Tous les autres champs de l'entité sont ignorés pour la mise à jour.

Exemple de commande curl :

    # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
    # environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "remainingVehicleJourneySegments": [
        {
          "stop": {
            "state": "NEW",
            "plannedLocation": {
              "point": {
                "latitude": 37.3382,
                "longitude": 121.8863
              }
            },
            "tasks": [
              {
                "taskId": "${TASK2_ID}"
              }
            ]
          }
        }
      ]
    }
    EOM

Mettre à jour une tâche

La plupart des champs de tâche sont immuables. Toutefois, vous pouvez modifier l'état, le résultat de la tâche, l'heure du résultat de la tâche, l'emplacement du résultat de la tâche et les attributs en mettant directement à jour l'entité de la tâche. Par exemple, si une tâche n'a pas été attribuée à un véhicule, vous pouvez la fermer en mettant directement à jour l'état.

gRPC

Voici un exemple de mise à jour d'une tâche via gRPC.

REST

Voici un exemple de mise à jour d'une tâche via REST.

Fermer une tâche

Pour fermer une tâche qui a été attribuée à un véhicule, informez Fleet Engine que le véhicule a terminé l'arrêt où la tâche a lieu ou supprimez-la de la liste des arrêts de véhicule. Pour ce faire, vous pouvez définir la liste des arrêts de véhicule restants, comme vous le feriez pour mettre à jour l'ordre des tâches d'un véhicule.

Si une tâche n'a pas encore de véhicule et doit être fermée, définissez-la sur CLOSED (FERMÉE). Toutefois, vous ne pourrez pas rouvrir une tâche FERMÉE.

La fermeture d'une tâche n'indique pas la réussite ou l'échec. Elle indique que la tâche n'est plus considérée comme en cours. Pour le suivi du parc, il est important d'indiquer le résultat réel d'une tâche afin d'afficher un résultat de livraison.

gRPC

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setState(Task.State.CLOSED) // You can only directly CLOSE a
  .build();                    // task that is NOT assigned to a vehicle.

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("state"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour marquer une tâche comme fermée depuis un environnement de serveur, envoyez un appel HTTP REST à UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`

<id> est un identifiant unique pour la tâche.

Votre en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Vous devez inclure une entité Task dans le corps de la requête:

  • Champs obligatoires :

    ChampValeur
    state State.CLOSED

  • Champs facultatifs :

    ChampValeur
    taskOutcome Outcome.SUCCEEDED ou Outcome.FAILED
    taskOutcomeTime Heure à laquelle la tâche a été terminée.
    taskOutcomeLocation Emplacement où la tâche a été effectuée. Fleet Engine utilise par défaut la dernière position du véhicule, sauf si le fournisseur le remplace manuellement.

Tous les autres champs de l'entité sont ignorés pour la mise à jour.

Exemple de commande curl :

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "state": "CLOSED",
      "taskOutcome": "SUCCEEDED",
      "taskOutcomeTime": "$(date -u --iso-8601=seconds)"
    }
    EOM

Définir le résultat de la tâche et son emplacement

La clôture d'une tâche n'indique pas sa réussite ni son échec, mais qu'elle n'est plus considérée comme en cours. Pour le suivi du parc, il est important d'indiquer le résultat réel d'une tâche afin qu'un résultat de livraison puisse être affiché et que les services soient correctement facturés. Une fois défini, vous ne pouvez plus modifier le résultat de la tâche. Vous pouvez toutefois modifier l'heure du résultat de la tâche et son emplacement après les avoir définis.

Le résultat des tâches à l'état FERMÉE peut être défini sur SUCCEEDED (SUCCÈS) ou FAILED (ÉCHEC). Fleet Engine ne facture que les tâches de livraison dont l'état est SUCCEEDED.

Lors du marquage du résultat d'une tâche, Fleet Engine remplit automatiquement l'emplacement du résultat de la tâche avec la dernière position connue du véhicule. Vous pouvez ignorer ce comportement.

gRPC

Vous avez la possibilité de définir l'emplacement du résultat de la tâche lorsque vous définissez le résultat. Définir l'emplacement empêche Fleet Engine de le définir sur la valeur par défaut du dernier emplacement du véhicule. Vous pouvez également écraser ultérieurement l'emplacement de résultat de la tâche défini par Fleet Engine. Fleet Engine n'écrase jamais un emplacement de résultat de tâche que vous indiquez. Vous ne pouvez pas définir d'emplacement de résultat pour une tâche dont le résultat n'est pas défini. Vous pouvez définir à la fois le résultat de la tâche et son emplacement dans la même requête.

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour définir un résultat de tâche sur SUCCEEDED et définir l'emplacement où la tâche a été effectuée:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskOutcome(TaskOutcome.SUCCEEDED)
  .setTaskOutcomeTime(now())
  .setTaskOutcomeLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour marquer une tâche comme terminée à partir d'un environnement de serveur, envoyez un appel HTTP REST à UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`

<id> est un identifiant unique pour la tâche.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit contenir une entité Task:

  • Champs obligatoires :

    ChampValeur
    taskOutcome Outcome.SUCCEEDED ou Outcome.FAILED
    taskOutcomeTime Code temporel du moment où le résultat de la tâche a été défini (à partir du fournisseur). Il s'agit de l'heure à laquelle la tâche a été terminée.

  • Champs facultatifs :

    ChampValeur
    taskOutcomeLocation Emplacement où la tâche a été effectuée. Fleet Engine utilise par défaut la dernière position du véhicule, sauf si le fournisseur le remplace manuellement.

Tous les autres champs de l'entité sont ignorés pour la mise à jour.

Exemple de commande curl :

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)",
  "taskOutcomeLocation": {
    "point": {
      "latitude": -6.195139,
      "longitude": 106.820826
    }
  }
}
EOM

Réacheminer un colis

Une fois qu'une tâche d'expédition a été créée, son emplacement planifié ne peut plus être modifié. Pour réacheminer un envoi, fermez la tâche d'expédition sans définir de résultat, puis créez une tâche avec le lieu planifié mis à jour. Après avoir créé la tâche, attribuez-la au même véhicule. Pour en savoir plus, consultez Fermer la tâche d'expédition et attribuer la tâche.

Utiliser des véhicules d'alimentation et de livraison

Si vous utilisez des véhicules d'actualisation pour transporter des envois vers des véhicules de livraison tout au long de la journée, modélisez le transfert des expéditions comme une tâche d'arrêt programmée pour le véhicule de livraison. Pour assurer un suivi précis de la position, n'attribuez une tâche de livraison à un colis transféré qu'après son chargement dans le véhicule de livraison. Pour en savoir plus, consultez la section Arrêt programmé.

État de la livraison en magasin et autres méta-informations

Lorsqu'une tâche d'expédition est terminée, l'état et le résultat de la tâche sont enregistrés dans la tâche. Toutefois, vous pouvez modifier d'autres méta-informations spécifiques à la livraison. Pour stocker d'autres méta-informations que vous pouvez référencer en dehors du service Fleet Engine, utilisez l'ID de suivi associé à la tâche comme clé dans une table externe.

Pour en savoir plus, consultez la section Déroulement du cycle de vie d'une tâche.

Rechercher un véhicule

Vous pouvez rechercher un véhicule à partir du SDK Driver, ou à partir d'un environnement de serveur à l'aide de gRPC ou REST.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour rechercher un véhicule:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder()  // No need for the header
    .setName(name)
    .build();

try {
  DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour rechercher un véhicule à partir d'un environnement de serveur, envoyez un appel HTTP REST à GetVehicle:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`

<id> est un identifiant unique pour la tâche.

<vehicleId> est l'identifiant du véhicule à rechercher.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit être vide.

Si la recherche aboutit, le corps de la réponse contient une entité de véhicule.

Exemple de commande curl :

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"

Rechercher une tâche

Vous pouvez rechercher une tâche à partir d'un environnement de serveur à l'aide de gRPC ou REST. Le SDK Driver ne permet pas de rechercher une tâche.

gRPC

L'exemple suivant montre comment rechercher une tâche à l'aide de la bibliothèque Java gRPC:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
    .setName(taskName)
    .build();

try {
  Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour rechercher une tâche à partir d'un environnement de serveur, envoyez un appel HTTP REST à GetTask:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`

<id> est un identifiant unique pour la tâche.

<taskId> est l'ID de la tâche à rechercher.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Le corps de la requête doit être vide.

Si la recherche aboutit, le corps de la réponse contient une entité de tâche.

Exemple de commande curl :

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

Rechercher les informations sur la tâche d'expédition à l'aide de son ID de suivi

Vous pouvez rechercher des informations sur les tâches du parc de différentes manières, chacune ayant un objectif distinct:

  • Par un ID de tâche: utilisé par les utilisateurs tels que les opérateurs de parc qui ont accès à l'affichage complet des données de tâche.
  • Par un ID de suivi: utilisé par votre logiciel client pour fournir des informations limitées à un utilisateur final (par exemple, quand un colis est attendu chez lui).

Cette section explique comment rechercher des informations sur une tâche à l'aide d'un ID de suivi. Si vous souhaitez rechercher une tâche à partir de son ID, consultez la section Rechercher une tâche.

Pour rechercher des informations à l'aide d'un ID de suivi, vous pouvez utiliser l'une des méthodes suivantes:

Exigences concernant la recherche

  • Les informations de livraison fournies par un ID de suivi respectent les règles de visibilité définies dans la section Contrôler la visibilité des établissements suivis.

  • Utilisez Fleet Engine pour rechercher des informations d'expédition par ID de suivi. Le SDK Driver n'est pas compatible avec les recherches d'informations par ID de suivi. Pour ce faire, avec Fleet Engine, vous utilisez soit un environnement de serveur, soit un environnement de navigateur.

  • Utilisez le jeton le plus étroit possible pour limiter les risques de sécurité. Par exemple, si vous utilisez un jeton de client de livraison, les appels de l'API Fleet Engine Deliveries ne renvoient que les informations pertinentes pour cet utilisateur final, comme le transporteur ou le destinataire d'une livraison. Toutes les autres informations contenues dans les réponses sont masquées. Pour en savoir plus sur les jetons, consultez la page Créer un jeton Web JSON (JWT) pour l'autorisation.

Recherches avec Java à l'aide de gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour rechercher des informations sur une tâche de livraison par son ID de suivi.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Recherches utilisant HTTP

Pour rechercher une tâche de livraison dans un navigateur, envoyez un appel HTTP REST à GetTaskTrackingInfo:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`

<tracking_id> est l'identifiant de suivi associé à la tâche.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Si la recherche aboutit, le corps de la réponse contient une entité taskTrackingInfo.

Exemple de commande curl :

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

Répertorier les tâches

Vous pouvez répertorier les tâches à partir d'un serveur ou d'un environnement de navigateur. Le SDK Driver n'est pas compatible avec l'établissement de listes de tâches.

L'affichage d'une liste de tâches nécessite un accès étendu aux tâches. L'affichage de la liste des tâches est destiné uniquement aux utilisateurs de confiance. Utilisez des lecteurs de parc de livraison ou des jetons d'authentification de super-utilisateur de livraison lorsque vous effectuez des requêtes de liste de tâches.

Les champs suivants sont masqués pour les tâches répertoriées:

  • VehicleStop.planned_location
  • VehicleStop.state
  • VehicleStop.TaskInfo.taskId

Les tâches répertoriées peuvent être filtrées selon la plupart des propriétés de tâche. Pour connaître la syntaxe des requêtes de filtre, consultez la section AIP-160. La liste suivante présente les propriétés de tâche valides que vous pouvez utiliser pour le filtrage:

  • attributs
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_outcome
  • task_outcome_location
  • task_outcome_location_source
  • task_outcome_time
  • tracking_id
  • Type

Utilisez les formats de champ suivants en fonction des propositions d'amélioration de l'API Google:

Type de champ Format Exemple
Code temporel RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Durée Nombre de secondes suivies d'un s task_duration = 120s
Enum Chaîne state = CLOSED AND type = PICKUP
Emplacement point.latitude et point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Consultez la page AIP-160 pour obtenir la liste complète des opérateurs de requête de filtre.

Si aucune requête de filtre n'est spécifiée, toutes les tâches sont répertoriées.

Les listes de tâches sont paginées. Une taille de page peut être spécifiée dans les requêtes de liste de tâches. Si une taille de page est spécifiée, le nombre de tâches renvoyées n'est pas supérieur à la taille de page spécifiée. Si aucune taille de page n'est indiquée, une valeur par défaut raisonnable est utilisée. Si la taille de page demandée dépasse une valeur interne maximale, la valeur maximale interne est utilisée.

Une liste de tâches peut inclure un jeton permettant de lire la page de résultats suivante. Utilisez le jeton de page avec une requête identique à la précédente pour récupérer la page de tâches suivante. Lorsque le jeton de page renvoyé est vide, plus aucune tâche n'est disponible pour la récupération.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour répertorier les tâches pour un deliveryVehicleId et un attribut de tâche. Une réponse réussie peut toujours être vide. Une réponse vide indique qu'aucune tâche n'est associée à l'ID de livraison de véhicule fourni.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
    .build();

try {
  ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Pour répertorier les tâches à partir d'un navigateur, envoyez un appel HTTP REST à ListTasks:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`

Pour appliquer un filtre aux tâches listées, incluez un paramètre d'URL "filter" avec une requête de filtre avec échappement comme valeur.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Si la recherche aboutit, le corps de la réponse contient des données présentant la structure suivante:

    // JSON representation
    {
      "tasks": [
        {
          object (Task)
        }
      ],
      "nextPageToken": string,
      "totalSize": integer
    }

Une réponse positive peut toujours être vide. Une réponse vide indique qu'aucune tâche ne correspond aux critères de filtre spécifiés.

Exemple de commande curl :

    # Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

Lister les véhicules de livraison

Vous pouvez lister les véhicules de livraison à partir d'un serveur ou d'un environnement de navigateur. Le SDK pour les conducteurs ne permet pas de lister les véhicules de livraison.

L'affichage de la liste des véhicules de livraison nécessite un accès étendu aux véhicules de livraison et est destiné uniquement aux utilisateurs de confiance. Utilisez le lecteur de parc de livraison ou les jetons d'authentification de super-utilisateur de livraison lorsque vous effectuez des requêtes de liste de véhicules de livraison.

Les champs suivants sont masqués pour les véhicules de livraison répertoriés en raison de leur impact sur la taille des réponses:

  • CurrentRouteSegment
  • RemainingVehicleJourneySegments

Vous pouvez filtrer la liste des véhicules de livraison en fonction de leur propriété attributes. Par exemple, pour interroger un attribut avec la clé my_key et la valeur my_value, utilisez attributes.my_key = my_value. Pour interroger plusieurs attributs, joignez les requêtes à l'aide des opérateurs logiques AND et OR, comme dans attributes.key1 = value1 AND attributes.key2 = value2. Consultez la page AIP-160 pour obtenir une description complète de la syntaxe des requêtes de filtre.

Vous pouvez filtrer les véhicules de livraison répertoriés par emplacement à l'aide du paramètre de requête viewport. Le paramètre de requête viewport définit les fenêtres d'affichage à l'aide de deux coordonnées de délimitation: une paire de coordonnées de latitude et de longitude high (nord-est) et low (sud-ouest). Les requêtes sont rejetées si elles contiennent une haute latitude géographiquement inférieure à une latitude basse.

Par défaut, les listes des véhicules de livraison sont paginées sur une taille de page raisonnable. Si vous spécifiez une taille de page, la requête ne renvoie que le nombre de véhicules spécifié par la limite, ou moins. Si la taille de page demandée dépasse une valeur interne maximale, la valeur maximale interne est utilisée. Les tailles de page par défaut et maximale correspondent à 100 véhicules.

Une liste de véhicules de livraison peut inclure un jeton pour lire la page de résultats suivante. Un jeton de page n'est présent dans une réponse que lorsque davantage de pages de véhicules de livraison peuvent être récupérées. Pour récupérer la page de tâches suivante, utilisez le jeton de page avec une requête identique à la précédente.

gRPC

L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour répertorier les véhicules de livraison dans une région particulière avec un certain attribut. Une réponse réussie peut toujours être vide. Dans ce cas, cela signifie qu'aucun véhicule avec l'attribut spécifié ne se trouve déjà dans la fenêtre d'affichage spécifiée.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
  ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setViewport(
            Viewport.newBuilder()
              .setHigh(LatLng.newBuilder()
                  .setLatitude(37.45)
                  .setLongitude(-122.06)
                  .build())
              .setLow(LatLng.newBuilder()
                  .setLatitude(37.41)
                  .setLongitude(-122.11)
                  .build())
      .setFilter("attributes.my_key = my_value")
      .build();

try {
  ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
      deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
          break;

      case PERMISSION_DENIED:
          break;
  }
  return;
}

REST

Pour répertorier les tâches à partir d'un navigateur, envoyez un appel HTTP REST à ListDeliveryVehicles:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`

Pour appliquer un filtre aux tâches répertoriées, incluez un paramètre d'URL "filter" avec une requête de filtre avec échappement comme valeur.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.

Si la recherche aboutit, le corps de la réponse contient des données présentant la structure suivante:

// JSON representation
{
  "deliveryVehicles": [
    {
      object (DeliveryVehicle)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Une réponse positive peut toujours être vide. Dans ce cas, cela signifie qu'aucun véhicule de livraison ne correspond à la requête de filtre et à la fenêtre d'affichage spécifiées.

Exemple de commande curl :

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"

Suivi de flotte

Deux options s'offrent à vous pour activer le suivi de parc à l'aide de l'API Fleet Engine Deliveries:

  • À privilégier:utilisez la bibliothèque JavaScript Fleet Tracking. La bibliothèque vous permet de visualiser l'emplacement des véhicules et les lieux d'intérêt suivis dans Fleet Engine. Il contient un composant de carte JavaScript qui remplace un objet google.maps.Map standard, ainsi que des composants de données à connecter à Fleet Engine. Ce composant vous permet de proposer une expérience de suivi de flotte animée et personnalisable à partir de votre application Web ou mobile.

  • Implémentez le suivi de votre propre flotte en plus de l'API Fleet Engine Deliveries.

La solution consiste à rechercher les tâches du parc à l'aide de leur ID de suivi.

Journalisation

Vous pouvez configurer Fleet Engine pour qu'il envoie des journaux RPC à Cloud Logging. Pour en savoir plus, consultez la section Journalisation.

Rôles d'autorisation et jetons

Comme décrit dans la section Gérer le cycle de vie du véhicule et des tâches et dans les notes d'autorisation pour des cas d'utilisation individuels, les appels à Fleet Engine nécessitent une authentification avec des jetons Web JSON signés à l'aide d'identifiants de compte de service. Les comptes de service utilisés pour émettre ces jetons peuvent avoir un ou plusieurs rôles, chaque rôle accordant un ensemble d'autorisations différent.

Pour en savoir plus, consultez la page Authentification et autorisation.

Résoudre les problèmes courants

En cas de problème, consultez les sections suivantes pour obtenir de l'aide.

Résilience

Fleet Engine n'est pas considéré comme une source fiable. Vous êtes responsable de la restauration de l'état de votre système, si nécessaire, sans dépendre de Fleet Engine.

État perdu dans Fleet Engine

Lorsque vous travaillez avec Fleet Engine, implémentez des clients de sorte que le système se répare tout seul en cas de défaillance. Par exemple, lorsque Fleet Engine tente de mettre à jour un véhicule, il peut renvoyer une erreur indiquant que le véhicule n'existe pas. Le client doit ensuite recréer le véhicule dans le nouvel état. Bien que ce problème se produise rarement, assurez-vous que votre système est suffisamment résilient pour le gérer.

Dans le scénario extrêmement improbable d'une défaillance catastrophique de Fleet Engine, vous devrez peut-être recréer la plupart ou la totalité des véhicules et des tâches. Si le taux de création devient trop élevé, certaines requêtes peuvent à nouveau échouer en raison de problèmes de quota, car des contrôles de quota sont en place pour éviter les attaques par déni de service (DoS). Dans ce cas, ralentissez le taux de recréation à l'aide d'une stratégie d'intervalle entre les tentatives.

État perdu dans l'application du conducteur

Si l'application de pilote plante, elle doit recréer l'état actuel dans le SDK Driver. L'application doit tenter de recréer des tâches pour s'assurer qu'elles existent et pour restaurer leurs états actuels. L'application doit également recréer et définir explicitement la liste des arrêts pour le SDK Driver.

Questions fréquentes

Que se passe-t-il si un conducteur s'arrête dans le désordre pour une tâche ?

Dans ce cas, commencez par mettre à jour l'ordre des tâches, puis procédez normalement, en marquant l'arrivée à l'arrêt, l'achèvement de la tâche et d'autres détails. Sinon, le système peut devenir incohérent, les ATA peuvent devenir incorrectes et des erreurs inattendues peuvent être signalées.