Cómo buscar tareas

En este documento, se describen las formas en que puedes encontrar información de tareas desde un servidor o navegador. Fleet Engine admite dos formas de encontrar tareas:

• Busca tareas: Puedes buscar tareas por los siguientes IDs:

  • ID de tarea: Lo usan los usuarios, como los operadores de flota, que tienen acceso a la vista completa de los datos de la tarea.
  • ID de seguimiento: El software cliente lo usa para proporcionar información limitada a un usuario final, como cuando se espera un paquete en su casa.

  Asegúrate de comprender la diferencia entre el ID de tarea y el ID de seguimiento de tarea. pero no son lo mismo. Consulta Campos básicos de tareas en la guía de tareas programadas.

• Enumerar tareas: Es un acceso amplio a las tareas, destinado solo a usuarios de confianza.

Nota: Si usas el modelo de cliente de confianza que proporciona al conductor el control de las tareas, ten en cuenta que el SDK de Driver no admite la búsqueda ni la creación de listas de tareas.

Buscar tareas

En esta sección, se describe cómo buscar tareas por ID de tarea o ID de seguimiento. Tiene los siguientes requisitos:

• Las búsquedas por ID de seguimiento deben cumplir con las reglas de visibilidad establecidas en Reglas de visibilidad para objetos con seguimiento.

• Usa el token más limitado posible para reducir los riesgos de seguridad. Por ejemplo, si usas un token de consumidor de entrega, las llamadas solo devuelven información relevante para ese usuario final, como el remitente o el destinatario de un envío. Fleet Engine oculta toda la demás información en las respuestas. Para obtener más información sobre los tokens, consulta Tokens web JSON.

Busca una tarea por su ID

Puedes buscar una tarea por su ID desde un entorno de servidor con gRPC o REST. En los siguientes ejemplos, se muestra cómo usar la biblioteca de gRPC de Java o una solicitud REST a 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> es un identificador único para la tarea.
• <taskId> es el ID de la tarea que se buscará.
• El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que tu servidor emite <token> según los lineamientos descritos en Roles de la cuenta de servicio y Tokens web JSON.
• El cuerpo de la solicitud debe estar vacío.
• Si la búsqueda se realiza de forma correcta, el cuerpo de la respuesta contendrá una entidad de tarea.

Comando curl de ejemplo

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

Busca tareas por ID de seguimiento

En los siguientes ejemplos, se muestra cómo buscar tareas por su ID de seguimiento de envío con gRPC o una llamada HTTP REST a 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> es el ID de seguimiento asociado con la tarea.

• El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> tiene el rol de cuenta de servicio correcto. Consulta Roles de cuentas de servicio.

• Si la búsqueda se realiza correctamente, el cuerpo de la respuesta contendrá una entidad taskTrackingInfo.

Comando curl de ejemplo

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

Enumerar tareas

La creación de listas de tareas requiere un acceso amplio a las tareas. La creación de listas de tareas solo está destinada a usuarios de confianza. Usa los tokens de autenticación de lector de flota de entrega o de administrador de entrega cuando realices solicitudes de tareas de lista. Consulta Roles de cuentas de servicio para obtener más información.

Pagina listas

Las listas de tareas están paginadas. Se puede especificar un tamaño de página en las solicitudes de tareas de lista. Si se especifica un tamaño de página, la cantidad de tareas que se muestran no es mayor que el tamaño de página especificado. Si no se indica un tamaño de página, se usa un valor predeterminado razonable. Si el tamaño de página solicitado supera un valor máximo interno, se usa el máximo interno.

Una lista de tareas puede incluir un token para leer la siguiente página de resultados. Para recuperar esa página siguiente, vuelve a emitir la misma solicitud junto con el token de página. Cuando el token de página que se muestra está vacío, no hay más tareas disponibles para recuperar.

Campos cuando se enumeran tareas

Fleet Engine oculta los siguientes campos cuando se enumeran las tareas:

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

Usa los siguientes formatos de campo según las propuestas de mejora de la API de Google:

Tipo de campo	Formato	Ejemplo
Marca de tiempo	RFC-3339	task_outcome_time = 2022-03-01T11:30:00-08:00
Duración	Cantidad de segundos seguida de una s	task_duration = 120s
Enum	String	state = CLOSED AND type = PICKUP
Ubicación	point.latitude y point.longitude	planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Filtra las tareas de la lista

Puedes filtrar las tareas de la lista por la mayoría de sus propiedades. Para conocer la sintaxis de las consultas de filtro, consulta AIP-160. Si no se especifica ninguna consulta de filtro, se enumeran todas las tareas.

Nota: El filtrado por atributos de tareas puede hacer que la latencia de recuperación aumente de forma significativa, por lo que debe usarse con precaución.

En la siguiente tabla, se muestran las propiedades de tarea válidas que puedes usar para filtrar:

Propiedades de tareas para filtrar listas
type attributes tracking_id delivery_vehicle_id state planned_location	task_duration task_duration_outcome task_outcome task_outcome_location task_outcome_time

Consulta AIP-160 para obtener una lista completa de los operadores de consulta de filtro.

Enumera ejemplos de tareas

En el siguiente ejemplo, se muestra cómo enumerar tareas para un deliveryVehicleId y un atributo de tarea, tanto con la biblioteca de gRPC de Java como con la llamada HTTP REST a ListTasks.

Una respuesta correcta puede estar vacía. Una respuesta vacía indica que no hay tareas asociadas al deliveryVehicleId proporcionado.

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

Para aplicar un filtro a las tareas de la lista, incluye un parámetro de URL "filter" con una consulta de filtro con escape de URL como su valor.

El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que <token> tiene el rol de cuenta de servicio correcto. Consulta Roles de cuentas de servicio.

Una búsqueda exitosa proporciona un cuerpo de respuesta con la siguiente estructura:

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

Comando curl de ejemplo

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

¿Qué sigue?

• Administra los envíos