Rechercher des tâches

Ce document décrit les façons dont vous pouvez trouver des informations sur les tâches à partir d'un un serveur ou un navigateur. Fleet Engine propose deux méthodes pour rechercher des tâches:

  • Rechercher des tâches: vous pouvez rechercher des tâches à l'aide des ID suivants:

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

    Assurez-vous de bien comprendre la différence entre l'ID de la tâche et la tâche ID de suivi. Sachez qu'il s'agit de deux choses différentes. Consultez la section Champs de tâches de base dans la Guide des tâches planifiées

  • Liste de tâches: accès étendu aux tâches, réservé aux utilisateurs de confiance.

Rechercher des tâches

Cette section explique comment rechercher des tâches par ID de tâche ou ID de suivi. Il contient les exigences suivantes:

  • Les recherches par ID de suivi doivent respecter les règles de visibilité comme indiqué dans l'article Règles de visibilité pour les objets suivis.

  • Utilisez le jeton le plus étroit possible pour limiter les risques de sécurité. Par exemple, si vous utiliser un jeton de consommateur de livraison, tout appel renvoyé que les informations pertinentes pour cet utilisateur final, comme le transporteur ou le destinataire d'un envoi. Fleet Engine masque toutes les autres informations réponses. Pour en savoir plus sur les jetons, consultez la page Jetons Web JSON.

Tâche de recherche par ID de tâche

Vous pouvez rechercher une tâche par son ID dans un environnement de serveur à l'aide de gRPC ou REST. Les exemples suivants montrent comment utiliser la bibliothèque Java gRPC ou une requête REST à GetTask.

gRPC

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

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

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

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

      case PERMISSION_DENIED:
        break;
   }
   return;
 }

REST

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

  • &lt;id&gt; est un identifiant unique pour la tâche.
  • &lt;taskId&gt; 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 émis par votre serveur conformément aux consignes décrites dans la section Rôles de compte de service et Jetons Web JSON :
  • 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 tâches par ID de suivi

Les exemples suivants montrent comment rechercher des tâches par ID de suivi de livraison à l'aide de gRPC ou d'un appel REST HTTP à GetTaskTrackingInfo.

gRPC

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

REST

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

  • &lt;tracking_id&gt; 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> porte le bon service rôle de compte de service Google Cloud. Consultez la section Rôles associés aux comptes de service.

  • Si la recherche aboutit, le corps de la réponse contient une 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

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 les jetons d'authentification de lecteur de parc de distribution ou d'administrateur de distribution lors des requêtes de liste de tâches. Pour en savoir plus, consultez Rôles associés aux comptes de service. des informations.

Paginer des listes

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. À récupérer la page suivante, renvoyer la même demande avec le jeton de page. Lorsque le jeton de page renvoyé est vide, aucune autre tâche n'est disponible pour la récupération.

Champs lors de la création d'une liste de tâches

Fleet Engine masque les champs suivants lors de la création d'une liste des tâches:

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

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

Filtrer les tâches listées

Vous pouvez filtrer les tâches répertoriées selon la plupart de leurs propriétés. Pour la syntaxe des requêtes de filtre, voir AIP-160. Si aucune requête de filtre n'est spécifiée, toutes les tâches sont répertoriées.

Le tableau suivant présente les propriétés de tâche valides que vous pouvez utiliser pour le filtrage:

Propriétés de la tâche pour filtrer les listes
  • type
  • attributes
  • tracking_id
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_duration_outcome
  • task_outcome
  • task_outcome_location
  • task_outcome_time

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

Répertorier des exemples de tâches

L'exemple suivant montre comment répertorier des tâches pour un deliveryVehicleId et un de tâche, à la fois avec la bibliothèque gRPC Java et avec un appel HTTP REST pour ListTasks

Une réponse positive peut toujours être vide. Une réponse vide indique que non tâches associées au deliveryVehicleId fourni.

gRPC

 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

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

Pour appliquer un filtre aux tâches de la liste, ajoutez un "filtre" Paramètre d'URL avec une requête de filtre avec échappement comme valeur.

L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <jeton>, où <jeton> porte le bon service rôle de compte de service Google Cloud. Consultez la section Rôles associés aux comptes de service.

Une recherche réussie fournit un corps de réponse présentant la structure suivante:

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

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}"

Étape suivante