Encontrar tarefas

Este documento descreve as maneiras como você pode encontrar informações de tarefas em um servidor ou navegador. O Fleet Engine oferece duas maneiras de encontrar tarefas:

  • Procurar tarefas: é possível procurar tarefas pelos seguintes IDs:

    • ID da tarefa: usado por usuários, como operadores de frota, que têm acesso à dos dados da tarefa.
    • ID de acompanhamento: usado pelo software cliente para fornecer informações limitadas para um usuário final, como quando se espera um pacote na sua casa.

    Entenda a diferença entre o ID da tarefa e a tarefa ID de acompanhamento. Eles não são a mesma coisa. Consulte Campos de tarefas básicas na Guia de tarefas agendadas.

  • Listar tarefas: acesso amplo às tarefas, destinado apenas a usuários confiáveis.

.

Procurar tarefas

Esta seção descreve como pesquisar tarefas por ID de tarefa ou de acompanhamento. Ele tem os seguintes requisitos:

  • As pesquisas por ID de acompanhamento precisam seguir as regras de visibilidade indicado nas Regras de visibilidade para objetos rastreados.

  • Use o token mais estreito possível para limitar os riscos de segurança. Por exemplo, se você usar um token de consumidor de entrega, todas as chamadas serão retornadas apenas informações relevantes para esse usuário final, como o remetente ou o destinatário de uma remessa. O Fleet Engine edita todas as outras informações na de resposta. Para saber mais sobre tokens, consulte Tokens JSON Web.

Pesquisar tarefa por ID de tarefa

Você pode pesquisar uma tarefa pelo ID dela em um ambiente de servidor usando gRPC ou REST. Os exemplos a seguir mostram como usar a biblioteca Java gRPC ou uma solicitação REST para 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; é um identificador exclusivo para a tarefa.
  • &lt;taskId&gt; é o código da tarefa a ser pesquisada.
  • O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é emitido pelo seu servidor de acordo com as diretrizes descritas nos Papéis da conta de serviço e Tokens JSON da Web.
  • O corpo da solicitação precisa estar vazio.
  • Se a pesquisa for bem-sucedida, o corpo da resposta conterá uma entidade de tarefa.

Comando curl de exemplo:

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

Pesquisar tarefas pelo ID de acompanhamento

Os exemplos a seguir mostram como pesquisar tarefas pelo ID de rastreamento de frete usando gRPC ou uma chamada HTTP REST para 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; é o ID de acompanhamento associado à tarefa.

  • O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> carrega o serviço correto. função de conta de serviço. Consulte Papéis da conta de serviço.

  • Se a pesquisa for bem-sucedida, o corpo da resposta conterá uma entidade taskTrackingInfo.

Comando curl de exemplo:

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

Listar tarefas

A listagem de tarefas solicita amplo acesso às tarefas. A listagem de tarefas é destinada apenas a usuários confiáveis. Usar tokens de autenticação do Delivery Fleet Reader ou do Delivery Admin ao fazer solicitações de tarefas de lista. Confira Papéis da conta de serviço para mais informações imprecisas ou inadequadas.

Paginar listas

As listas de tarefas são paginadas. Um tamanho de página pode ser especificado em solicitações de lista de tarefas. Se um tamanho de página for especificado, o número de tarefas retornadas não será maior que o tamanho de página especificado. Se nenhum tamanho de página estiver presente, um padrão razoável é usado. Se o tamanho da página solicitado exceder um valor máximo interno, então o máximo interno é usado.

Uma lista de tarefas pode incluir um token para leitura da próxima página de resultados. Para recupere a próxima página e emita novamente a mesma solicitação junto com o token da página. Quando o token de página retornado estiver vazio, não haverá mais tarefas disponíveis para recuperação.

Campos ao listar tarefas

O Fleet Engine edita os seguintes campos ao listar tarefas:

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

Use os seguintes formatos de campo com base nas propostas de melhoria da API do Google:

Tipo de campo Formato Exemplo
Carimbo de data/hora RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Duração Número de segundos seguidos por um s task_duration = 120s
Enumeração String state = CLOSED AND type = PICKUP
Local point.latitude e point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Filtrar tarefas listadas

É possível filtrar tarefas listadas pela maioria das propriedades da tarefa. Para a sintaxe da consulta de filtro, consulte AIP-160 (link em inglês). Se nenhuma consulta de filtro for especificada, todas as tarefas serão listadas.

A tabela a seguir mostra propriedades de tarefa válidas que podem ser usadas para filtragem:

Propriedades de tarefas 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

Consulte AIP-160 para ver uma lista completa de operadores de consulta de filtro.

Listar exemplos de tarefas

O exemplo abaixo mostra como listar tarefas de uma deliveryVehicleId e uma atributo de tarefa com a biblioteca Java gRPC e com chamada HTTP REST para ListTasks.

Uma resposta bem-sucedida ainda pode estar vazia. Uma resposta vazia indica que não tarefas associadas ao deliveryVehicleId fornecido.

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 um filtro às tarefas listadas, inclua um "filtro" Parâmetro de URL com uma consulta de filtro com escape de URL como valor.

O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> carrega o serviço correto. função de conta de serviço. Consulte Papéis da conta de serviço.

Uma pesquisa bem-sucedida fornece um corpo de resposta com a seguinte estrutura:

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

Comando curl de exemplo:

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

A seguir