L'API Fleet Engine Deliveries vous permet de modéliser les activités de votre parc pour le premier et le dernier kilomètre des livraisons. L'API Deliveries est exposée via le SDK Driver pour Android et iOS. Elle peut également être utilisée directement via des appels HTTP REST ou gRPC.
Configuration initiale
L'API Fleet Engine Deliveries est configurée via Google Cloud Console. Pour en savoir plus sur la procédure à suivre dans la console et sur la création d'un jeton Web JSON pour l'autorisation, consultez la page Authentification et autorisation. Pour en savoir plus sur l'utilisation de la console, consultez la documentation de la console Google Cloud.
Vérifier votre configuration
Après avoir créé les comptes de service, vous devez vérifier que la configuration est terminée et que vous pouvez créer un véhicule de livraison. En effectuant la validation à cette étape du workflow, vous vous assurez de résoudre les problèmes d'autorisation courants qui peuvent survenir lors de la configuration de votre projet. Suivez le guide Vérifier la configuration.
Ce guide fournit des informations détaillées sur l'utilisation de l'utilitaire de ligne de commande gcloud afin de tester deux éléments clés de votre configuration: la signature des jetons d'autorisation et la création d'un véhicule d'essai.
Vous pouvez également utiliser les exemples de scripts d'authentification Fleet Engine pour tester votre configuration.
Bibliothèques clientes
Nous publions des bibliothèques clientes dans plusieurs langages de programmation courants. Ces bibliothèques offrent une meilleure expérience aux développeurs par rapport aux serveurs REST ou gRPC bruts. Pour savoir comment obtenir des bibliothèques clientes pour votre application serveur, consultez la page Bibliothèques clientes.
Les exemples Java de cette documentation supposent que vous connaissez bien gRPC.
Structures de données
L'API Deliveries utilise deux structures de données pour modéliser le retrait et la livraison des expéditions:
- Véhicule de livraison utilisé pour transporter le colis
- Tâches de retrait et de livraison de la commande.
De plus, vous pouvez utiliser des tâches pour modéliser les pauses du pilote et les arrêts planifiés tout au long de la journée.
Véhicules de livraison
Les véhicules de livraison transportent les commandes d'un dépôt à un lieu de livraison et d'un point de retrait au dépôt. Dans certains cas, il peut également expédier un colis directement du lieu de retrait vers le lieu de livraison.
Vous pouvez utiliser le SDK Driver pour créer un objet DeliveryVehicle dans Fleet Engine et envoyer des mises à jour de la position pour le suivi des expéditions et de la flotte.
Tâches
Des tâches sont attribuées à chaque véhicule. Il peut s'agir de prises en charge ou de livraison, de pauses obligatoires pour les chauffeurs, ou d'arrêts programmés dans des points de dépôt ou chez des clients. Chaque tâche doit avoir un ID de tâche unique, mais peut partager le même ID de suivi. Les tâches et l'ordre dans lequel elles sont planifiées sont utilisés pour calculer les fenêtres d'heure d'arrivée pour chaque tâche.
Utilisez le gestionnaire de tâches du SDK du pilote pour créer des tâches dans Fleet Engine.
Tâches d'expédition
Les tâches d'expédition sont liées au retrait ou au dépôt. Vous devez spécifier un numéro de suivi ou un ID lorsque vous créez une tâche d'expédition. Vous devez également spécifier un temps d'attente pour tenir compte du temps supplémentaire pour effectuer la tâche, rechercher un parking ou marcher jusqu'au lieu de transfert.
- Créez une tâche de retrait pour récupérer une livraison, en spécifiant le lieu de retrait et l'ID ou le numéro de suivi.
- Créez une tâche de livraison pour la livraison, en spécifiant l'emplacement de livraison et le numéro ou l'ID de suivi.
Tâches d'indisponibilité
Créez une tâche d'indisponibilité pour une période pendant laquelle le véhicule ne peut pas être retiré ni livré. Il peut s'agir d'une pause pour faire le plein ou d'un repos au volant.
Spécifiez la durée de la coupure lorsque vous créez la tâche. Il n'est pas nécessaire de faire des pauses dans un lieu spécifique, mais la spécification d'un lieu fournit des fenêtres d'heure d'arrivée plus précises tout au long de la journée.
Tâches d'arrêt planifié
Créez des tâches d'arrêt planifiées pour modéliser les arrêts à effectuer par un véhicule de livraison. Par exemple, vous pouvez créer une tâche d'arrêt planifié pour un arrêt de collecte quotidien planifié à un emplacement spécifique, indépendamment des autres livraisons ou retraits au même emplacement. Vous pouvez également créer des tâches d'arrêt planifiées pour les collections à partir de boîtes de dépôt, ou pour modéliser les transferts ou les arrêts des bases d'actualisation de contenu dans les centres de service et les points de service.
Vous pouvez voir les champs spécifiques contenus dans chaque structure de données en consultant la documentation de référence de l'API pour DeliveryVehicle (gRPC, REST et Task (gRPC, REST).
Consignes pour l'ID de tâche
Les ID de tâche doivent être uniques et ne pas afficher d'informations personnelles ni de texte clair.
Les ID de tâche doivent respecter les exigences de format suivantes:
- Les ID doivent être des chaînes Unicode valides.
- Les ID ne doivent pas comporter plus de 64 caractères.
- Les identifiants sont normalisés conformément au formulaire de normalisation C Unicode.
- Les ID ne doivent pas contenir les caractères ASCII suivants: "/", ":", "\", "?" ou "#".
Voici quelques exemples d'ID de tâche valides:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
Le tableau suivant présente des exemples d'ID de tâche non valides:
| ID de tâche non valide | Motif |
|---|---|
| 31/08/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | Non-respect des exigences relatives aux informations personnelles et aux caractères: virgules, points, deux-points et barres obliques |
| JohnDoe-577b484da26f-Cupertino-SantaCruz | Non-respect des exigences relatives aux informations permettant d'identifier personnellement les utilisateurs. |
| 4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a | Non-respect des exigences en matière d'informations personnelles et de caractères: espaces, virgules et guillemets Plus de 64 caractères. |
La vie d'un véhicule
L'objet DeliveryVehicle représente un véhicule de livraison de premier ou de dernier kilomètre.
Pour créer un objet DeliveryVehicle, utilisez:
- ID du projet Google Cloud contenant le compte de service utilisé pour appeler les API Fleet Engine.
- ID du véhicule appartenant au client.
Les identifiants des véhicules doivent être uniques pour chaque véhicule. Ils ne doivent pas être réutilisés pour un autre véhicule, sauf si aucune tâche n'est active pour ce véhicule.
Veillez à rechercher une erreur NOT_FOUND lorsque vous appelez UpdateDeliveryVehicle, puis, si nécessaire, appelez CreateDeliveryVehicle pour créer un véhicule. Un objet DeliveryVehicle qui n'a pas été mis à jour à l'aide de UpdateDeliveryVehicle est automatiquement supprimé au bout de sept jours. Notez qu'appeler CreateDeliveryVehicle avec une paire ID de projet/ID de véhicule qui existe déjà génère une erreur.
Attributs du véhicule
L'entité DeliveryVehicle contient un champ répété de DeliveryVehicleAttribute. Ces attributs ne sont pas interprétés par Fleet Engine. L'API ListDeliveryVehicles inclut un champ filter qui peut limiter les entités DeliveryVehicle renvoyées à celles possédant les attributs spécifiés.
Bien que le champ attributes soit opaque pour Fleet Engine, n'incluez pas d'informations personnelles ni sensibles dans les attributs, car ce champ pourrait être visible par les utilisateurs.
Cycle de vie d'une tâche
Vous pouvez créer, mettre à jour et interroger des tâches dans Fleet Engine à l'aide des interfaces gRPC ou de l'API Deliveries.
Un objet Task possède un champ d'état permettant de suivre sa progression tout au long de son cycle de vie. Les valeurs passent de OPEN à CLOSED. Les tâches sont créées à l'état OUVERT, ce qui indique que:
- La tâche n'a pas encore été attribuée à un véhicule de livraison.
- Le véhicule de livraison n'a pas encore dépassé l'arrêt attribué à la tâche.
Une tâche ne peut être attribuée à un véhicule que lorsqu'elle est OUVERTE.
Vous pouvez annuler une tâche en la supprimant de la liste des arrêts du véhicule. Son état est ensuite automatiquement défini sur FERMÉ.
Lorsque le véhicule de la tâche termine l'arrêt du véhicule, mettez à jour le champ de résultat de la tâche sur SUCCEEDED ou FAILED, puis spécifiez l'horodatage de l'événement. Le résultat de la tâche peut être défini à tout moment avant ou après la fin de la tâche, mais ne peut être défini qu'une seule fois.
La bibliothèque JavaScript Shipment Tracking peut ensuite indiquer le résultat de la tâche. L'état de la tâche est automatiquement défini sur CLOSED. Pour en savoir plus, consultez la page Suivre les envois avec la bibliothèque de suivi des envois JavaScript.
Comme pour les véhicules, les tâches qui n'ont pas été mises à jour après sept jours sont supprimées. Toute tentative de création d'une tâche avec un ID qui existe déjà 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 mise à jour. Si vous souhaitez conserver les données des tâches plus de sept jours, vous devez implémenter cette fonctionnalité vous-même.
Intégrer l'API Deliveries
Vous pouvez intégrer l'API Deliveries à l'aide d'un modèle non approuvé ou fiable, qui détermine les mises à jour que vous pouvez effectuer à l'aide du SDK du pilote. Le modèle non approuvé est préférable. Le modèle approuvé est en version bêta.
Modèle non approuvé
Dans le cas d'un modèle non approuvé, vous utilisez le rôle Fleet Engine Delivery Untrusted Driver User (Utilisateur de pilote de confiance dans le cadre de la livraison du parc) pour autoriser la mise à jour de l'emplacement du véhicule de livraison. Les jetons émis par un compte de service doté de ce rôle sont généralement utilisés depuis les appareils mobiles du livreur.
Modèle de confiance
Avec un modèle de confiance, disponible en aperçu, vous utilisez le rôle Fleet Engine Delivery Trusted Driver User pour accorder l'autorisation de créer et de mettre à jour des véhicules de livraison et des tâches de livraison, y compris l'emplacement et l'état des tâches du véhicule de livraison. Les jetons émis par un compte de service doté de ce rôle sont généralement utilisés depuis les appareils mobiles du livreur ou vos serveurs backend.
Pour en savoir plus sur les rôles de la solution Google Cloud Platform Last Fleet pour les modèles fiables et non approuvés, consultez la page Configuration du projet Cloud.
Une intégration complète à partir d'appareils mobiles ne doit être effectuée que si vous possédez et gérez les appareils. Cela leur assure une totale confiance. Vous pouvez ensuite créer des véhicules et des tâches directement à partir du SDK du pilote.
Remarque:Pour des raisons de sécurité, vous ne devez émettre des jetons que sur vos serveurs backend, puis les partager avec des clients.
Modéliser une journée de travail
Le tableau suivant décrit le déroulement d'une journée de travail pour les livreurs de premier ou de dernier kilomètre dans une entreprise de livraison et de logistique. Les détails de votre entreprise peuvent différer, mais vous pouvez voir comment vous pourriez modéliser une journée de travail.
| Durée | Activité | Modélisation |
|---|---|---|
| Dans les 24 heures en début de journée | Le coordinateur attribue les expéditions aux véhicules de transport ou aux itinéraires. | Les tâches de livraison, de retrait, de pause, etc. peuvent être créées à l'avance dans Fleet Engine. Par exemple, vous pouvez créer une tâche de retrait en magasin, une tâche de livraison, une indisponibilité planifiée ou un arrêt planifié.
Une fois que l'ensemble de packages de livraison et l'ordre de livraison sont définis, les tâches doivent être attribuées à un véhicule. |
| Début de journée | Le conducteur commence la journée au dépôt en se connectant à l'application du conducteur. | Initialisez l'API Delivery Driver. Créez le véhicule de livraison dans Fleet Engine si nécessaire. |
| Le conducteur charge les colis dans le véhicule de livraison en les scannant. | Si des tâches de livraison n'ont pas été créées à l'avance, créez des tâches de livraison au moment de la numérisation. | |
| Le pilote confirme l'ordre des tâches à effectuer. | S'ils n'ont pas été créés à l'avance, créez des tâches de retrait en magasin, une indisponibilité planifiée et des arrêts planifiés. | |
| Le pilote quitte le dépôt et valide le nombre de tâches suivantes. | Attribuez toutes les tâches ou un sous-ensemble de tâches au véhicule en validant leur ordre d'exécution. | |
| 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. Une fois la livraison expédiée, fermez la tâche de livraison et, si vous le souhaitez, stockez l'état de la livraison et autres métadonnées. Après avoir effectué toutes les tâches à l'arrêt et avant de commencer à prendre la route vers le prochain arrêt, effectuez les actions correspondant à l'arrêt d'un véhicule et à son acheminement jusqu'au prochain arrêt. | |
| Un livreur rencontre un engin d'alimentation pour transférer des colis supplémentaires sur le véhicule de livraison. | Le point de rencontre d'une correspondance entre bases d'alimentation et véhicules de livraison doit être modélisé comme un arrêt planifié.
Après avoir transféré et scanné les colis, créez des tâches de livraison s'ils n'ont pas encore été créés. Ensuite, mettez à jour l'ordre d'exécution des tâches en attribuant des tâches à un véhicule et en modifiant l'ordre des tâches. |
|
| Le conducteur reçoit une notification de demande de retrait. | Après avoir accepté la demande de retrait, créez une tâche de retrait en livraison. Ensuite, mettez à jour l'ordre d'exécution des tâches en attribuant des tâches à un véhicule et en modifiant l'ordre des tâches. | |
| Midi | Le conducteur fait une pause-déjeuner. | Si un emplacement est associé à la tâche d'indisponibilité, traitez-la comme n'importe quelle autre tâche. Effectuez des actions en lien avec un véhicule qui arrive à un arrêt, véhicule effectue un arrêt et véhicule en route vers le prochain arrêt.
Sinon, aucune autre action n'est nécessaire avant la fin de la coupure. Supprimez la tâche en confirmant les tâches suivantes et restantes, puis en mettant à jour l'ordre des tâches. |
| Le livreur récupère une commande. | Cette méthode est comparable à un arrêt de la livraison. effectuer des actions liées à l'arrivée d'un véhicule à un arrêt et à la fermeture d'une tâche, et éventuellement du stockage de l'état de la livraison et d'autres métadonnées ; Après avoir terminé toutes les tâches à l'arrêt et avant de commencer à prendre la voiture jusqu'au prochain arrêt, effectuez les actions correspondant à l'arrêt du véhicule et à l'acheminement du véhicule jusqu'au prochain arrêt. Remarque: Pour que la facturation soit correcte, tous les retraits doivent avoir une tâche de livraison correspondante. Si le retrait doit être livré à un autre endroit de la même route le jour même, nous vous recommandons de modéliser cette tâche de livraison comme toute autre tâche de livraison de l'itinéraire. Si le livreur récupère le ramassage dans le dépôt, nous vous recommandons de créer une tâche de livraison à la destination du dépôt. | |
| Le livreur effectue un arrêt planifié pour récupérer les envois depuis un dépôt. | Le processus de modélisation est identique à celui des autres arrêts de retrait. Effectuez des actions liées à l'arrivée d'un véhicule à un arrêt et à la fermeture d'une tâche. Une fois que vous avez terminé toutes les tâches à l'arrêt et commencé à conduire au prochain arrêt, effectuez les actions liées à l'arrêt d'un véhicule et à son acheminement vers le prochain arrêt. | |
| Le livreur reçoit une notification indiquant qu'un colis a été dévié. | Définissez l'état de la tâche de livraison d'origine sur COMPLETED et créez une tâche de livraison pour le nouvel emplacement de livraison. Pour en savoir plus, consultez Réacheminer une livraison. | |
| Le livreur a tenté de livrer un colis, mais n'a pas pu le faire. | Cette méthode est semblable à un arrêt de livraison réussi, marquant la tâche de livraison comme terminée. Effectuez des actions associées à un véhicule arrivant à un arrêt. Une fois le colis livré, fermez la tâche et, si vous le souhaitez, stockez l'état de l'expédition et autres métadonnées. Après avoir terminé toutes les tâches à l'arrêt et avant de commencer à prendre la voiture jusqu'au prochain arrêt, effectuez les actions correspondant à l'arrêt du véhicule et à l'acheminement du véhicule jusqu'au prochain arrêt. | |
| Un livreur a été informé de la mise en attente (et non de la livraison) d'une livraison. | Une fois la notification reçue et confirmée, définissez l'état de la tâche sur COMPLETED. | |
| Le livreur a été informé de la livraison d'un certain colis et a modifié la commande avec livraison validée. | Modifiez l'ordre des tâches. | |
| Le livreur choisit de livrer une commande dans le désordre. | Mettez à jour l'ordre des tâches, puis procédez comme d'habitude. | |
| Le livreur livre plusieurs colis dans un même établissement. | Le processus 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 la livraison, fermez chaque tâche et, si vous le souhaitez, indiquez l'état de la livraison et les autres méta-informations. Après avoir terminé toutes les tâches à l'arrêt et avant de commencer à prendre la voiture jusqu'au prochain arrêt, effectuez les actions correspondant à l'arrêt du véhicule et à l'acheminement du véhicule jusqu'au prochain arrêt. | |
| Fin de journée | Le conducteur retourne au dépôt. | Si le livreur revient au dépôt avec des envois récupérés au cours du trajet, vous devez également créer et fermer chaque colis en tant que tâche de livraison pour vous assurer que la facturation est correcte. Pour ce faire, modélisez le dépôt comme n'importe quel autre arrêt de livraison. Si le dépôt n'est pas utilisé comme arrêt de livraison, vous pouvez éventuellement le modéliser en tant qu'arrêt planifié. Vos chauffeurs pourront ainsi voir l'itinéraire jusqu'au dépôt et connaître leur heure d'arrivée prévue. |
Comprendre les mises à jour de la position
Les mises à jour de la position sont envoyées à Fleet Engine une fois qu'un véhicule de livraison est en route à partir d'un arrêt (y compris du dépôt) jusqu'à ce qu'il arrive à l'arrêt suivant. Comme ces événements ne sont pas détectés automatiquement, vous devez les marquer par programmation. Utilisez des bibliothèques qui détectent les changements de mode de transport pour déclencher l'envoi des notifications requises à Fleet Engine.
Les mises à jour de la position doivent être suspendues lorsque le conducteur ne conduit pas, car la qualité des signaux de localisation se dégrade considérablement lorsque quelqu'un se trouve dans un bâtiment.
La fréquence de mise à jour de la position peut être définie dans le SDK du pilote. Par défaut, il envoie des mises à jour toutes les 10 secondes.
Arrêts de véhicules et lieux de livraison
Un véhicule à l'arrêt effectue une tâche d'expédition ou une autre tâche. Il s'agit d'un point d'accès tel qu'un quai de chargement ou un emplacement fixé à une route.
Le lieu de livraison est le lieu où le colis est livré ou retiré. Pour vous rendre au lieu de livraison et la quitter, vous devrez peut-être vous déplacer à pied depuis l'arrêt du véhicule.
Par exemple, lorsqu'un livreur livre un colis dans un centre commercial, le véhicule de livraison s'arrête dans le parking du centre commercial le plus proche de l'entrée la plus proche. Il s'agit de l'arrêt du véhicule. Le conducteur se déplace à pied de l'arrêt du véhicule à l'emplacement du centre commercial où se trouve le magasin. Il s'agit du lieu de livraison.
Afin d'optimiser le suivi des expéditions pour vos utilisateurs, pensez à la manière dont les tâches d'expédition sont attribuées aux arrêts de véhicule. N'oubliez pas que le nombre d'arrêts restants pour les tâches d'expédition est signalé à l'utilisateur afin de l'aider à suivre la progression de son expédition.
Par exemple, si un livreur effectue de nombreuses livraisons dans un même immeuble de bureaux, envisagez d'attribuer toutes les tâches de livraison à un seul arrêt de véhicule. Si chaque tâche de livraison est attribuée à son propre arrêt, le suivi des envois sera moins utile pour vos utilisateurs, car le suivi n'est disponible qu'une fois que le véhicule se trouve dans un nombre limité d'arrêts avant son arrivée. Un grand nombre d'arrêts de véhicules effectués dans un court laps de temps ne permet pas à l'utilisateur de suivre la progression de sa livraison.
Utiliser les SDK pour mobile
Avant d'appeler le SDK Driver, veillez à l'initialiser.
Initialiser l'API Delivery Driver
Avant d'initialiser l'API Delivery Driver dans le SDK Driver, veillez à initialiser le SDK Navigation. Ensuite, initialisez l'API Delivery Driver comme indiqué dans l'exemple suivant:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
Cas d'utilisation
Cette section explique comment utiliser l'API Deliveries pour modéliser des cas d'utilisation courants.
Identifiants d'entités uniques
Le format et la valeur des identifiants d'entité uniques utilisés dans les appels REST sont opaques pour Fleet Engine. Évitez d'utiliser l'incrémentation automatique des identifiants et assurez-vous que l'identifiant ne contient aucune information personnelle, telle que le numéro de téléphone du conducteur.
Créer un véhicule
Vous pouvez créer un véhicule à partir du SDK Driver ou de l'environnement du serveur.
gRPC
Pour créer un véhicule, vous devez appeler CreateDeliveryVehicle à Fleet Engine.
Utilisez l'objet CreateDeliveryVehicleRequest pour définir les attributs du nouveau véhicule de livraison. Notez que toute valeur spécifiée pour le champ Name sera ignorée conformément aux instructions de l'API pour les ID spécifiés par l'utilisateur.
Vous devez utiliser le champ DeliveryVehicleId pour définir l'ID du véhicule.
Lorsque vous créez un DeliveryVehicle, vous pouvez éventuellement spécifier deux champs:
- Attributs
- Dernière position
Tous les autres champs ne doivent pas être définis. Sinon, Fleet Engine renverra une erreur, car ces champs sont en lecture seule ou ne peuvent être mis à jour que via des appels UpdateDeliveryVehicle.
Pour créer un véhicule sans définir de champs facultatifs, vous pouvez laisser le champ DeliveryVehicle non défini dans CreateDeliveryVehicleRequest.
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java pour créer un véhicule:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour créer un véhicule à partir de l'environnement de serveur, envoyez un appel HTTP REST à CreateDeliveryVehicle:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> est un identifiant unique pour un véhicule de livraison dans votre parc.
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps POST représente l'entité DeliveryVehicle à créer. Vous pouvez spécifier les champs facultatifs suivants:
- Attributs
- dernier lieu
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 par API pour les ID spécifiés par l'utilisateur.
Tous les autres champs ne doivent pas être définis. Sinon, Fleet Engine renverra une erreur, car ces champs sont en lecture seule ou ne peuvent être mis à jour que via des appels UpdateDeliveryVehicle.
Pour créer un véhicule sans définir de champs, vous pouvez laisser le corps de la requête POST vide.
Un ID de véhicule sera extrait du paramètre deliveryVehicleId de l'URL POST pour le véhicule nouvellement créé.
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 magasin
Vous pouvez créer une tâche de retrait en magasin à partir du SDK Driver ou de l'environnement du serveur.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour créer une tâche de retrait en livraison:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour créer une tâche de retrait en livraison à partir de l'environnement de serveur, envoyez un appel HTTP REST à "CreateTask":
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> est un identifiant unique de la tâche. Il ne doit pas s'agir du numéro de suivi de 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.ACCUEIL state État.OPEN trackingId Numéro ou identifiant que vous utilisez pour suivre un envoi. Emplacement planifié Le lieu où la tâche doit être effectuée, dans ce cas le lieu de retrait. Durée de la tâche Délai prévu, en secondes, pour récupérer la commande au lieu de prise en charge. Champs facultatifs :
- Aucun
Tous les autres champs de l'entité sont ignorés pour la création. Fleet Engine lève une exception si la requête inclut un identifiant de véhicule de livraison attribué. Vous attribuez des tâches à l'aide de UpdateVehicleRequests. Pour en savoir plus, consultez Attribuer des tâches à un véhicule.
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"
}
EOM
Créer une tâche de livraison
Vous pouvez créer une tâche de livraison d'expédition depuis le SDK Driver ou depuis l'environnement du serveur.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java 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))
.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 à partir de l'environnement de serveur, envoyez un appel HTTP REST à "CreateTask":
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> est un identifiant unique de la tâche. Il ne doit pas s'agir du numéro de suivi de 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 État.OPEN trackingId Numéro ou identifiant que vous utilisez pour suivre un envoi. Emplacement planifié Lieu où la tâche doit être effectuée (dans ce cas, le lieu de livraison pour ce colis). Durée de la tâche Durée prévue, en secondes, avant de déposer le colis à l'adresse de livraison. Champs facultatifs :
- Aucun
Tous les autres champs de l'entité sont ignorés pour la création. Fleet Engine lève une exception si la requête inclut un identifiant de véhicule de livraison attribué.
Vous attribuez des tâches à l'aide de UpdateVehicleRequests. Pour en savoir plus, consultez Attribuer des tâches à un véhicule.
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"
}
EOM
Créer des tâches par lot
Vous pouvez créer un lot de tâches à partir de l'environnement de serveur.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java pour créer deux tâches, l'une pour la livraison et l'autre pour le retrait au même emplacement:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Delivery Task settings
Task deliveryTask = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("delivery-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header or parent fields
.setTaskId("task-8312508") // Task ID assigned by the Provider
.setTask(deliveryTask) // Initial state
.build();
// Pickup Task settings
Task pickupTask = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("pickup-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header or parent fields
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(pickupTask) // Initial state
.build();
// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;
// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
BatchCreateTasksRequest.newBuilder()
.setParent(parent)
.addRequests(createDeliveryTaskRequest)
.addRequests(createPickupTaskRequest)
.build();
// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.
try {
BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour créer une tâche de livraison et de retrait à partir de l'environnement de serveur, effectuez un appel HTTP REST à BatchCreateTasks:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit contenir une entité BatchCreateTasksRequest:
Champs obligatoires :
Champ Valeur requêtes Tableau< CreateTasksRequest>Champs facultatifs :
Champ Valeur en-tête `DeliveryRequestHeader`
Chaque élément CreateTasksRequest dans requests doit transmettre les mêmes règles de validation qu'une requête CreateTask, à l'exception que les champs parent et header sont facultatifs. S'ils sont définis, ils doivent être identiques à leurs champs respectifs au niveau supérieur BatchCreateTasksRequest. Pour en savoir plus sur les règles de validation spécifiques à chacune d'elles, consultez les sections Créer une tâche de livraison et Créer une tâche de livraison.
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 l'indisponibilité (par exemple, pour les changements de pilote ou le réapprovisionnement de véhicules) à partir du SDK Driver ou de l'environnement du serveur. Une tâche d'indisponibilité planifiée ne doit pas inclure d'ID de suivi. Vous pouvez éventuellement indiquer un lieu.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java 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 de l'environnement de serveur, envoyez un appel HTTP REST à CreateTask:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> est un identifiant unique de la tâche. Si vous n'avez pas d'ID de tâche dans votre système, vous pouvez générer un identifiant unique universel (UUID).
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit contenir une entité Task:
Champs obligatoires :
Champ Valeur type Type.INDISPONIBLE state État.OPEN Durée de la tâche Durée de la coupure en secondes. Champs facultatifs :
Champ Valeur Emplacement planifié Lieu de la coupure si elle doit être prise à un endroit spécifique.
Tous les autres champs de l'entité sont ignorés pour la création. Fleet Engine lève une exception si la requête inclut un identifiant de véhicule de livraison attribué. Vous attribuez des tâches à l'aide de UpdateVehicleRequests. Pour en savoir plus, consultez Attribuer des tâches à un véhicule.
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 programmée depuis le SDK Driver ou depuis l'environnement du serveur. Une tâche d'arrêt planifiée peut ne pas inclure d'ID de suivi.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour créer une tâche d'arrêt programmé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 de l'environnement de serveur, envoyez un appel HTTP REST à "CreateTask":
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> est un identifiant unique de la tâche. Si vous n'avez pas d'ID de tâche dans votre système, vous pouvez générer un identifiant unique universel (UUID).
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit contenir une entité Task:
Champs obligatoires :
Champ Valeur type Type.SCHEDULED_STOP state État.OPEN Emplacement planifié Emplacement de l'arrêt. Durée de la tâche Durée prévue de l'arrêt en secondes. Champs facultatifs :
- Aucun
Tous les autres champs de l'entité sont ignorés pour la création. Fleet Engine lève une exception si la requête inclut un identifiant de véhicule de livraison attribué. Vous attribuez des tâches à l'aide de UpdateVehicleRequests. Pour en savoir plus, consultez Attribuer des tâches à un véhicule.
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
Attribuer des tâches à un véhicule
Les tâches sont attribuées à un véhicule de livraison en mettant à jour l'ordre des tâches du véhicule. L'ordre des tâches d'un véhicule est déterminé par la liste des arrêts du véhicule de livraison. Une ou plusieurs tâches peuvent être attribuées à chaque arrêt de véhicule.
La mise à jour de l'ordre des tâches précédemment attribuées à un autre véhicule génère une erreur.
Pour modifier une livraison d'un véhicule à un autre, fermez la tâche d'origine, puis recréez-la avant de lui attribuer le nouveau véhicule.
Modifier l'ordre des tâches
Vous pouvez modifier l'ordre d'exécution des tâches attribuées à un véhicule à partir du SDK Driver ou de l'environnement du serveur. Les deux méthodes ne doivent pas être mélangées pour éviter les conditions de concurrence.
Si vous mettez à jour l'ordre des tâches, celles-ci sont également attribuées à un véhicule s'il n'en était pas assigné auparavant, et les tâches fermées qui avaient été précédemment attribuées à un véhicule et mises à jour. L'attribution d'une tâche à un autre véhicule si elle a déjà été attribuée à un autre véhicule génère une erreur. Fermez la tâche existante, puis créez une tâche avant de l'attribuer au nouveau véhicule.
Vous pouvez modifier l'ordre des tâches à tout moment.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java Java pour mettre à jour l'ordre des tâches du véhicule:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.NEW)))
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
// 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 {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour mettre à jour l'ordre des tâches d'un véhicule à partir de l'environnement de serveur, envoyez un appel HTTP REST à `UpdateDeliveryVehicle':
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments
<id> est un identifiant unique pour un véhicule de livraison de votre parc dont vous prévoyez de modifier 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 Segmentsdejoursdus restants 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. resteVehicleJourneySegments[i].stop L'arrêt de la tâche i dans la liste. resteVehicleJourneySegments[i].stop.plannedLocation Emplacement prévu de l'arrêt. resteVehicleJourneySegments[i].stop.tasks Liste des tâches à effectuer à cet arrêt. resteVehicleJourneySegments[i].stop.state État.NOUVEAU 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 vers le prochain arrêt
Fleet Engine doit être notifié lorsqu'un véhicule quitte un arrêt ou démarre la navigation. Vous pouvez envoyer une notification à Fleet Engine à partir du SDK Driver ou de l'environnement du serveur. Les deux méthodes ne doivent pas être mélangées pour éviter les conditions de concurrence et pour maintenir une source unique de vérité.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java Java pour informer Fleet Engine qu'un véhicule est en route vers son prochain arrêt.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
// 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 {
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 l'environnement de serveur, effectuez un appel HTTP REST à "UpdateDeliveryVehicle":
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments
<id> est un identifiant unique du véhicule de livraison de votre parc dont vous souhaitez modifier 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 Segmentsdejoursdus restants Liste des arrêts restants du véhicule, dont l'état est "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
Le véhicule arrive à un arrêt
Fleet Engine doit être notifié lorsqu'un véhicule arrive à un arrêt. Vous pouvez envoyer une notification à Fleet Engine à partir du SDK Driver ou de l'environnement du serveur. Les deux méthodes ne doivent pas être mélangées pour éviter les conditions de concurrence et pour maintenir une source unique de vérité.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java Java 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();
// 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 {
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 l'environnement serveur, effectuez un appel HTTP REST à `UpdateDeliveryVehicle':
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments
<id> est un identifiant unique du véhicule de livraison de votre parc dont vous souhaitez modifier 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 Segmentsdejoursdus restants L'arrêt en question est associé à l'état "State.ARRIVED", puis à une liste d'arrêts de véhicules restants, dont l'état est "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 s'arrête
Fleet Engine doit être notifié lorsqu'un véhicule effectue un arrêt. Toutes les tâches associées à l'arrêt sont alors définies sur FERMÉE. Vous pouvez signaler Fleet Engine à partir du SDK Driver ou de l'environnement du serveur. Les deux méthodes ne doivent pas être mélangées pour éviter les conditions de concurrence et maintenir une source d'informations unique.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour informer Fleet Engine qu'un véhicule a terminé un arrêt.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
// 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 {
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 la fin d'un arrêt à partir de l'environnement de serveur, effectuez un appel HTTP REST à `UpdateDeliveryVehicle':
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments
<id> est un identifiant unique du véhicule de livraison de votre parc dont vous souhaitez modifier 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 segments_jours_véhicules_restants L'arrêt que vous avez terminé ne doit plus figurer dans la liste des arrêts restants du véhicule. Champs facultatifs :
- Aucun
Tous les autres champs de l'entité sont ignorés pour la mise à jour.
Exemple de commande curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Mettre à jour une tâche
La plupart des champs de tâches sont immuables. Toutefois, il est possible de modifier l'état, le résultat de la tâche, son heure et son emplacement en mettant directement à jour l'entité de tâche. Par exemple, lorsqu'une tâche n'a pas été attribuée à un véhicule, il est possible de la fermer en mettant directement à jour l'état.
gRPC
Voici un exemple de mise à jour d'une tâche via gRPC.
REST
Voici un exemple de mise à jour d'une tâche via REST.
Fermer une tâche
Pour fermer une tâche qui a été attribuée à un véhicule, signalez à Fleet Engine que le véhicule a terminé l'arrêt où la tâche a lieu ou supprimez-le de la liste des arrêts du véhicule. Pour ce faire, vous pouvez définir la liste des arrêts de véhicules restants comme vous le feriez pour mettre à jour l'ordre des tâches d'un véhicule.
Si une tâche n'a pas encore été attribuée à un véhicule et doit être fermée, mettez-la à l'état FERMÉE. Toutefois, vous ne pouvez pas rouvrir une tâche FERMÉE.
La fermeture d'une tâche n'indique ni la réussite, ni l'échec. Elle indique que la tâche n'est plus considérée comme en cours. Pour le suivi de la livraison, il est important d'indiquer le résultat réel d'une tâche afin de pouvoir afficher le résultat de la livraison.
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setState(Task.State.CLOSED) // It's only possible to directly CLOSE a
.build(); // task which 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();
// 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 updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour marquer une tâche comme fermée à partir de l'environnement de serveur, envoyez un appel HTTP REST à UpdateTask:
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state
<id> est un identifiant unique de 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 state État.FERMÉ Champs facultatifs :
Champ Valeur résultat Result.SUCCEEDED ou Output.FAILED Heure de résultat de la tâche Heure à laquelle la tâche a été effectuée. Emplacement du résultat de la tâche Emplacement où la tâche a été effectuée. Fleet Engine utilise par défaut la dernière position du véhicule, sauf si le fournisseur le remplace manuellement.
Tous les autres champs de l'entité sont ignorés pour la mise à jour.
Exemple de commande curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"state": "CLOSED",
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)"
}
EOM
Définir le résultat de la tâche et son emplacement
La fermeture d'une tâche n'indique pas que l'opération a réussi ou échoué. Elle indique que la tâche n'est plus considérée comme en cours d'exécution. Pour le suivi de la livraison, il est important d'indiquer le résultat réel d'une tâche pour qu'un résultat de livraison puisse être affiché et que les services soient correctement facturés. Une fois définie, le résultat de la tâche ne peut plus être modifié. Il est possible de modifier l'heure et le lieu de résultat des tâches après leur définition.
Le résultat des tâches à l'état FERMÉ peut être défini sur RÉUSSITE ou ÉCHEC. Fleet Engine ne facture que les tâches de livraison ayant l'état SUCCEEDED.
Lorsque vous marquez le résultat d'une tâche, Fleet Engine renseigne automatiquement l'emplacement du résultat de la tâche avec la dernière position connue du véhicule. Vous pouvez ignorer ce comportement.
gRPC
Lorsque vous définissez le résultat, vous avez la possibilité de définir l'emplacement du résultat de la tâche. Cela empêchera Fleet Engine de la définir sur la valeur par défaut du dernier emplacement du véhicule. Vous pouvez également écraser l'emplacement du résultat de la tâche défini par Fleet Engine ultérieurement. Fleet Engine n'écrasera jamais un emplacement de résultat de tâche que vous fournissez. Il n'est pas possible de définir un emplacement de résultat pour une tâche pour laquelle aucun résultat de tâche n'est défini. Il est possible de définir à la fois le résultat de la tâche et son emplacement dans une même requête.
L'exemple suivant montre comment utiliser la bibliothèque Java Java pour définir le résultat d'une tâche sur SUCCEEDED et l'emplacement où la tâche a été effectuée:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTime(now())
.setTaskOutcomeLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
.build();
// 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 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 de l'environnement de serveur, effectuez un appel HTTP REST à UpdateTask:
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation
<id> est un identifiant unique de 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 résultat Result.SUCCEEDED ou Output.FAILED Heure de résultat de la tâche Horodatage du moment où le résultat de la tâche a été défini (à partir du fournisseur). Il s'agit du moment où la tâche a été effectuée. Champs facultatifs :
Champ Valeur Emplacement du résultat de la tâche Emplacement où la tâche a été effectuée. Fleet Engine utilise par défaut la dernière position du véhicule, sauf si le fournisseur le remplace manuellement.
Tous les autres champs de l'entité sont ignorés pour la mise à jour.
Exemple de commande curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
Réacheminer une commande
Une fois qu'une tâche d'expédition a été créée, son emplacement prévu ne peut plus être modifié. Pour réacheminer une livraison, fermez la tâche sans définir de résultat, puis créez une tâche avec le nouveau lieu prévu. Après avoir créé la tâche, attribuez-la au même véhicule. Pour en savoir plus, consultez Fermer la tâche d'expédition et Attribuer la tâche.
Utiliser des distributeurs et des véhicules de livraison
Si vous utilisez des distributeurs pour acheminer des envois vers des véhicules de livraison tout au long de la journée, modélisez le transfert des envois en tant que tâche d'arrêt planifiée pour le véhicule de livraison. Pour garantir un suivi précis de la position, n'attribuez une tâche de livraison que pour le colis transféré une fois celui-ci chargé dans le véhicule de livraison. Pour en savoir plus, consultez la section Arrêt planifié.
État de livraison du magasin et autres méta-informations
Lorsqu'une tâche d'expédition est terminée, son état et son résultat sont enregistrés. Toutefois, vous pouvez mettre à jour d'autres métadonnées spécifiques à l'envoi. Pour stocker d'autres méta-informations que vous pouvez référencer en dehors du service Fleet Engine, utilisez l'ID de suivi associé à la tâche en tant que clé dans une table externe.
Pour en savoir plus, consultez la section Déroulement d'une tâche.
Rechercher un véhicule
Vous pouvez rechercher un véhicule à partir du SDK Driver ou à partir de l'environnement du serveur.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour rechercher un véhicule:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour rechercher un véhicule à partir de l'environnement de serveur, envoyez un appel HTTP REST à "GetVehicle":
GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>
<id> est un identifiant unique de la tâche.
<vehicleId> est l'identifiant du véhicule à rechercher.
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Le corps de la requête doit être vide.
Si la recherche aboutit, le corps de la réponse contient une entité de véhicule.
Exemple de commande curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"
Rechercher une tâche
Vous pouvez rechercher une tâche à partir de l'environnement du serveur. Le SDK Driver ne permet pas de rechercher une tâche.
gRPC
L'exemple suivant montre comment utiliser la 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 de l'environnement de serveur, envoyez un appel HTTP REST à "GetTask":
GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>
<id> est un identifiant unique de 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 les tâches d'expédition par ID de suivi
Vous pouvez rechercher des informations sur les tâches d'expédition de différentes manières, chacune ayant un objectif distinct:
- par un ID de tâche: utilisé par des utilisateurs comme des opérateurs de parcs qui ont accès à l'intégralité des données de tâches.
- à l'aide d'un ID de suivi: votre logiciel client l'utilise pour fournir des informations limitées à un utilisateur final (par exemple, quand un colis arrive chez lui).
Cette section traite de la recherche d'informations sur les tâches à l'aide d'un ID de suivi. Si vous souhaitez rechercher une tâche à l'aide de son ID, consultez Rechercher une tâche.
Pour rechercher des informations par ID de suivi, vous pouvez utiliser l'une des méthodes suivantes:
Conditions de recherche
Les informations de livraison fournies par un ID de suivi respectent les règles de visibilité définies dans la section Contrôler la visibilité des lieux suivis.
Utilisez Fleet Engine pour rechercher des informations sur la livraison par ID de suivi. Le SDK Driver n'est pas compatible avec les recherches d'informations par ID de suivi. Pour effectuer cette opération avec Fleet Engine, vous devez utiliser un environnement de serveur ou de navigateur.
Utilisez le jeton le plus étroit possible pour limiter les risques de sécurité. Par exemple, si vous utilisez un jeton de consommateur de livraison, les appels d'API Fleet Engine Deliveries ne renvoient que les informations pertinentes pour cet utilisateur final, comme le transporteur ou le destinataire d'une livraison. Toutes les autres informations des réponses sont masquées. Pour en savoir plus sur les jetons, consultez la page Créer un jeton Web JSON (JWT) pour l'autorisation.
Requêtes avec Java à l'aide de gRPC
L'exemple suivant montre comment utiliser la bibliothèque gRPC Java pour rechercher des informations sur une tâche de livraison en fonction de son ID de suivi.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder() // No need for the header
.setParent(parent)
.setTrackingId(TRACKING_ID)
.build();
try {
TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Recherches via HTTP
Pour rechercher une tâche d'expédition dans un navigateur, envoyez un appel HTTP REST à GetTaskTrackingInfo:
GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>
<tracking_id> est l'ID de suivi associé à la tâche.
L'en-tête de requête doit contenir un champ Authorization ayant la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Si la recherche aboutit, le corps de la réponse contient une entité taskTrackingInfo.
Exemple de commande curl:
# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"
Répertorier les tâches
Vous pouvez répertorier les tâches à partir d'un serveur ou d'un navigateur. Le SDK du pilote ne permet pas de répertorier les tâches.
Répertorier les tâches nécessite un accès étendu aux tâches. La création de listes de tâches n'est destinée qu'aux utilisateurs de confiance. Utilisez le lecteur de parc de livraison ou les jetons d'authentification de super-utilisateur Delivery lorsque vous envoyez des requêtes de tâches de liste.
Les tâches suivantes sont masquées:
- VehicleStop.planned_location
- VéhiculeStop.state
- VehicleStop.TaskInfo.taskId
Les tâches répertoriées peuvent être filtrées par la plupart des propriétés des tâches. Pour connaître la syntaxe des requêtes de filtre, consultez la page AIP-160. La liste suivante présente les propriétés de tâche valides que vous pouvez utiliser pour le filtrage:
- livraison_véhicule_id
- state
- emplacement planifié
- durée_tâche
- résultat_tâche
- lieu_sortie_tâche
- source_destination_source_source
- temps_de_sortie_tâche
- tracking_id [id_suivi]
- type
Utilisez les formats de champ suivants, basés sur des propositions d'amélioration de l'API Google:
| Type de champ | Format | Exemple |
|---|---|---|
| Code temporel | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
| Durée | Nombre de secondes suivi d'un "s" | task_duration = 120s |
| Enum | Chaîne | state = CLOSED AND type = PICKUP |
| Emplacement | point.latitude et point.longitude |
planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0 |
Consultez la page AIP-160 pour obtenir la liste complète des opérateurs de requête de filtrage.
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. Vous pouvez spécifier une taille de page dans les requêtes de liste de tâches. Si une taille de page est spécifiée, le nombre de tâches renvoyées n'est pas supérieur à la taille de page spécifiée. Si aucune taille de page n'est présente, une valeur par défaut raisonnable est utilisée. Si la taille de page demandée dépasse une valeur maximale interne, la valeur maximale interne est utilisée.
Une liste de tâches peut inclure un jeton permettant de lire la page de résultats suivante. Utilisez le jeton de page avec une requête identique à la requête précédente pour récupérer la page suivante. Lorsque le jeton de page renvoyé est vide, aucune autre tâche ne peut être récupérée.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java gRPC pour répertorier les tâches d'un identifiant deliveryVehicleId. Une réponse positive peut toujours être vide. Une réponse vide indique qu'aucune tâche n'est associée à l'identifiant 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")
.build();
try {
ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour répertorier les tâches d'un navigateur, envoyez un appel HTTP REST à ListTasks:
GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks
Pour appliquer un filtre aux tâches répertoriées, incluez un paramètre d'URL "filter" ayant une valeur de filtre avec échappement.
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Si la recherche aboutit, le corps de la réponse contient des données présentant la structure suivante:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
Une réponse positive peut toujours être vide. Une réponse vide indique qu'aucune tâche ne répond aux critères de filtrage spécifiés.
Exemple de commande curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"
Répertorier les véhicules de livraison
Vous pouvez répertorier les véhicules de livraison à partir d'un serveur ou d'un navigateur. Le SDK Driver ne permet pas de répertorier les véhicules de livraison.
Cette fonctionnalité demande un accès étendu aux véhicules de livraison et n'est destinée qu'aux utilisateurs de confiance. Utilisez le lecteur de parc de livraison ou les jetons d'authentification de super-utilisateur de livraison lorsque vous envoyez des requêtes de liste de véhicules de livraison.
Les champs suivants des véhicules de livraison listés sont masqués en raison de leur impact sur la taille de la réponse:
- Segment du routage actuel
- Segments de véhicules restants
Vous pouvez filtrer les véhicules de livraison par liste en fonction de leur propriété attributes. Par exemple, pour interroger un attribut ayant la clé my_key et la valeur my_value, utilisez attributes.my_key = my_value. Pour interroger plusieurs attributs, joignez les requêtes à l'aide des opérateurs logiques AND et OR, comme dans attributes.key1 = value1 AND
attributes.key2 = value2. Consultez la page AIP-160 pour obtenir une description complète de la syntaxe des requêtes de filtre.
Vous pouvez filtrer les véhicules de livraison listés par emplacement à l'aide du paramètre de requête viewport. Le paramètre de requête viewport définit les fenêtres d'affichage à l'aide de deux coordonnées de délimitation: high (nord-est) et low (sud-ouest) de latitude/longitude.
Les requêtes sont refusées si leur latitude est inférieure à leur latitude.
Par défaut, les listes de véhicules de livraison sont paginées selon une taille de page raisonnable. Si vous spécifiez une taille de page, la requête ne renvoie que le nombre de véhicules spécifié par la limite, ou moins. Si la taille de page demandée dépasse une valeur maximale interne, la valeur maximale interne est utilisée. Les tailles de page par défaut et maximale sont de 100 véhicules.
Une liste de véhicules de livraison peut inclure un jeton permettant de lire la page de résultats suivante. Un jeton de page n'est présent dans une réponse que lorsque davantage de pages de véhicules de livraison sont disponibles pour la récupération. Pour récupérer la page suivante de tâches, utilisez le jeton de page avec une requête identique à la requête précédente.
gRPC
L'exemple suivant montre comment utiliser la bibliothèque Java Java pour répertorier les véhicules de livraison dans une région particulière avec un certain attribut. Une réponse réussie peut quand même être vide. Dans ce cas, cela signifie qu'aucun véhicule avec l'attribut spécifié n'est actuellement dans la fenêtre d'affichage spécifiée.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
ListDeliveryVehiclesRequest.newBuilder() // No need for the header
.setParent(parent)
.setViewport(
Viewport.newBuilder()
.setHigh(LatLng.newBuilder()
.setLatitude(37.45)
.setLongitude(-122.06)
.build())
.setLow(LatLng.newBuilder()
.setLatitude(37.41)
.setLongitude(-122.11)
.build())
.setFilter("attributes.my_key = my_value")
.build();
try {
ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Pour répertorier les tâches d'un navigateur, envoyez un appel HTTP REST à ListDeliveryVehicles:
GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles
Pour appliquer un filtre aux tâches répertoriées, incluez un paramètre d'URL "filter" ayant une valeur de filtre avec échappement.
L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est un jeton émis par une fabrique de jetons Fleet Engine.
Si la recherche aboutit, le corps de la réponse contient des données présentant la structure suivante:
// JSON representation
{
"deliveryVehicles": [
{
object (DeliveryVehicle)
}
],
"nextPageToken": string,
"totalSize": integer
}
Une réponse positive peut toujours être vide. Dans ce cas, cela signifie qu'aucun véhicule de livraison ne correspond à la requête de filtre et à la fenêtre d'affichage spécifiées.
Exemple de commande curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"
Suivi de la livraison
Vous pouvez activer le suivi des livraisons à l'aide de l'API Fleet Engine Deliveries de deux manières:
À privilégier:utilisez la bibliothèque de suivi des envois JavaScript. La bibliothèque vous permet de visualiser la position des véhicules et les lieux d'intérêt suivis dans Fleet Engine. Il contient un composant de carte JavaScript qui remplace directement un objet google.maps.Map standard et des composants de données à connecter à Fleet Engine. Cela vous permet de proposer une expérience de suivi des expéditions personnalisable et animée à partir de votre application Web ou mobile.
Implémentez votre propre suivi des livraisons en plus de l'API Fleet Engine Deliveries. L'essentiel est de rechercher les tâches d'expédition par ID de suivi.
Si vous utilisez un rôle de consommateur de livraison, les appels d'API Fleet Engine Deliveries ne renvoient que les informations pertinentes pour un expéditeur ou un destinataire. Toutes les autres informations des réponses seront masquées. Vous êtes responsable de l'authentification des utilisateurs finaux. De plus, les informations de localisation seront filtrées en fonction de la tâche en cours d'exécution. Pendant une tâche d'indisponibilité, aucune information de localisation ne sera partagée avec un utilisateur final.
Journalisation
Vous pouvez activer une option permettant à Fleet Engine d'envoyer des journaux RPC à Cloud Logging. Pour en savoir plus, consultez la page Journalisation.
Rôles et jetons d'autorisation
Comme décrit dans la section Intégrer l'API Deliveries et les notes d'autorisation pour des cas d'utilisation individuels, l'appel à Fleet Engine nécessite une authentification avec des jetons Web JSON signés à l'aide des identifiants du compte de service. Les comptes de service utilisés pour générer ces jetons peuvent avoir un ou plusieurs rôles, chacun accordant un ensemble différent d'autorisations.
Pour en savoir plus, consultez la page Authentification et autorisation.
Dépannage
Résilience
Fleet Engine n'est pas considéré comme une source fiable. Vous êtes responsable de la restauration de l'état de votre système, si nécessaire, sans utiliser Fleet Engine.
État perdu dans Fleet Engine
Lorsque vous travaillez avec Fleet Engine, mettez en œuvre des clients afin que le système se répare en cas de défaillance. Par exemple, lorsque Fleet Engine tente de mettre à jour un véhicule, il peut répondre par une erreur indiquant que le véhicule n'existe pas. Le client doit ensuite recréer le véhicule dans son nouvel état. Dans de rares cas, le système doit être résilient en cas d'incident.
Dans le scénario extrêmement improbable d'une défaillance catastrophique de Fleet Engine, vous devrez peut-être recréer la plupart ou l'ensemble des véhicules et des tâches. Si le taux de création devient trop élevé, certaines requêtes peuvent à nouveau échouer en raison de problèmes de quota, car des contrôles de quota sont en place pour éviter les attaques par déni de service (DOS). Dans ce cas, ralentissez le taux de recréation en utilisant un intervalle entre les tentatives.
État perdu dans l'application de pilote
Si l'application de pilote plante, elle doit recréer l'état actuel dans le SDK du pilote. L'application doit tenter de recréer les tâches pour s'assurer qu'elles existent et restaurer leur état actuel. L'application doit également recréer et définir explicitement la liste des arrêts pour le SDK Driver.
Notez que ces restaurations doivent être effectuées de manière autonome sans s'appuyer sur les informations de Fleet Engine, autres que les erreurs indiquant si et quand une entité existe déjà dans la base de données. Si une entité existe déjà, cette erreur peut être absorbée et mise à jour à l'aide de son ID.
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, vous devez d'abord mettre à jour l'ordre des tâches, puis continuer normalement, en marquant l'arrivée à l'arrêt, l'exécution des tâches, etc. Sinon, le système peut devenir incohérent. Les ATA peuvent devenir incorrectes et des erreurs inattendues peuvent être signalées.