Modéliser les activités de votre parc pour les premier 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 à l'aide d'appels HTTP REST ou gRPC.
Configuration initiale
Vous configurez l'API Fleet Engine Deliveries dans la console Google Cloud.
Pour en savoir plus sur la procédure à suivre dans la console et sur la création un jeton Web JSON pour l'autorisation, consultez Authentification et autorisation
Pour en savoir plus sur l'utilisation de la console, consultez les Documentation de la console Google Cloud
Vérifier votre configuration
Après avoir créé des comptes de service, vérifiez que votre configuration est terminée et créer un véhicule de livraison. Vérification immédiate de votre configuration vous aide à résoudre les problèmes d'autorisation courants pouvant survenir 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 distribution de l'essai. la création de véhicules Utilitaire de ligne de commande
gcloud. Pour détails, consultez la section Vérification de la configuration .Testez votre configuration à l'aide de l' Exemples de scripts d'authentification pour Fleet Engine
Bibliothèques clientes
Pour une meilleure expérience développeur avec les protocoles gRPC ou REST bruts, utilisez bibliothèques clientes dans plusieurs langages de programmation courants. Pour sur la façon d'obtenir des bibliothèques clientes pour votre application de serveur, consultez 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 collecte et la livraison de livraisons:
- Véhicule de livraison utilisé pour transporter le colis.
- Les tâches d'enlèvement et de livraison de l'expédition.
Les tâches vous permettent également de modéliser les pauses au volant et les arrêts programmés. tout au long de la journée.
Véhicules de livraison
Les véhicules de livraison transportent les envois d'un dépôt à un lieu de livraison, et d'un 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.
Créer un objet DeliveryVehicle dans Fleet Engine à l'aide du SDK Driver
et d'envoyer des notifications de position
pour le suivi de l'expédition et de la flotte.
Tâches
Pour les actions effectuées par un véhicule au cours de la journée, vous attribuez les tâches en fonction le 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, attribuer des tâches d'indisponibilité.
- Pour les tâches qui ne sont pas à effectuer dans les boîtes de dépôt ou chez les clients, attribuez 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 l'heure d'arrivée prévue fenêtres pour chaque tâche, il utilise toutes les tâches et l'ordre dans lequel ils sont programmés pour faire des estimations. Pour en savoir plus sur les ID de tâche, consultez la page Consignes concernant les 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éer des tâches d'expédition pour le retrait et la livraison d'une commande inclure 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, regardez pour se garer ou marcher jusqu'au lieu de remise.
- 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 pendant les retraits ou les livraisons, comme des pauses pour ravitailler le véhicule ou le conducteur des pauses.
Créez une tâche d'indisponibilité à l'aide des informations suivantes:
- Durée de la coupure.
- Éventuellement, l'emplacement de la coupure publicitaire. Vous n'avez pas besoin de fournir un lieu spécifique, mais cela permet d'obtenir des heures d'arrivée prévues 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 dont un véhicule de livraison a besoin créer. Par exemple, créez une tâche d'arrêt planifiée pour un événement un arrêt de collecte à un endroit spécifique, indépendamment des autres livraisons ou des retraits au même endroit. 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 les transferts de véhicules d'actualisation de contenu ou s'arrête dans des centres de service ou 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 aucune information permettant d'identifier personnellement l'utilisateur. effacer des données textuelles.
- 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
Afficher les champs spécifiques contenus dans chaque donnée
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 d'un véhicule sauf si aucune tâche n'est active pour le véhicule d'origine.
Fleet Engine supprime automatiquement DeliveryVehicle objets qui n'ont pas
a été mis à jour avec UpdateDeliveryVehicle au bout de sept jours. La méthode recommandée
l'approche pour maintenir un véhicule disponible dans Fleet Engine consiste à mettre à jour sa position
à intervalles réguliers. Mises à jour de la plupart des autres champs dans DeliveryVehicle
entité prolonge également sa durée de vie, à condition que la nouvelle valeur du champ soit différente
de l'existant.
Pour voir si un véhicule existe:
- Appelez le
UpdateDeliveryVehicle. - Si vous obtenez une erreur NOT_FOUND, appelez
CreateDeliveryVehicle. pour recréer le véhicule. Si l'appel renvoie un véhicule, vous pouvez toujours le mettre à jour.
Type de véhicule
L'entité VehicleType comporte un champ facultatif VehicleType, qui contient un
É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
pour le type de véhicule.
Attributs du véhicule
L'entité DeliveryVehicle contient un champ répété de
DeliveryVehicleAttribute L'API ListDeliveryVehicles inclut un filter
qui peut limiter les entités DeliveryVehicle renvoyées à celles ayant le paramètre
attributs spécifiques. DeliveryVehicleAttribute n'a aucune incidence sur Fleet Engine
le comportement de routage.
N'incluez pas d'informations permettant d'identifier personnellement l'utilisateur ni d'informations sensibles. dans les attributs, car les utilisateurs peuvent voir ce champ.
Cycle de vie d'une tâche
Vous pouvez créer, mettre à jour et interroger des tâches dans Fleet Engine avec les interfaces gRPC ou REST de l'API Deliveries.
Un objet Task comporte un champ d'état permettant de suivre sa progression via
leur cycle de vie. Les valeurs passent de OPEN à CLOSED. Des tâches sont créées
à l'état OPEN (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 l'état de la tâche sur CLOSED (FERMÉ) automatiquement.
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 l'état de la tâche est automatiquement défini sur CLOSED. Pour en savoir plus, consultez Suivre votre expédition 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 après sept jours, et si vous essayez de créer une tâche avec un ID qui existe déjà, elle renvoie une erreur.
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 plus de sept jours, vous devez implémenter cette fonctionnalité vous-même.
Attributs de la tâche
L'entité Task contient un champ répété de
TaskAttribute, qui peut avoir une valeur de l'un des trois types suivants: chaîne, nombre
et bool. L'API ListTasks inclut un champ filter qui peut limiter les valeurs renvoyées
Task par celles avec les attributs spécifiés. Les attributs de tâche
sur le comportement de routage de Fleet Engine.
N'incluez pas d'informations permettant d'identifier personnellement l'utilisateur ni d'autres informations sensibles. informations dans les attributs, car ceux-ci peuvent être visibles par les utilisateurs.
Gérer le cycle de vie des véhicules et des tâches
Rappel: Votre système interne est la source fiable des données L'API Fleet Engine Deliveries effectue des optimisations en votre nom.
Pour gérer le cycle de vie des véhicules et des tâches dans votre système, utilisez l'API Fleet Engine Deliveries pour créer, mettre à jour et suivre vos véhicules et leurs tâches associées.
Dans le même temps, l'application de pilote communique directement avec Fleet Engine pour mettre à jour les informations de localisation et d'itinéraire de l'appareil. Ce modèle permet à Fleet Engine gérer efficacement la localisation en temps réel. Il envoie directement la position au qui vous permet d'informer les clients de l'état de leur ordre.
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 au bibliothèque de suivi, que votre application grand public utilise pour alerter le client à la proximité de leur colis.
- Une fois que le livreur a terminé la livraison, il clique sur "Colis livré". dans l'application pilote.
- La mention "Colis livré" envoie les informations à votre système backend, qui effectue les étapes nécessaires de validation et de validation de l'activité.
- Votre système confirme que la tâche a abouti et met à jour Fleet Engine à l'aide de la méthode API Deliveries.
Le schéma suivant illustre ces processus à un niveau générique. Il y a aussi indique la relation standard entre le système, le client et Fleet Engine.
Gérer les jetons client
Mises à jour de position provenant de l'application de pilote et envoyées directement vers Fleet Engine nécessitent des jetons d'autorisation. Approche recommandée pour gérer les mises à jour du client vers Fleet Engine:
Générez le jeton à l'aide de l'utilisateur Fleet Engine Delivery Untrusted Driver User rôle de compte de service.
Fournir à l'application pilote un jeton de champ d'application limité. Ce champ d'application ne lui permet de mettre à jour la localisation de l'appareil que dans Fleet Engine.
Cette approche garantit que les appels provenant d'appareils mobiles dans les environnements où la confiance est faible, principe du moindre privilège.
Autres rôles du compte de service
Si vous souhaitez autoriser les applications pilotes à effectuer les mises à jour de Fleet Engine autres que celles limitées au rôle de Conducteur non approuvé, par exemple pour certaines mises à jour de tâches, vous pouvez utiliser le rôle Conducteur de confiance. Pour sur un modèle utilisant le rôle Conducteur de confiance, consultez Modèle de pilote de confiance.
Pour en savoir plus sur les utilisations des rôles de pilote non fiables et de confiance, consultez Configuration d'un projet Cloud
Imaginer une journée de travail
Le tableau suivant décrit le déroulement d'une journée de travail pour les conducteurs empruntant le premier ou le dernier kilomètre pourrait ressembler à une entreprise de livraison et de logistique. Votre entreprise peut différents dans les détails, mais vous pouvez voir comment vous pouvez modéliser une journée de travail.
| Heure | 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 des tâches pour
les livraisons, les retraits, les pauses et
d'autres dans Fleet Engine à l'avance. Par exemple, vous pouvez créer un
la tâche de retrait en magasin,
tâche de livraison d'une commande,
indisponibilité planifiée
arrêt programmé.
Attribuer des tâches à un véhicule une fois que l'ensemble des colis de livraison et l'ordre dans lequel ils doivent être livrés sont finalisés. |
| Début de journée | Le conducteur commence 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 d’expédition n’ont pas été créées à l’avance, Créer des tâches de livraison au moment de la numérisation. | |
| Le conducteur confirme l'ordre des tâches à effectuer. | Si ce n'est pas le cas, créez tâches de retrait en magasin, indisponibilité planifiée Arrêts planifiés. | |
| Le conducteur quitte le dépôt et s'engage sur le nombre de tâches suivant terminé. | Attribuer toutes les tâches ou un sous-ensemble de tâches au véhicule en validant son ordre de finalisation. | |
| Le livreur livre un colis. | Une fois arrivé à l'arrêt de livraison, effectuez les actions associées à un véhicule arrivant à un arrêt. Après avoir livré la commande, fermez le de livraison et, éventuellement, état de la livraison en magasin et autres méta-informations. Après avoir effectué toutes les tâches à l'arrêt et avant qui commence à conduire jusqu'au prochain arrêt, un véhicule termine un arrêt et véhicule en route vers le prochain arrêt. | |
| Le livreur rencontre un véhicule d'alimentation pour y transférer d'autres colis. | Point de rendez-vous d'une correspondance entre le véhicule de restauration et le véhicule de livraison
doit être modélisé comme un arrêt planifié.
Après avoir transféré et scanné les envois, créez des tâches de livraison s'ils n'ont pas encore été créés. Ensuite, mettez à jour l’avancement de la tâche en attribuant des tâches à un véhicule et mettre à jour l'ordre des tâches. |
|
| Le conducteur reçoit une notification de demande de retrait. | Après avoir accepté la demande de retrait, créer une tâche de retrait en livraison. Ensuite, mettez à jour l'exécution de la tâche. en attribuant des tâches à un véhicule et mettre à jour 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
toute autre tâche. Effectuer des actions liées à un véhicule
arrivant à un arrêt,
véhicule s'arrête
et véhicule en route pour le prochain arrêt.
Sinon, aucune autre action n'est nécessaire avant la fin de la coupure. supprimer la tâche en confirmant les tâches suivantes et restantes ; et mettre à jour l'ordre des tâches. |
| Le livreur récupère un colis. | Il est modélisé comme un arrêt de livraison. Effectuer les actions associées à un véhicule arrivant à un arrêt. et la fermeture d'une tâche et, éventuellement, 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 à conduire au prochain arrêt, effectuez les actions associées aux véhicules qui passent par un arrêt et véhicule en route vers le prochain arrêt. Remarque: Pour garantir une facturation correcte, tous les retraits doivent disposer d'un de livraison. Si le retrait doit être livré dans une autre adresse du l'itinéraire d'un livreur ce jour-là, nous vous recommandons de modéliser cette tâche de livraison toute autre tâche de livraison sur l'itinéraire. Si le conducteur apporte la prise en charge au dépôt, nous vous conseillons de créer une tâche de livraison vers votre destination. | |
| 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. Effectuer les actions associées à un véhicule arrivant à un arrêt. et la fermeture d'une tâche. Une fois l'opération terminée toutes les tâches à l’arrêt et commencer à conduire jusqu’au prochain arrêt, Effectuer des actions en lien avec un véhicule arrêtant un arrêt et 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 de livraison pour le nouveau lieu de livraison. Pour plus d'informations, consultez la section Réacheminer un colis. | |
| Le conducteur a tenté de livrer un colis, mais n'y est pas parvenu. | Ce modèle est représenté de la même manière qu'un arrêt de livraison réussi, marquant le début de de livraison comme terminée. Effectuer des actions liées à Un véhicule arrivant à un arrêt Après l’échec de la livraison, fermer la tâche et, éventuellement, état de la livraison en magasin et autres méta-informations. Après avoir effectué toutes les tâches à l'arrêt et avant de commencer à conduire au prochain arrêt, effectuez les actions associées aux véhicules qui passent par un arrêt et 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 se dérouleront normalement. | |
| 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 associées à un véhicule arrivant à un arrêt. Après avoir livré chaque envoi, fermez chaque tâche. et, éventuellement, état de la livraison en magasin et autres méta-informations. Après avoir effectué toutes les tâches à l'arrêt et avant de commencer à conduire au prochain arrêt, effectuez les actions associées aux véhicules qui passent par un arrêt et 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 vous devez aussi créer et clôturer chaque package en tant que tâche de livraison pour garantir une facturation correcte. Pour ce faire, vous pouvez modéliser le dépôt autre arrêt de livraison. Si le dépôt n'est pas utilisé comme arrêt de livraison, vous avez toujours la possibilité le dépôt 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 fournir une visibilité sur le temps estimé de l'arrivée. |
Fonctionnement des mises à jour de la position
Pour optimiser les performances de Fleet Engine, fournissez un flux de véhicules mises à jour de la position géographique. Pour fournir ces mises à jour, utilisez l'une des méthodes suivantes:
- Utiliser le SDK Driver – Android iOS est l'option la plus simple.
- Utilisez un code personnalisé (utile si les lieux sont transmis via votre backend, ou si vous utilisez des appareils autres qu'Android ou iOS
Quelle que soit la façon dont vous fournissez les mises à jour de la position des véhicules, votre backend est qui est responsable de la mise à jour de Fleet Engine lorsqu'un véhicule de livraison en route vers un arrêt (y compris le dépôt) et lorsqu'il arrive à un arrêt. Fleet Engine ne détecte pas ces événements automatiquement.
Arrêts de véhicules et lieux de livraison
Un arrêt 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 position fermée.
Le lieu de livraison est le lieu de livraison du colis. ou retiré. Vous devrez peut-être marcher pour vous rendre au lieu de livraison et en revenir de l'arrêt du véhicule.
Par exemple, lorsqu'un livreur livre une livraison à un magasin dans un centre commercial, le véhicule de livraison s'arrête sur le parking du centre commercial à proximité l'entrée la plus proche du magasin. Il s'agit de l'arrêt du véhicule. Le conducteur puis marche de l'arrêt du véhicule jusqu'au centre commercial où où se trouve le magasin. Il s'agit du lieu de livraison.
Pour optimiser l'expérience de suivi des livraisons de vos utilisateurs, réfléchissez à la manière dont les tâches d'expédition sont affectées aux arrêts des véhicules et n'oubliez pas que le nombre les arrêts restants du véhicule pour les tâches d'expédition sont signalés à l'utilisateur afin de l'aider consulter la progression de leur expédition.
Par exemple, si un chauffeur effectue de nombreuses livraisons dans un seul immeuble de bureaux, envisagez d'affecter toutes les tâches de livraison à un seul arrêt de véhicule. Si chaque tâche de livraison est attribuée à son propre arrêt de véhicule, votre livraison expérience de suivi serait moins utile pour vos utilisateurs puisque le suivi n’est disponible lorsque le véhicule est à moins d'un certain nombre d'arrêts avant sa destination. Avoir de nombreux arrêts de véhicule terminés en peu de temps ne beaucoup de temps à un 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, assurez-vous pour 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 les suivants : opaque pour Fleet Engine. Évitez d'utiliser des ID d'incrémentation automatique 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 de la SDK Driver, ou à partir d'un environnement de serveur avec 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 de
le nouveau véhicule de livraison. Notez que toute valeur spécifiée dans le champ Name ne sera
ignorés conformément aux instructions de l'API pour les ID spécifiés par l'utilisateur.
Vous devez utiliser le champ DeliveryVehicleId pour définir l'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 quitter le
Champ DeliveryVehicle non défini dans CreateDeliveryVehicleRequest.
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour créer un véhicule:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour créer un véhicule à partir d'un environnement de serveur, effectuez un appel HTTP REST
vers 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.
requête vide. Le véhicule que vous venez de créer extrait ensuite un identifiant 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 de la SDK Driver ou depuis un environnement de serveur à l'aide de gRPC ou REST.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour créer une tâche de retrait en magasin:
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 d'une livraison à partir d'un environnement de serveur, effectuez un appel REST HTTP
vers 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 pour la livraison. Si vous n'avez pas d'ID de tâche dans votre système, vous pouvez générer un identifiant unique universel (UUID).
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit contenir une entité Task:
Champs obligatoires :
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 d'enlèvement du colis. taskDuration Le délai estimé, en secondes, pour récupérer le colis au lieu de prise en charge. Champs facultatifs :
Champ Valeur targetTimeWindow La période pendant laquelle la tâche doit être terminée. Cela ne concerne pas affectent 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. Lancers Fleet Engine
une exception si la requête inclut un deliveryVehicleId attribué. Vous attribuez
tâches à l'aide de UpdateDeliveryVehicleRequest. Pour en savoir plus, consultez
Attribuez 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 depuis la SDK Driver ou depuis un environnement de serveur à l'aide de gRPC ou REST.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour créer une tâche de livraison:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour créer une tâche de livraison d'envoi à partir d'un environnement de serveur à l'aide de gRPC ou REST, effectuez un appel HTTP REST
vers 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 pour la livraison. Si vous n'avez pas d'ID de tâche dans votre système, vous pouvez générer un identifiant unique universel (UUID).
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit contenir une entité Task:
Champs obligatoires :
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 cette livraison. taskDuration Le 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 ne concerne pas affectent 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. Lancers Fleet Engine
une exception si la demande inclut un "deliveryVehicleId" attribué. Vous attribuez
tâches à l'aide de UpdateDeliveryVehicleRequest. Pour en savoir plus, consultez
Attribuez 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 classe Bibliothèque Java gRPC pour créer deux tâches en même temps, l'une pour la livraison et l'autre pour le retrait lieu:
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 une
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. <jeton>, où <jeton> 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 de requests doit passer la même validation
en tant que requête CreateTask, à l'exception du fait que parent
et header sont facultatifs. S'ils sont définis, ils doivent être identiques aux
leurs champs respectifs au niveau supérieur BatchCreateTasksRequest. Voir
créer une tâche de retrait en livraison ;
créer une tâche de livraison
pour connaître les règles de validation propres à chacun.
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 un pilote ou de ravitaillement du véhicule) à partir de la SDK Driver ou depuis un environnement de serveur à l'aide de gRPC ou REST. Une tâche d'indisponibilité planifiée ne doit pas inclure un ID de suivi. Vous pouvez éventuellement indiquer un lieu.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour créer une tâche d'indisponibilité:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour créer une tâche d'indisponibilité à partir d'un environnement de serveur, effectuez un appel HTTP REST
vers CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> est un identifiant unique pour la tâche. Si vous ne n'ont pas d'ID de tâche dans votre système, vous pouvez générer (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. Lancers Fleet Engine
une exception si la demande inclut un "deliveryVehicleId" attribué. Vous attribuez
tâches à l'aide de UpdateDeliveryVehicleRequest. Pour en savoir plus, consultez
Attribuez 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 depuis la SDK Driver ou depuis un environnement de serveur à l'aide de gRPC ou REST. Une tâche d'arrêt planifiée peut ne pas inclure d'élément de suivi ID.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour créer une tâche d'arrêt planifiée:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour créer une tâche d'arrêt planifiée à partir d'un environnement de serveur, effectuez un appel HTTP REST
vers CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> est un identifiant unique pour la tâche. Si vous ne disposez pas de tâche dans votre système, vous pouvez générer un identifiant unique universel (UUID).
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit contenir une entité Task:
Champs obligatoires :
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. Lancers Fleet Engine
une exception si la demande inclut un "deliveryVehicleId" attribué. Vous attribuez
tâches à l'aide de UpdateDeliveryVehicleRequest. Pour en savoir plus, consultez
Attribuez 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 fenêtre cible est la TimeWindow pendant laquelle la tâche doit être terminée. Par exemple, si vous indiquez de livraison aux destinataires, vous pouvez utiliser l'heure cible de la tâche pour capturer cette fenêtre, et générer des alertes ou analyser les données après le trajet à l'aide du champ.
La fenêtre cible se compose d'une heure de début et d'une heure de fin. Vous pouvez la définir sur n'importe quel type de tâche. La fenêtre cible n'affecte pas le routage comportemental.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour définir une fenêtre de temps de tâche:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour définir une fenêtre de temps de tâche à l'aide du protocole HTTP, appelez UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<id> est un identifiant unique pour la tâche.
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit contenir une entité Task:
Champs obligatoires :
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
Visibilité des données dans la bibliothèque de suivi des expéditions et de ces données
renvoyés par un appel à GetTaskTrackingInfo peuvent être contrôlés au niveau de chaque tâche
en définissant
TaskTrackingViewConfig
sur la tâche. Voir
Tâches actives sur le véhicule
pour en savoir plus. Vous pouvez le faire lors de la création ou de la mise à jour
tâche. Voici un exemple de mise à jour de la tâche avec cette configuration:
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour définir la configuration de la vue de suivi des tâches:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskTrackingViewConfig(
TaskTrackingViewConfig.newBuilder()
.setRoutePolylinePointsVisibility(
VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
.setEstimatedArrivalTimeVisibility(
VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
.setRemainingStopCountVisibility(
VisibilityOption.newBuilder().setNever(true)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour définir la fenêtre de configuration de la vue de suivi des tâches à l'aide du protocole HTTP, appelez UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<id> est un identifiant unique pour la tâche.
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit contenir une entité Task:
Champs obligatoires :
Champ Valeur taskTrackingViewConfig Configuration du suivi des tâches qui spécifie les é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
Vous attribuez des tâches à un véhicule de livraison en mettant à jour l'ordre des tâches pour le véhicule. L'ordre des tâches pour un véhicule est déterminé par la liste d'arrêts du véhicule de livraison, et vous pouvez attribuer une ou plusieurs tâches à chaque arrêt de véhicule. Pour en savoir plus, consultez Mettez à jour l'ordre des tâches.
Pour passer d'un véhicule à un autre, fermez la tâche d'origine. puis le recréer avant de lui attribuer le nouveau véhicule. Si vous modifiez la tâche 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 modifier l'ordre d'exécution des tâches attribuées à un véhicule : la SDK Driver ou l'environnement du serveur. N'utilisez pas les deux méthodes pour éviter les conditions de concurrence et maintenir une source unique de vérité.
Lorsque vous 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 le sont pas dans le nouvel ordre.
Pour passer d'un véhicule à un autre en livraison, fermer la tâche d'origine puis le recréer avant de lui attribuer le nouveau véhicule. Si vous modifiez la tâche 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 classe Bibliothèque Java gRPC 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 pour un véhicule à partir d'un environnement de serveur, effectuez un appel HTTP REST
vers 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 laquelle 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. remainingVehicleJourneySegments[i].stop Arrêt de la tâche i dans la liste. remainingVehicleJourneySegments[i].stop.plannedLocation Emplacement prévu de l'arrêt. remainingVehicleJourneySegments[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 part d'un arrêt ou démarre la navigation. Vous pouvez informer Fleet Engine à partir de la SDK Driver ou depuis un environnement de serveur à l'aide de gRPC ou REST. N'utilisez pas les deux méthodes pour éviter l'origine ethnique les conditions et de maintenir une source unique de vérité.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour informer Fleet Engine qu'un véhicule est en route pour 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 depuis
serveur, effectuez un appel REST HTTP à 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 laquelle 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 effectuer une appel direct à Fleet Engine avec l'emplacement du véhicule. Pour tout véhicule actif, Fleet Engine attend une mise à jour de la position au moins une fois par minute et au maximum toutes les 5 secondes.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC 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 la
UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`
<id> est l'identifiant unique du véhicule de livraison associé à votre ou si 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 avertir Fleet Engine à partir de SDK Driver ou depuis un environnement de serveur à l'aide de gRPC ou REST. N'utilisez pas les deux méthodes pour éviter l'origine ethnique les conditions et de maintenir une source unique de vérité.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour informer Fleet Engine qu'un véhicule est arrivé à un arrêt:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// 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 depuis un environnement de serveurs,
effectuez un appel HTTP REST vers 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 laquelle 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 Vous êtes arrivé à l'arrêt dont l'état est défini sur State.ARRIVED. suivi d'une liste des arrêts restants du véhicule, avec leur état défini sur 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. Cela provoque toutes les tâches associées à l'arrêt soient définies sur l'état CLOSED. Vous pouvez informer Fleet Engine à partir de la 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 classe Bibliothèque Java gRPC pour informer 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'arrêt d'un environnement de serveur,
effectuez un appel HTTP REST vers 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 laquelle 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. Cependant, vous pouvez modifier l'état, le résultat de la tâche, le résultat de la tâche, l’emplacement du résultat de la tâche et les attributs par en mettant directement à jour l'entité de tâche. Par exemple, lorsqu'une tâche n'a pas encore attribuée à un véhicule, vous pouvez fermer la tâche en mettant à jour directement.
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 le supprimer de la liste des arrêts du véhicule. Pour ce faire, vous pouvez définir la liste le véhicule restant s'arrête, comme lors de la mise à jour de 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, mettez-la à jour à 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. Elle indique que le tâche n'est plus considérée comme étant en cours. Pour le suivi des expéditions, il est important d'indiquer le résultat réel d'une tâche afin qu'une livraison le résultat peut être affiché.
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 dans un environnement de serveur, effectuez un appel HTTP REST vers
UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`
<id> est un identifiant unique pour la tâche.
L'en-tête de votre 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. La valeur par défaut de Fleet Engine jusqu'à la dernière position du véhicule, sauf s'il a été remplacé manuellement par le fournisseur.
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
Le bouclage d'une tâche n'indique pas le succès ou l'échec, il 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 qu'un le résultat de la livraison peut être affiché et que la facturation des services est correcte. Une fois défini, vous ne pouvez plus modifier le résultat de la tâche. En revanche, vous pouvez modifier le temps du résultat de la tâche et le lieu du résultat de la tâche après qu'ils ont été définis.
Le résultat des tâches à l'état FERMÉE peut être défini sur SUCCEEDED (Réussite) ou FAILED (ÉCHEC). Fleet Engine ne facture que les tâches de livraison dont l'état est RÉUSSITE.
Lorsque vous marquez le résultat d'une tâche, Fleet Engine remplit automatiquement le le lieu 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. La définition de l'emplacement empêche Fleet Engine de le définir à la valeur par défaut du dernier la position du véhicule. Vous pouvez également écraser l'emplacement du résultat de la tâche Fleet Engine à une date ultérieure. Fleet Engine n'écrase jamais l'emplacement du résultat d'une tâche que vous fournissez. Vous ne pouvez pas définir un lieu de résultat pour une tâche qui n'a pas de résultat de tâche. Vous pouvez définir à la fois le résultat de la tâche et l'emplacement du résultat de la tâche dans la même requête.
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour définir le résultat d'une tâche sur SUCCEEDED et définir l'emplacement de la tâche terminé:
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 HTTP REST vers 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 ce champ n'est pas défini, Fleet Engine la valeur par défaut est 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 colis, fermez la tâche d'envoi sans définir un résultat, puis créez une nouvelle tâche avec le lieu planifié mis à jour. Après avoir créé la tâche, attribuez-la au même véhicule. Pour plus plus d'informations, consultez la section Fermer la tâche d'envoi et attribuer la tâche.
Utiliser des chargeurs et des véhicules de livraison
Si vous utilisez des véhicules de ravitaillement pour le transport des colis vers des véhicules de livraison tout au long de la journée, modéliser le transfert des expéditions en tant que tâche d'arrêt planifiée pour le véhicule de livraison. Pour garantir un suivi précis de votre position, n'attribuez une tâche de livraison pour un colis transféré, après son chargement sur le un 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 la tâche. Toutefois, vous pouvez mettre à jour d'autres méta-informations spécifiques à la livraison. Pour stocker d'autres méta-informations que vous pouvez en dehors du service Fleet Engine, utilisez l'identifiant de suivi associé avec 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 SDK Driver ou depuis un environnement de serveur à l'aide de gRPC ou REST.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour rechercher un véhicule:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour rechercher un véhicule
dans un environnement de serveurs,
effectuez un appel HTTP REST vers 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 pour rechercher une tâche.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour rechercher une tâche:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder() // No need for the header
.setName(taskName)
.build();
try {
Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour rechercher une tâche
à partir d'un environnement de serveur,
effectuez un appel HTTP REST vers 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 comme suit : chacun ayant un objectif distinct:
- par un ID de tâche: utilisé par les utilisateurs tels que les opérateurs de parc ayant accès au une vue complète des données des tâches.
- par un ID de suivi: utilisé par votre logiciel client pour fournir des d'informations à un utilisateur final, telles que la date à laquelle 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 voulez Pour rechercher une tâche par son ID, accédez à 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é comme indiqué dans Contrôlez la visibilité des lieux suivis.
Utilisez Fleet Engine pour rechercher des informations sur la livraison à l'aide de l'ID de suivi. Le Pilote Le SDK ne permet pas de rechercher des informations par ID de suivi. Pour ce faire avec Fleet 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 si vous utilisez un jeton Delivery Consumer, tout appel d'API Fleet Engine Deliveries renvoie que les informations pertinentes pour cet utilisateur final, comme le transporteur ou le destinataire d'un envoi. Toutes les autres informations contenues dans les réponses sont masquées. Pour en savoir plus sur les jetons, consultez 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 classe Bibliothèque Java gRPC pour rechercher des informations sur une tâche d'expédition grâce à 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 HTTP REST vers
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 <jeton>, où <jeton> est un jeton émis par une fabrique de jetons Fleet Engine.
Si la recherche aboutit, le corps de la réponse contient une taskTrackingInfo entité.
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 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 des utilisateurs de confiance. Utiliser l'authentification du lecteur de parc de livraison ou du super-utilisateur des livraisons Jetons lors des requêtes de liste de tâches.
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 la syntaxe des requêtes de filtre, voir AIP-160. La liste suivante répertorie les tâches 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 |
|---|---|---|
| Horodatage | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
| Durée | Nombre de secondes suivies d'un s |
task_duration = 120s |
| Énumération | 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 requêtes de filtre. les opérateurs.
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 que la taille de page spécifiée. Si aucune taille de page n'est indiquée, une valeur par défaut raisonnable est utilisé. Si la taille de page demandée dépasse une valeur maximale interne, alors la valeur maximale interne est utilisée.
Une liste de tâches peut inclure un jeton permettant de lire la page de résultats suivante. Utilisez le jeton de page avec une requête 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, aucune autre tâche n'est disponible pour la récupération.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour répertorier les tâches pour un deliveryVehicleId et un attribut de tâche. Une campagne peut encore être vide. Une réponse vide indique qu'aucune tâche n'est l'ID 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, ajoutez un "filtre" Paramètre d'URL 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âches correspondant aux critères de filtrage spécifiés ont été trouvé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}/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 Pilote Le SDK ne permet pas de présenter des véhicules de livraison.
Répertorier des véhicules de livraison demande un accès étendu aux véhicules de livraison et est destiné uniquement à des utilisateurs de confiance. Utiliser Delivery Fleet Reader ou Delivery Super Jetons d'authentification utilisateur lors des requêtes de livraison de listes de véhicules
Les champs suivants sont masqués pour les véhicules de livraison répertoriés en raison de leur impact sur la taille de réponse:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
Vous pouvez filtrer la liste des véhicules de livraison selon leur propriété attributes. Pour
Par exemple, pour interroger un attribut avec la clé my_key et la valeur my_value, utilisez
attributes.my_key = my_value Pour effectuer une requête portant sur plusieurs attributs, effectuez des requêtes de jointure
en utilisant les opérateurs logiques AND et OR, comme dans attributes.key1 = value1 AND
attributes.key2 = value2. Reportez-vous à la norme AIP-160
description de la syntaxe d'une requête de filtre.
Vous pouvez filtrer les véhicules de livraison listés par lieu à l'aide de la requête viewport
. Le paramètre de requête viewport définit les fenêtres d'affichage à l'aide de deux limites
coordonnées: une latitude et une longitude de high (nord-est) et de low (sud-ouest)
de coordonnées. Les requêtes contenant une latitude élevée sont refusées
située géographiquement
inférieure à une faible latitude.
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 la valeur maximale interne est utilisée. Le nombre de pages par défaut et le nombre maximal de pages 100 véhicules.
Une liste de véhicules de livraison peut inclure un jeton permettant de lire la page suivante résultats. Un jeton de page n'est présent dans une réponse que lorsque davantage de pages de diffusion les véhicules peuvent être récupérés. Pour récupérer la page de tâches suivante, utilisez le jeton de page par une requête, par ailleurs identique à la requête requête.
gRPC
L'exemple suivant montre comment utiliser la classe Bibliothèque Java gRPC pour répertorier les véhicules de livraison d'une région spécifique à l'aide d'un certain attribut. A de réponse positive peut toujours être vide. Lorsque cela se produit, cela signifie qu’aucune les véhicules avec l'attribut spécifié se trouvent 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, ajoutez un "filtre" paramètre d'URL avec un 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. Lorsque cela se produit, cela signifie qu’aucune que des véhicules de livraison correspondent à 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
Deux options s'offrent à vous pour utiliser l'API Fleet Engine Deliveries pour activer le suivi des expéditions:
Recommandé:Utilisez le Bibliothèque JavaScript Shipment Tracking. La bibliothèque vous permet de visualiser l'emplacement des véhicules et des emplacements suivis dans Fleet Engine. Il contient un composant de carte JavaScript qui remplace directement un objet google.maps.Map standard, et composants de données pour se connecter à Fleet Engine. Ce composant vous permet Proposez une expérience de suivi des colis animée et personnalisable. depuis 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 le rôle Consommateur Livraison, tous les appels d'API Fleet Engine Deliveries renvoyer uniquement des informations pertinentes pour un expéditeur ou un destinataire. Toutes les autres les informations contenues dans les réponses sont masquées. Vous êtes responsable pour authentifier les utilisateurs finaux. De plus, les informations de localisation sont filtrées en fonction de la tâche déjà effectuée. Pendant 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 plus pour en savoir plus, consultez Journalisation.
Rôles et jetons d'autorisation
Comme décrit dans Gérer le cycle de vie des véhicules et des tâches et les notes d'autorisation pour chaque cas d'utilisation. les appels à Fleet Engine nécessitent une authentification avec des jetons Web JSON signé à l'aide des identifiants du compte de service. Les comptes de service utilisés pour émettre ces jetons peuvent avoir un ou plusieurs rôles, chacun accordant un autre ensemble d'autorisations.
Pour en savoir plus, consultez 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 pour restaurer l'état de votre système, si nécessaire, sans dépendre Fleet Engine.
État perdu dans Fleet Engine
Lorsque vous travaillez avec Fleet Engine, mettez en œuvre des clients pour que le système répare en cas de défaillance. Par exemple, lorsque Fleet Engine tente de mettre à jour véhicule, il peut renvoyer une erreur indiquant que le véhicule n'est pas existent. Le client doit ensuite recréer le véhicule dans le nouvel état. Bien que ce problème survient rarement, assurez-vous que votre système est suffisamment résilient pour 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 de nouvelles tentatives.
État perdu dans l'application du conducteur
Si l'application du pilote plante, elle doit recréer l'état actuel. dans le SDK Driver. L'application doit tenter de recréer les tâches pour s'assurer et restaurer leur état actuel. L'application doit également recréez et définissez 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 continuez comme d'habitude, l'indication de l'arrivée à l'arrêt, la fin 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.