Rechercher des tâches

Ce document décrit les différentes manières de trouver des informations sur les tâches à partir d'un serveur ou d'un navigateur. Fleet Engine permet de trouver des tâches de deux manières :

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

    • ID de la tâche : utilisé par les utilisateurs tels que les gestionnaires de flotte qui ont accès à la vue complète 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 lorsqu'un colis est attendu à son domicile.

    Veillez à bien comprendre la différence entre l'ID de la tâche et l'ID de suivi de la tâche. Sachez qu'il s'agit de deux choses différentes. Consultez Champs de tâches de base dans le guide des tâches planifiées.

  • Lister les tâches : accès étendu aux tâches, destiné uniquement 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. Elle doit répondre aux exigences suivantes :

  • Les recherches par ID de suivi doivent respecter les règles de visibilité énoncées dans Règles de visibilité pour les objets suivis.

  • Utilisez le jeton le plus précis possible pour limiter les risques de sécurité. Par exemple, si vous utilisez un jeton Delivery Consumer, tous les appels ne renvoient que les informations pertinentes pour cet utilisateur final, comme l'expéditeur ou le destinataire d'un envoi. Fleet Engine masque toutes les autres informations dans les réponses. Pour en savoir plus sur les jetons, consultez Jetons Web JSON.

Rechercher une tâche par son ID

Vous pouvez rechercher une tâche par son ID de tâche à partir d'un environnement de serveur à l'aide de gRPC ou de REST. Les exemples suivants montrent comment utiliser la bibliothèque gRPC Java ou une requête REST pour 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>

  • <id> est un identifiant unique pour la tâche.
  • <taskId> correspond à l'ID de la tâche à rechercher.
  • L'en-tête de la 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 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 l'envoi à l'aide d'un appel gRPC ou HTTP REST à 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>

  • <tracking_id> correspond à l'ID de suivi associé à la tâche.

  • L'en-tête de la requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> porte le rôle de compte de service approprié. Consultez la section Rôles des comptes de service.

  • 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

L'affichage des tâches nécessite un accès étendu aux tâches. La liste des tâches n'est destinée qu'aux utilisateurs de confiance. Utilisez des jetons d'authentification Lecteur ou Administrateur Fleet Engine Delivery lorsque vous effectuez des requêtes de liste de tâches. Pour en savoir plus, consultez Rôles des comptes de service.

Paginer les listes

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

Une liste de tâches peut inclure un jeton permettant de lire la page de résultats suivante. Pour récupérer la page suivante, renvoyez la même requête avec le jeton de page. Lorsque le jeton de page renvoyé est vide, cela signifie qu'il n'y a plus de tâches à récupérer.

Champs lors de la liste des tâches

Fleet Engine masque les champs suivants lors de la liste des tâches :

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

Utilisez les formats de champ suivants en fonction des propositions d'amélioration de l'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 suivi d'un s task_duration = 120s
Énumération 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

Filtrer les tâches listées

Vous pouvez filtrer les tâches listées en fonction de la plupart de leurs propriétés. Pour en savoir plus sur la syntaxe des requêtes de filtre, consultez AIP-160. Si aucune requête de filtre n'est spécifiée, toutes les tâches sont listées.

Le tableau suivant indique les propriétés de tâches valides que vous pouvez utiliser pour filtrer les tâches :

Propriétés des tâches 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

Pour obtenir la liste complète des opérateurs de requête de filtre, consultez AIP-160.

Lister des exemples de tâches

L'exemple suivant montre comment lister les tâches pour un deliveryVehicleId et un attribut de tâche, à la fois avec la bibliothèque gRPC Java et avec un appel HTTP REST à ListTasks.

Une réponse réussie peut toujours être vide. Une réponse vide indique qu'aucune tâche n'est associée à l'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 listées, incluez un paramètre d'URL "filter" avec une requête de filtre échappée au format URL comme valeur.

L'en-tête de la requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> porte le rôle de compte de service approprié. Consultez la section Rôles des 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