Criar tarefas de envio

Este documento pressupõe que você leu o guia introdutório para Tarefas agendadas também na seção Introdução ao Fleet Engine como O que é uma tarefa agendada? nesta seção.

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

  • Tarefas de envio: use para tarefas de condução, incluindo coleta e entrega de remessas.
  • Tarefas de indisponibilidade: use para horários em que os motoristas não estiverem disponíveis, como assim como os intervalos obrigatórios.
  • Tarefas com paradas programadas: use para tarefas que não sejam a direção do carro em caixas de depósito ou clientes. locais, como tempo 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 tarefa, consulte Criar outros tipos de tarefa.

Campos da tarefa de envio

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

Campos de tarefa obrigatórios

Para cada tarefa criada no Fleet Engine, você precisa fornecer as informações e também pode fornecer qualquer um dos campos opcionais. Motor de frota ignora todos os outros campos e gera uma exceção se uma criação de tarefa solicitação fornece um deliveryVehicleId atribuído. Para atribuir tarefas a um veículo, use UpdateDeliveryVehicleRequest. Para mais informações, consulte Atualizar tarefas.

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ão pode ser o número de rastreamento do envio. Se você não têm IDs de tarefas em seu sistema, é possível gerar um ID de (UUID). Para mais detalhes, consulte IDs de tarefas.
tracking_id Apenas tarefas PICKUP ou DELIVERY: O número ou identificador que você está usando para rastrear um envio. Não informe este campo para tarefas que não sejam de envio.
plannedLocation PICKUP, DELIVERY ou SCHEDULED_STOP apenas tarefas: o local onde a tarefa será concluída. Não é necessário para UNAVAILABLE tarefas.
taskDuration O tempo esperado a ser adicionado para concluir a tarefa. Por exemplo, para procurar para estacionar ou caminhar até o local de transferência.

Campos de tarefa de remessa opcionais

CampoValor
targetTimeWindow A janela de tempo em que a tarefa deve ser concluída. Este campo não afeta o comportamento de roteamento.
task_tracking_view_config Apenas tarefas PICKUP ou DELIVERY: Configuração para o rastreamento de tarefas que especifica quais elementos de dados que são visíveis para os usuários finais 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 frete

Para usar o Fleet Engine para acompanhar a atividade de um motorista ao retirar uma remessa, criar uma tarefa de retirada de remessas. Isso envolve definir o atributo do tipo de tarefa como PICKUP: O exemplo a seguir ilustra uma retirada de remessa no Indonesia East Mall.

Os exemplos a seguir mostram como criar uma tarefa de retirada da remessa usando o 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 frete em um ambiente de servidor, crie uma solicitação HTTP REST Chamada para CreateTask:

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

&lt;id&gt; é um identificador exclusivo para a 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 às diretrizes descritas nos Papéis da conta de serviço e nos Papéis da Web JSON tokens.

O corpo da solicitação precisa conter uma entidade Task com os campos apropriados descritos nos 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 para acompanhar a atividade de um motorista que entrega uma remessa, criar uma tarefa de entrega de remessas. Isso envolve definir o atributo do tipo de tarefa para DELIVERY. O exemplo a seguir ilustra uma entrega de remessa para o Indonesia East Mall.

Os exemplos a seguir mostram como criar uma tarefa de retirada da remessa usando o 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 frete em um ambiente de servidor, crie uma solicitação HTTP REST Chamada para CreateTask:

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

&lt;id&gt; é um identificador exclusivo para a 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 às diretrizes descritas nos Papéis da conta de serviço e nos Papéis da Web JSON 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