Modélisez les activités de votre parc pour les premiers et dernier kilomètre de livraisons avec l'API Fleet Engine Deliveries. Vous pouvez utiliser cette API à l'aide du SDK Driver pour Android et iOS, ou directement via des appels HTTP REST ou gRPC.
Configuration initiale
Vous configurez l'API Fleet Engine Deliveries dans la console Google Cloud.
Pour en savoir plus sur les étapes à suivre dans la console et sur la création d'un jeton Web JSON pour l'autorisation, consultez la page Authentification et autorisation.
Pour en savoir plus sur l'utilisation de la console, consultez la documentation de la console Google Cloud.
Vérifier votre configuration
Après avoir créé les comptes de service, vérifiez que votre configuration est terminée et que vous pouvez créer un véhicule de livraison. En vérifiant 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:
Testez deux éléments clés de votre configuration: la signature du jeton d'autorisation et la création du véhicule de livraison d'essai avec l'utilitaire de ligne de commande
gcloud. Pour en savoir plus, consultez le guide Vérifier votre configuration.Testez votre configuration avec les exemples de scripts d'authentification pour parc Engine.
Bibliothèques clientes
Pour une meilleure expérience développeur sur 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 de serveur, consultez la page Bibliothèques clientes.
Les exemples Java de cette documentation partent du principe que vous connaissez gRPC.
Structures de données
L'API Fleet Engine Deliveries utilise deux structures de données pour modéliser la prise en charge et la livraison des expéditions:
- Véhicule de livraison utilisé pour transporter le colis.
- Les tâches d'enlèvement et de livraison de l'expédition.
Vous pouvez également utiliser des tâches pour modéliser les coupures au volant et les arrêts planifiés tout au long de la journée.
Véhicules de livraison
Les véhicules de livraison transportent les colis d'un dépôt à un lieu de livraison, et d'un point 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 notifications de position pour le suivi des expéditions et du parc.
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.
- Lorsque les conducteurs sont indisponibles, par exemple pour faire des pauses, attribuez des tâches d'indisponibilité.
- Pour les tâches secondaires qui se trouvent dans des boîtes de dépôt ou sur les sites des clients, 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 délais d'exécution pour chaque tâche, il utilise toutes les tâches et l'ordre dans lequel elles sont planifiées pour effectuer des estimations. Pour plus d'informations sur les ID de tâche, consultez la section Consignes relatives aux ID de tâche.
Pour créer des tâches dans Fleet Engine, utilisez le gestionnaire de tâches du SDK Driver.
Tâches d'expédition
Créez des tâches d'expédition pour le retrait et la livraison d'un colis, et incluez les informations suivantes:
- Lieu du retrait ou de la livraison.
- Un numéro de suivi ou un identifiant.
- Un temps d'interaction pour tenir compte du temps supplémentaire pour accomplir la tâche, chercher 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 d'indisponibilité
Les tâches d'indisponibilité couvrent les périodes pendant lesquelles un véhicule n'est pas disponible pour le retrait ou la livraison, comme les pauses pour faire le plein ou les pauses du conducteur.
Créez une tâche d'indisponibilité à l'aide des informations suivantes:
- Durée de la coupure.
- Éventuellement, l'emplacement de la coupure publicitaire. Il n'est pas nécessaire de fournir un emplacement spécifique, mais cela permet d'obtenir des heures d'arrivée prévues plus précises 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é pour un arrêt de collecte planifié quotidien à un emplacement spécifique, indépendamment des autres livraisons ou retraits à ce même site. Vous pouvez également créer des tâches d'arrêt planifiées pour les collectes depuis des boîtes de dépôt, ou pour modéliser les correspondances entre véhicules d'alimentation ou les arrêts dans des centres de réparation et des points de service.
Pour plus d'informations, consultez les articles suivants :
Android
iOS
Consignes concernant les 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
- Ne divulguez 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 maximum.
- N'incluez aucun des caractères ASCII suivants: "/", ":", "\", "?" ou "#".
- Procédez à la normalisation selon le formulaire C de normalisation Unicode.
Voici quelques exemples d'ID de tâche corrects:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
Le tableau suivant présente des exemples d'ID de tâche non compatibles:
| ID de tâche non compatibles | Motif |
|---|---|
| 8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | Enfreint les informations permettant d'identifier personnellement l'utilisateur et les exigences en termes de caractères: virgules, points, deux-points et barres obliques. |
| JohnDoe-577b484da26f-Cupertino-SantaCruz | Enfreint les exigences concernant les informations permettant d'identifier personnellement l'utilisateur. |
| 4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a | Enfreint les exigences relatives aux informations permettant d'identifier personnellement l'utilisateur et aux caractères: espaces, virgules et guillemets. Il comporte plus de 64 caractères. |
Autres ressources
Pour afficher 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).
Durée de vie d'un véhicule
L'objet DeliveryVehicle représente un véhicule de livraison du premier ou du dernier kilomètre.
Vous pouvez créer 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.
- Identifiant d'un véhicule appartenant au client.
Utilisez des identifiants uniques pour chaque véhicule. Ne réutilisez pas l'ID du véhicule, sauf s'il n'y a pas de tâches actives pour le véhicule d'origine.
Fleet Engine supprime automatiquement les objets DeliveryVehicle qui n'ont pas été mis à jour à l'aide de UpdateDeliveryVehicle au bout de sept jours. Pour que votre véhicule reste disponible dans Fleet Engine, il est recommandé de mettre à jour sa position à intervalles réguliers. Les mises à jour de la plupart des autres champs de l'entité DeliveryVehicle prolongent également sa durée de vie, à condition que la nouvelle valeur de champ soit différente de la valeur existante.
Pour voir si un véhicule existe:
- Appelez le
UpdateDeliveryVehicle. - Si vous obtenez une erreur NOT_FOUND, appelez
CreateDeliveryVehiclepour recréer le véhicule. Si l'appel renvoie un véhicule, vous pouvez toujours le mettre à jour.
Type de véhicule
L'entité VehicleType contient un champ facultatif VehicleType, qui comporte une énumération Category que vous pouvez spécifier comme AUTO, TWO_WHEELER, BICYCLE ou PEDESTRIAN. Si vous ne le définissez pas, il est défini par défaut sur AUTO.
Tous les itinéraires pour les véhicules utilisent le RouteTravelMode correspondant au type de véhicule.
Attributs du véhicule
L'entité DeliveryVehicle contient un champ répété DeliveryVehicleAttribute. L'API ListDeliveryVehicles inclut un champ filter qui peut 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 pourrait ê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 à l'aide des interfaces gRPC ou REST de l'API Deliveries.
Un objet Task possède un champ d'état permettant de 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'a pas encore dépassé l'arrêt attribué à la tâche.
Consignes concernant les tâches
Vous ne pouvez attribuer une tâche à un véhicule que lorsqu'il est à l'état OUVERT.
Pour annuler une tâche, supprimez-la de la liste des arrêts du véhicule, ce qui définit automatiquement l'état de la tâche sur CLOSED (FERMÉ).
Lorsque le véhicule de la tâche termine l'arrêt du véhicule de la tâche:
Dans le champ de résultat de la tâche, indiquez "SUCCEEDED" (Réussite) ou "FAILED" (ÉCHEC).
Indiquez le code temporel de l'événement.
La bibliothèque JavaScript Shipment Tracking indique ensuite le résultat de la tâche, et son état est automatiquement défini sur CLOSED (FERMÉ). Pour en savoir plus, consultez la page Suivre votre colis avec la bibliothèque JavaScript Shipment Tracking.
Comme pour les véhicules, Fleet Engine supprime les tâches qui n'ont pas été mises à jour au bout de sept jours. Si vous essayez de créer une tâche avec un ID qui existe déjà, une erreur est renvoyée.
Remarque:Fleet Engine ne permet pas de supprimer explicitement une tâche. Le service supprime automatiquement les tâches après sept jours sans être mis à jour. Si vous souhaitez conserver les données de tâches pendant plus de sept jours, vous devez mettre en œuvre 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: chaîne, nombre et valeur booléenne. L'API ListTasks inclut un champ filter qui peut limiter les entités Task renvoyées à celles ayant les attributs spécifiés. Les attributs de tâche n'ont aucune 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 ils pourraient être visibles par les utilisateurs.
Gérer le cycle de vie des véhicules et des tâches
Rappel: Votre système interne constitue la source fiable des données que l'API Fleet Engine Deliveries enrichit 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 les tâches associées.
Dans le même temps, l'application de pilote communique directement avec Fleet Engine pour mettre à jour la position de l'appareil et les informations d'itinéraire. Ce modèle permet à Fleet Engine de gérer efficacement la localisation en temps réel. Il envoie l'établissement directement à la bibliothèque de suivi, qui vous permet ensuite d'informer les clients de l'état de leur commande.
Par exemple, supposons que vous ayez le scénario suivant:
- Un livreur s'approche d'un arrêt de livraison. L'application pilote envoie sa localisation à Fleet Engine.
- Fleet Engine envoie la position de l'appareil à la bibliothèque de suivi, que votre application consommateur utilise pour avertir le consommateur de la proximité de son colis.
- Une fois que le livreur a terminé la livraison, il clique sur le bouton "Colis livré" dans l'application du livreur.
- L'action "Livraison livrée" envoie les informations à votre système backend, qui effectue les étapes de validation et de validation nécessaires.
- Votre système confirme que la tâche a abouti 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.
Gérer les jetons client
Les mises à jour de position émanant 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:
Générez le jeton à l'aide du rôle de compte de service Utilisateur de pilote non approuvé pour parc de services de livraison.
Fournir à l'application pilote un jeton de champ d'application limité. Ce champ d'application lui permet uniquement de mettre à jour l'emplacement de l'appareil dans Fleet Engine.
Cette approche garantit que les appels provenant d'appareils mobiles (considérés comme des environnements à faible confiance) respectent le principe du moindre privilège.
Autres rôles du compte de service
Si vous souhaitez autoriser les applications de pilote à effectuer des mises à jour directes de Fleet Engine au-delà de celles limitées au rôle de pilote non approuvé, par exemple pour certaines mises à jour de tâches, vous pouvez utiliser le rôle de pilote de confiance. Pour en savoir plus sur un modèle utilisant le rôle de pilote de confiance, consultez la page Modèle de pilote de confiance.
Pour en savoir plus sur l'utilisation des rôles de pilote non approuvés et de confiance, consultez Configuration d'un projet Cloud.
Imaginer une journée de travail
Le tableau suivant décrit à quoi peut ressembler une journée de travail pour les livreurs du premier ou du dernier kilomètre dans une entreprise de livraison et de logistique. Votre entreprise peut différer dans les détails, mais vous pouvez voir comment vous pourriez modéliser une journée de travail.
| Temps | Activité | Modélisation |
|---|---|---|
| Dans les 24 heures suivant 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 livraisons dans Fleet Engine. Par exemple, vous pouvez créer une tâche de retrait de la livraison, 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 de livraison ont été finalisés. |
| Début de journée | Le conducteur commence sa 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 dans le véhicule de livraison et les scanne. | Si les tâches de livraison n'ont pas été créées à l'avance, créez des tâches de livraison au moment de l'analyse. | |
| Le conducteur confirme l'ordre des tâches à effectuer. | Si ce n'est pas le cas, créez des tâches de retrait, des indisponibilités planifiées et des arrêts planifiés. | |
| Le conducteur quitte le dépôt et effectue un commit pour le nombre de tâches suivant. | Attribuez toutes les tâches ou un sous-ensemble de tâches au véhicule en validant leur ordre d'achèvement. | |
| Le livreur livre un colis. | Une fois arrivé à l'arrêt de livraison, effectuez les actions en rapport avec l'arrivée d'un véhicule à un arrêt. Après la livraison, fermez la tâche de livraison et, si vous le souhaitez, indiquez l'état de la livraison et les 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 actions associées au véhicule achever un arrêt et au véhicule en route vers le prochain arrêt. | |
| Le livreur rencontre un véhicule d'alimentation pour y transférer d'autres colis. | Le point de rendez-vous d'une correspondance entre un véhicule d'alimentation et un véhicule de livraison doit être modélisé en tant qu'arrêt planifié.
Une fois les livraisons transférées et analysées, 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 modifiant l'ordre des tâches. |
|
| Le conducteur reçoit une notification de demande de retrait. | Après avoir accepté la demande de retrait, créez une tâche de retrait en magasin. Modifiez ensuite l'ordre d'exécution des tâches en attribuant des tâches à un véhicule et en modifiant l'ordre des tâches. | |
| Midi | Le conducteur prend sa pause déjeuner. | Si un établissement est associé à la tâche d'indisponibilité, traitez-le comme n'importe quelle autre tâche. Effectuez les actions associées à un véhicule arrivant à un arrêt, un véhicule passe par un arrêt et véhicule en route vers le prochain arrêt.
Autrement, aucune autre action n'est nécessaire avant la fin de la coupure. Pour supprimer la tâche, confirmez les tâches suivantes et restantes, et mettez à jour l'ordre des tâches. |
| Le livreur récupère un colis. | Il est modélisé comme un arrêt de livraison. Effectuez les actions associées à l'arrivée d'un véhicule à un arrêt, à la fermeture d'une tâche et, éventuellement, au stockage de l'état de la livraison 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 actions associées au véhicule arrêtant un arrêt et au véhicule en route vers le prochain arrêt. Remarque: Pour garantir une facturation correcte, tous les retraits doivent être associés à une tâche de livraison. Si la prise en charge doit être livrée à un autre endroit sur le même itinéraire du 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 livreur ramène le retrait au dépôt, nous vous recommandons de créer une tâche de livraison au lieu du dépôt. | |
| Le livreur effectue un arrêt planifié pour récupérer les colis dans une boîte de dépôt. | Il est modélisé comme n'importe quel autre arrêt de prise en charge. Effectuez les 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é à conduire jusqu'au prochain arrêt, effectuez les actions associées au véhicule à l'arrêt et au véhicule en route vers le prochain arrêt. | |
| Le livreur reçoit une notification indiquant qu'un colis est dévié vers un autre lieu. | Définissez l'état d'origine de la tâche de livraison sur "TERMINÉ" et créez une tâche de livraison pour le nouveau lieu de livraison. Pour en savoir plus, consultez la section Réacheminer un colis. | |
| Le conducteur a tenté de livrer un colis, mais n'y est pas parvenu. | Cette modélisation est semblable à celle d'un arrêt de livraison réussi, marquant la tâche de livraison comme terminée. Effectuez les actions liées à l'arrivée d'un véhicule à un arrêt. Après l'échec de la livraison, fermez la tâche et, éventuellement, stockez l'état de l'envoi et les 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 actions associées au véhicule arrêtant un arrêt et au véhicule en route vers le prochain arrêt. | |
| Le livreur a reçu une notification lui demandant de mettre un colis en attente (et non de le livrer). | Une fois la notification reçue et confirmée, définissez l'état de la tâche sur TERMINÉ. | |
| Le livreur a été invité à livrer un colis par la suite, ce qui a modifié la commande de livraison engagée. | Mettez à jour l'ordre des tâches. | |
| Le livreur choisit de livrer un colis dans le désordre. | Mettez à jour l'ordre des tâches, puis procédez comme d'habitude. | |
| Le livreur livre plusieurs colis à un seul site. | Ce modèle est semblable à celui d'un arrêt de livraison unique. Une fois arrivé à l'arrêt, effectuez les actions nécessaires lorsqu'un véhicule arrive à cet arrêt. Après avoir livré chaque envoi, fermez chaque tâche et, éventuellement, état de la livraison du magasin et 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 actions associées au véhicule arrêtant un arrêt et au véhicule en route vers le prochain arrêt. | |
| Fin de journée | Le chauffeur retourne au dépôt. | Si le livreur revient au dépôt avec des colis récupérés pendant son trajet, vous devez également créer et finaliser chaque colis en tant que tâche de livraison pour vous assurer que la facturation est correcte. Pour ce faire, vous pouvez modéliser 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 toujours le modéliser en tant qu'arrêt planifié. La modélisation de l'arrêt permet aux conducteurs de voir l'itinéraire de retour au dépôt et de connaître leur heure d'arrivée prévue. |
Fonctionnement des mises à jour de la position
Pour optimiser les performances de Fleet Engine, fournissez-lui un flux de mises à jour de la position des véhicules. Pour fournir ces mises à jour, utilisez l'une des méthodes suivantes:
- Utilisez le SDK Driver pour Android ou iOS. Il s'agit de l'option la plus simple.
- Utilisez un code personnalisé : utile si les emplacements sont retransmis 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 est en route vers un arrêt (y compris au dépôt) et lorsqu'il arrive à un arrêt. Fleet Engine ne détecte pas ces événements automatiquement.
Arrêts de véhicules et lieux de livraison
Un arrêt de véhicule est l'endroit 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 emplacement barré.
Le lieu de livraison est le lieu où le colis est livré ou retiré. Pour vous rendre au lieu de livraison et en revenir, vous devrez peut-être marcher depuis l'arrêt du véhicule.
Par exemple, lorsqu'un chauffeur livre un colis à un magasin situé dans un centre commercial, le véhicule de livraison s'arrête sur le parking du centre commercial, à proximité de l'entrée la plus proche. Il s'agit de l'arrêt du véhicule. Le conducteur marche ensuite de l'arrêt du véhicule jusqu'à l'emplacement du centre commercial où se trouve le magasin. Il s'agit du lieu de livraison.
Pour optimiser l'expérience de suivi des livraisons de vos utilisateurs, tenez compte de la manière dont les tâches d'expédition sont attribuées aux arrêts des véhicules et gardez à l'esprit que le nombre d'arrêts de véhicule restants pour les tâches d'expédition est signalé à l'utilisateur pour l'aider à suivre la progression de la livraison.
Par exemple, si un livreur effectue de nombreuses livraisons dans un seul 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, le suivi des expéditions sera moins utile pour vos utilisateurs, car le suivi n'est disponible que lorsque le véhicule se trouve à un nombre limité d'arrêts avant sa destination. Avoir de nombreux arrêts de véhicule effectués en peu de temps ne donne pas beaucoup de temps à l'utilisateur pour suivre la progression de sa 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 indiqué 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 incrémentiels automatiquement et assurez-vous que l'identifiant ne contient aucune information permettant d'identifier personnellement l'utilisateur, comme 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 à partir 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 dans le champ Name est ignorée conformément aux instructions de l'API concernant les ID spécifiés par l'utilisateur.
Vous devez utiliser le champ DeliveryVehicleId pour définir l'identifiant du véhicule.
Lorsque vous créez un DeliveryVehicle, vous pouvez éventuellement spécifier les champs suivants:
- Attributs
- LastLocation
- Type
Ne définissez aucun autre champ. 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 champs facultatifs, vous pouvez laisser le champ DeliveryVehicle non défini dans CreateDeliveryVehicleRequest.
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java 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, effectuez un appel REST HTTP à CreateDeliveryVehicle:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> est l'identifiant unique d'un véhicule de livraison de 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 aucun autre champ. 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 en livraison
Vous pouvez créer une tâche de retrait en magasin à partir du SDK Driver ou à partir d'un environnement de serveur à l'aide de gRPC ou REST.
gRPC
L'exemple suivant montre comment créer une tâche de retrait en magasin à l'aide de la bibliothèque gRPC Java:
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 en magasin à partir d'un environnement de serveur, effectuez un appel REST HTTP à 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 de l'expédition. Si votre système ne comporte pas d'ID de tâche, 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 :
Champ Valeur Type Type.PICKUP state State.OPEN trackingId Numéro ou identifiant que vous utilisez pour suivre une livraison. plannedLocation Le lieu où la tâche doit être effectuée, dans ce cas le lieu de retrait du colis. taskDuration Temps estimé, en secondes, pour récupérer le colis au point de retrait. Champs facultatifs :
Champ Valeur targetTimeWindow La période pendant laquelle la tâche doit être terminée. Cela n'affecte pas le comportement de routage. attributs Liste d'attributs de tâche 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
Créez une tâche de livraison de colis à partir du SDK Driver ou d'un environnement de serveur à l'aide de gRPC ou REST.
gRPC
L'exemple suivant montre comment créer une tâche de livraison de colis à l'aide de la bibliothèque gRPC Java:
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 colis à partir d'un environnement de serveur à l'aide de gRPC ou REST, effectuez un appel REST HTTP à 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 de l'expédition. Si votre système ne comporte pas d'ID de tâche, 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 :
Champ Valeur Type Type.DELIVERY state State.OPEN trackingId Numéro ou identifiant que vous utilisez pour suivre une livraison. plannedLocation Le lieu où la tâche doit être effectuée, dans ce cas le lieu de livraison de la livraison. taskDuration Délai estimé, en secondes, pour déposer le colis sur le lieu de livraison. Champs facultatifs :
Champ Valeur targetTimeWindow La période pendant laquelle la tâche doit être terminée. Cela n'affecte pas le comportement de routage. attributs Liste d'attributs de tâche 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
Créer des tâches en série
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 gRPC Java pour créer deux tâches, l'une pour une livraison et l'autre pour le retrait au même endroit:
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 :
Champ Valeur requêtes Tableau< CreateTasksRequest>Champs facultatifs :
Champ Valeur en-tête "DeliveryRequestHeader"
Chaque élément CreateTasksRequest du fichier requests doit transmettre les mêmes règles de validation qu'une requête CreateTask, à l'exception des champs parent et header qui sont facultatifs. S'ils sont définis, ils doivent être identiques à leurs champs respectifs à la racine BatchCreateTasksRequest. Consultez les sections Créer une tâche de retrait en magasin et créer une tâche de livraison pour connaître les règles de validation propres à 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 interruptions du conducteur ou le ravitaillement en carburant d'un véhicule) à partir du SDK Driver, ou à partir 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 éventuellement indiquer un lieu.
gRPC
L'exemple suivant montre comment créer une tâche d'indisponibilité à l'aide de la bibliothèque gRPC Java:
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, effectuez un appel REST HTTP à CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> est un identifiant unique pour la tâche. Si votre système ne comporte pas d'ID de tâche, 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 :
Champ Valeur Type Type.UNAVAILABLE state State.OPEN taskDuration Durée de la coupure en secondes. Champs facultatifs :
Champ Valeur plannedLocation Emplacement 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 à l'aide de 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 gRPC Java pour créer une tâche d'arrêt programmé:
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, effectuez un appel REST HTTP à CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> est un identifiant unique pour la tâche. Si votre système ne comporte pas d'ID de tâche, 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 :
Champ Valeur Type Type.SCHEDULED_STOP state State.OPEN plannedLocation Emplacement de l'arrêt. taskDuration Durée anticipée 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 la période cible
La période cible correspond à la période TimeWindow au cours de laquelle la tâche doit être terminée. Par exemple, si vous indiquez un créneau de livraison aux destinataires de la tâche, vous pouvez utiliser la période cible de la tâche pour capturer cette période et générer des alertes ou analyser les performances après le trajet à l'aide du champ.
La période cible comprend une heure de début et une heure de fin. Elle peut être définie pour n'importe quel type de tâche. La période cible n'affecte pas le comportement de routage.
gRPC
L'exemple suivant montre comment définir une fenêtre temporelle pour les tâches à l'aide de la bibliothèque gRPC Java:
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 :
Champ Valeur targetTimeWindow La 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 de suivi des expéditions et des données renvoyées par un appel à GetTaskTrackingInfo peut être contrôlée pour chaque tâche en définissant un TaskTrackingViewConfig. Pour en savoir plus, consultez Tâches actives liées au véhicule. Cela peut être fait 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 gRPC Java 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 :
Champ Valeur taskTrackingViewConfig Configuration du suivi des tâches qui spécifie quels éléments de données sont visibles par les utilisateurs finaux et 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 ce véhicule. L'ordre des tâches pour 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 passer 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 modifiez 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 de commande attribuées à un véhicule à partir du SDK Driver ou de l'environnement de serveur. N'utilisez pas les deux méthodes pour éviter les conditions de concurrence et maintenir une source unique de vérité.
Lorsque vous mettez à jour l'ordre des tâches pour un véhicule, il effectue également les opérations suivantes:
- Attribue des tâches inédites au véhicule.
- Ferme toutes les tâches précédemment attribuées au véhicule, mais qui ne figurent pas dans l'ordre modifié.
Pour passer 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 modifiez 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 gRPC Java pour mettre à jour l'ordre des tâches pour le 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, effectuez un appel HTTP REST à UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> est l'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 :
Champ Valeur 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. restantVehicleJourneySegments[i].stop Arrêt de la tâche i dans la liste. restantVehicleJourneySegments[i].stop.plannedLocation Emplacement prévu de l'arrêt. restantVehicleJourneySegments[i].stop.tasks Liste des tâches à effectuer à cet arrêt de 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
Le véhicule est en route pour le prochain arrêt
Fleet Engine doit être averti lorsqu'un véhicule quitte un arrêt ou commence la navigation. Vous pouvez envoyer une notification à Fleet Engine à partir du SDK Driver, ou depuis 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 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 informer Fleet Engine qu'un véhicule est en route vers son prochain arrêt à partir d'un environnement de serveur, effectuez un appel HTTP REST à UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> est l'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:
Champ Valeur remainingVehicleJourneySegments Liste des arrêts restants du véhicule avec leur état marqué "State.NEW". L'état du premier arrêt de la liste doit être défini sur 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 la position du véhicule, vous pouvez appeler directement Fleet Engine en indiquant sa position. La position de chaque véhicule actif doit être mise à jour au moins une fois par minute et toutes les cinq secondes au maximum.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java pour mettre à jour la position 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 la position 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 attribué au véhicule de livraison de votre parc ou dont vous souhaitez mettre à jour la position. 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:
Champ Valeur lastLocation.supplementalLocation 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 :
Champ Valeur lastLocation.supplementalLocationAccuracy Précision de la position indiquée, 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 à partir du SDK Driver, ou à partir 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 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 informer Fleet Engine de l'arrivée d'un véhicule à un arrêt à partir d'un environnement de serveur, effectuez un appel HTTP REST à UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> est l'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 :
Champ Valeur remainingVehicleJourneySegments L'arrêt auquel vous êtes arrivé, dont l'état est défini sur State.ARRIVED, suivi d'une liste des arrêts restants du véhicule avec l'état 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 termine 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 informer Fleet Engine à partir du SDK Driver, ou à partir 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 gRPC Java pour avertir Fleet Engine qu'un véhicule a été 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 informer Fleet Engine de l'achèvement d'un arrêt à partir d'un environnement de serveur, effectuez un appel REST HTTP à UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
<id> est l'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 :
Champ Valeur remaining_vehicle_journey_segments L'arrêt que vous avez terminé ne doit plus figurer dans la liste des arrêts restants du véhicule. 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âches sont immuables. Toutefois, vous pouvez modifier l'état, le résultat de la tâche, la date et l'heure du résultat, l'emplacement du résultat de la tâche et les attributs en mettant directement à jour l'entité de tâche. Par exemple, dans les cas où une tâche n'a pas été attribuée à un véhicule, vous pouvez la fermer en mettant à jour directement son état.
gRPC
Il s'agit d'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 du véhicule. Pour ce faire, vous pouvez définir la liste des arrêts restants du véhicule, comme lorsque vous modifiez l'ordre des tâches pour un véhicule.
Si un véhicule n'a pas encore été attribué à une tâche et qu'elle doit être fermée, définissez-la sur l'état CLOSED. Cependant, vous ne pouvez pas rouvrir une tâche CLOSED.
La fermeture d'une tâche n'indique pas la réussite ou l'échec. Cela indique que la tâche n'est plus considérée comme en cours. Pour le suivi du colis, il est important d'indiquer le résultat réel d'une tâche afin de pouvoir afficher le résultat d'une 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 à partir d'un environnement de serveur, effectuez un appel REST HTTP à 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 :
Champ Valeur state State.CLOSED Champs facultatifs :
Champ Valeur taskOutcome Outcome.SUCCEEDED ou Outcome.FAILED taskOutcomeTime L'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 la 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 le lieu du résultat
La fermeture d'une tâche n'indique pas la réussite ou l'échec, mais indique que la tâche n'est plus considérée comme en cours. Pour le suivi des expéditions, il est important d'indiquer le résultat réel d'une tâche afin que le résultat de la livraison puisse s'afficher et que la facturation des services soit appropriée. 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 l'emplacement du résultat de la tâche une fois qu'ils ont été définis.
Le résultat des tâches à l'état FERMÉE peut être défini sur SUCCEEDED (SUCCEEDED) ou FAILED (ÉCHEC). Fleet Engine ne facture que les tâches de livraison dont l'état est "SUCCEEDED" (Réussite).
Lorsque vous marquez le résultat d'une tâche, Fleet Engine renseigne 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 la définir sur la valeur par défaut du dernier emplacement du véhicule. Vous pouvez également écraser ultérieurement l'emplacement du résultat de la tâche Fleet Engine défini. Fleet Engine ne remplace jamais un emplacement de résultat de tâche que vous fournissez. Vous ne pouvez pas définir un emplacement de résultat pour une tâche pour laquelle aucun résultat n'est 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 gRPC Java 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, effectuez un appel REST HTTP à 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 :
Champ Valeur taskOutcome Outcome.SUCCEEDED ou Outcome.FAILED Champs facultatifs :
Champ Valeur taskOutcomeLocation Emplacement où la tâche a été effectuée. Si cette règle n'est pas configurée, Fleet Engine utilise par défaut la dernière position du véhicule. taskOutcomeTime Code temporel de la fin de la tâche.
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 l'emplacement 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 chargeurs et des véhicules de livraison
Si vous utilisez des véhicules d'actualisation de contenu pour transporter des colis vers des véhicules de livraison tout au long de la journée, modélisez le transfert des colis en tant que tâche d'arrêt planifiée pour le véhicule de livraison. Pour garantir un suivi précis de l'emplacement, 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 du 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 celle-ci. Toutefois, vous pouvez mettre à jour 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'identifiant de suivi associé à la tâche comme clé dans une table externe.
Pour en savoir plus, consultez la section Cycle de vie d'une tâche.
Rechercher un véhicule
Vous pouvez rechercher un véhicule à partir du SDK Driver, ou dans un environnement de serveur à l'aide de gRPC ou REST.
gRPC
L'exemple suivant montre comment rechercher un véhicule à l'aide de la bibliothèque gRPC Java:
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 dans un environnement de serveur, effectuez 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é 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 dans 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 gRPC Java:
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 dans un environnement de serveur, effectuez un appel REST HTTP à 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 des informations sur la tâche d'expédition en fonction de son ID de suivi
Vous pouvez rechercher des informations sur les tâches d'expédition 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 ayant accès à l'affichage complet des données de la tâche.
- Par un ID de suivi: utilisé par votre logiciel client pour fournir des informations limitées à un utilisateur final, par exemple la date et l'heure auxquelles 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 par son ID, consultez la section Rechercher une tâche.
Pour rechercher des informations à partir d'un ID de suivi, vous pouvez utiliser l'une des méthodes suivantes:
Exigences concernant la recherche
Les informations sur la livraison fournies par un ID de suivi respectent les règles de visibilité définies dans Contrôler la visibilité des lieux suivis.
Utilisez Fleet Engine pour rechercher des informations sur la livraison à l'aide de l'ID de suivi. Le SDK Driver ne permet pas de rechercher des informations par ID de suivi. Pour ce faire avec Fleet Engine, vous devez utiliser un environnement de serveur ou 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, tous les appels d'API Fleet Engine Deliveries ne renvoient que des 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.
Effectuer des recherches avec Java à l'aide de gRPC
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java pour rechercher des informations sur une tâche de livraison en fonction de 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;
}
Requêtes HTTP
Pour rechercher une tâche d'expédition dans un navigateur, effectuez un appel REST HTTP à GetTaskTrackingInfo:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`
<tracking_id> est l'ID 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 des tâches à partir d'un serveur ou d'un environnement de navigateur. Le SDK Driver ne permet pas de lister les tâches.
La liste des tâches demande un accès étendu aux tâches. La liste des tâches est destinée uniquement aux utilisateurs de confiance. Utilisez le lecteur de parc de livraison ou les jetons d'authentification super-utilisateur de distribution lorsque vous effectuez des requêtes de tâches de liste.
Les champs suivants des tâches répertoriées sont masqués:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
Les tâches répertoriées peuvent être filtrées selon la plupart de leurs propriétés. Pour en savoir plus sur la syntaxe des requêtes de filtre, consultez la page AIP-160. La liste suivante répertorie 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, basés sur les propositions d'amélioration des 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 |
| Lieu | 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 demandes 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 maximale interne, celle-ci 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 par ailleurs identique à la requête 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 à récupérer.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java afin de répertorier les tâches pour un deliveryVehicleId et un attribut de tâche. Une réponse positive peut toujours être vide. Une réponse vide indique qu'aucune tâche n'est associée à l'élément deliveryVehicleId 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 des tâches à partir d'un navigateur, effectuez un appel REST HTTP à 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 d'URL 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 répond aux critères de filtrage 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 répertorier les véhicules de livraison à partir d'un environnement de serveur ou de navigateur. Le SDK Driver ne permet pas de présenter des véhicules de livraison.
La liste des véhicules de livraison nécessite un accès étendu aux véhicules de livraison et est destinée uniquement aux utilisateurs de confiance. Utilisez le lecteur de parc de livraison ou les jetons d'authentification super-utilisateur de livraison lorsque vous effectuez des requêtes de véhicules de diffusion de listes.
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 selon 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 des 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 listé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 latitude élevée géographiquement inférieure à une latitude basse.
Par défaut, les listes de véhicules de diffusion sont paginées dans 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 un nombre inférieur. Si la taille de page demandée dépasse une valeur maximale interne, celle-ci est utilisée. La taille de page par défaut et maximale est de 100 véhicules.
Une liste de véhicules de livraison peut inclure un jeton permettant de 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 sont disponibles pour la récupération. Pour récupérer la page de tâches suivante, utilisez le jeton de page avec une requête qui est par ailleurs identique à la requête précédente.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java pour répertorier les véhicules de livraison dans une région particulière avec un certain attribut. Une réponse positive peut toujours être vide. 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 des tâches à partir d'un navigateur, effectuez un appel REST HTTP à ListDeliveryVehicles:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Pour appliquer un filtre aux tâches listées, incluez un paramètre d'URL "filter" avec une requête de filtre avec échappement d'URL 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. Cela signifie qu'aucun véhicule de livraison n'a été trouvé répondant à 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 la livraison
Vous disposez de deux options pour activer le suivi des livraisons à l'aide de l'API Fleet Engine Deliveries:
Méthode recommandée:utilisez la bibliothèque JavaScript Shipment Tracking. Cette bibliothèque vous permet de visualiser la position des véhicules et des lieux d'intérêt suivis dans Fleet Engine. Il contient un composant de carte JavaScript qui remplace directement un objet google.maps.Map standard, ainsi que des composants de données à connecter à Fleet Engine. Ce composant vous permet d'offrir une expérience de suivi des livraisons animée et personnalisable à partir de votre application Web ou mobile.
Implémentez votre propre suivi des colis sur l'API Fleet Engine Deliveries.
L'essentiel est de rechercher les tâches d'expédition par ID de suivi.
Si vous utilisez un rôle Livraison, tous les appels d'API Fleet Engine Deliveries ne renvoient que des informations pertinentes pour un expéditeur ou un destinataire. Toutes les autres informations contenues dans les réponses sont masquées. Vous êtes responsable de l'authentification des utilisateurs finaux. De plus, les informations de localisation sont filtrées en fonction de la tâche en cours. Lors d'une tâche d'indisponibilité, aucune information de localisation n'est partagée avec un utilisateur final.
Journalisation
Vous pouvez configurer Fleet Engine pour qu'il envoie les journaux RPC à Cloud Logging. Pour en savoir plus, consultez la page Journalisation.
Rôles et jetons d'autorisation
Comme décrit dans la section Gérer le cycle de vie des véhicules 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
Si vous rencontrez des problèmes, consultez les sections suivantes pour obtenir de l'aide.
Résilience
Fleet Engine n'est pas considéré comme une source de référence. 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 utilisez Fleet Engine, implémentez des clients afin que le système se soigne lui-même 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 vérifications de quota sont en place pour éviter les attaques par déni de service (DOS). Dans ce cas, ralentissez le taux de recréation en utilisant une stratégie d'intervalle entre les tentatives pour les nouvelles tentatives.
État perdu dans l'application du conducteur
Si l'application pilote plante, elle doit recréer l'état actuel dans le SDK Driver. L'application doit essayer de recréer les tâches pour s'assurer qu'elles existent et restaurer leur état actuel. 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 pour une tâche dans le désordre ?
Dans ce cas, commencez par mettre à jour l'ordre des tâches, puis procédez comme d'habitude, en indiquant 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.