Criar tarefas de envio

Este documento pressupõe que você leu o guia introdutório sobre Tarefas programadas na seção Introdução ao Fleet Engine, bem como O que é uma tarefa programada? nesta seção.

O Fleet Engine para tarefas programadas oferece diferentes categorias amplas de tarefas:

  • Tarefas de envio: use para tarefas de direção, incluindo coleta e entrega de envio.
  • Tarefas de indisponibilidade: use quando os motoristas não estiverem disponíveis, por exemplo, com intervalos obrigatórios.
  • Tarefas de parada programada: use para tarefas que não sejam de direção em caixas de depósito ou locais de clientes, como horário para entrar em um edifício ou localizar um ponto de entrega.

Neste documento, mostramos como criar tarefas de envio no seu servidor. Para outros tipos de tarefas, consulte Criar outros tipos de tarefas.

Campos de tarefas de envio

Esta seção documenta os campos de tarefa necessários para tarefas de retirada e entrega.

Campos de tarefa obrigatórios

Para cada tarefa criada no Fleet Engine, é necessário fornecer os campos obrigatórios e também pode ser necessário fornecer qualquer um dos campos opcionais. O Fleet Engine ignora todos os outros campos e gera uma exceção se uma solicitação de criação de tarefa fornecer um deliveryVehicleId atribuído. Para atribuir tarefas a um veículo, use UpdateDeliveryVehicleRequest. Para mais informações, consulte Tarefas de atualização.

CampoValor
type

Defina com o tipo que corresponde ao tipo de tarefa, que pode ser um dos seguintes:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id ID exclusivo da tarefa. Esse número não pode ser o número de rastreamento do envio. Se você não tem IDs de tarefas no seu sistema, pode gerar um identificador universalmente exclusivo (UUID). Para detalhes, consulte IDs de tarefas.
tracking_id Somente tarefas PICKUP ou DELIVERY: o número ou identificador que você está usando para rastrear um envio. Não preencha este campo para tarefas que não sejam de envio.
plannedLocation Somente tarefas PICKUP, DELIVERY ou SCHEDULED_STOP: o local em que a tarefa precisa ser concluída. Não é necessário para tarefas UNAVAILABLE.
taskDuration O tempo esperado para concluir a tarefa. Por exemplo, para procurar um estacionamento ou caminhar até o local de transferência.

Campos opcionais da tarefa de envio

CampoValor
targetTimeWindow A janela de tempo em que a tarefa deve ser concluída. Esse campo não afeta o comportamento de roteamento.
task_tracking_view_config Somente tarefas PICKUP ou DELIVERY: a configuração de rastreamento de tarefas que especifica quais elementos de dados são visíveis para os usuários finais e em quais circunstâncias.
attributes Uma lista de atributos de tarefa personalizados. Cada atributo precisa ter uma chave exclusiva.

Criar uma tarefa de retirada de envio

Para usar o Fleet Engine e acompanhar a atividade de um motorista que está retirando um envio, crie uma tarefa de retirada de envio. Isso envolve definir o atributo do tipo de tarefa como PICKUP. O exemplo a seguir ilustra a retirada de um envio do Grand Indonesia East Mall.

Os exemplos a seguir mostram como criar uma tarefa de retirada de envio usando a biblioteca Java gRPC ou como fazer uma solicitação HTTP REST para CreateTask.

gRPC

  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))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .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

Para criar uma tarefa de retirada de envio em um ambiente de servidor, faça uma chamada HTTP REST para CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> é um identificador exclusivo da tarefa.

O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, em que <token> é emitido pelo servidor de acordo com as diretrizes descritas em Papéis da conta de serviço e tokens JSON da Web.

O corpo da solicitação precisa conter uma entidade Task com os campos adequados descritos em Campos da tarefa de envio.

Comando curl de exemplo:

 # 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",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 EOM

Criar uma tarefa de entrega de remessa

Para usar o Fleet Engine e acompanhar a atividade de um motorista que entrega uma remessa, crie uma tarefa de entrega de remessa. Isso envolve definir o atributo de tipo de tarefa como DELIVERY. O exemplo a seguir ilustra uma entrega de remessa para o Grand Indonesia East Mall.

Os exemplos a seguir mostram como criar uma tarefa de retirada de envio usando a biblioteca Java gRPC ou como fazer uma solicitação HTTP REST para CreateTask.

gRPC

  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))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .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

Para criar uma tarefa de retirada de envio em um ambiente de servidor, faça uma chamada HTTP REST para CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> é um identificador exclusivo da tarefa.

O cabeçalho da solicitação precisa conter um campo Autorização com o valor Bearer <token>, em que <token> é emitido pelo servidor de acordo com as diretrizes descritas em Papéis da conta de serviço e JSON Web Tokens.

O corpo da solicitação precisa conter uma entidade Task:

Comando curl de exemplo:

 # 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",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 EOM
 ```

A seguir