Criar tarefas de envio

Neste documento, presumimos que você leu o guia introdutório sobre tarefas programadas na seção Introdução ao Fleet Engine e o artigo O que é uma tarefa programada? nesta seção.

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

• Tarefas de envio: usadas para tarefas de direção, incluindo coleta e entrega de envios.
• Tarefas de indisponibilidade: usadas para momentos em que os motoristas não estão disponíveis, como em intervalos obrigatórios.
• Tarefas de parada programada: usadas para tarefas que não envolvem direção em caixas de entrega ou locais de clientes, como tempo para entrar em um prédio ou localizar um ponto de entrega.

Este documento aborda 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 tarefas necessários para tarefas de coleta e entrega.

Campos de tarefas obrigatórios

Para cada tarefa criada no Fleet Engine, você precisa fornecer os campos obrigatórios e também pode 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 Atualizar tarefas.

Campo	Valor
type	Defina o tipo que corresponde ao tipo de tarefa, que é um destes: PICKUP DELIVERY SCHEDULED_STOP UNAVAILABLE
state	State.OPEN
task_id	ID exclusivo da tarefa. Não pode ser o número de rastreamento do envio. Se você não tiver IDs de tarefas no seu sistema, poderá gerar um identificador único universal (UUID). Para mais detalhes, consulte IDs de tarefas.
tracking_id	PICKUP ou DELIVERY tarefas apenas: O número ou identificador que você está usando para rastrear um envio. Não forneça esse campo para tarefas que não sejam de envio.
planned_location	PICKUP, DELIVERY, ou SCHEDULED_STOP tarefas apenas: O local onde a tarefa será concluída. Não é obrigatório para UNAVAILABLE tarefas.
task_duration	O tempo esperado para concluir a tarefa. Por exemplo, para procurar estacionamento ou caminhar até o local de entrega.

Campos opcionais de tarefas de envio

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

Criar uma tarefa de coleta de envio

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

Os exemplos a seguir mostram como criar uma tarefa de coleta de envio usando a biblioteca gRPC Java 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 coleta 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 seu servidor de acordo com as diretrizes descritas em Papéis da conta de serviço e tokens da Web JSON.

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

Exemplo de comando curl:

 # 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

Experimental: como um recurso experimental, o campo LocationInfo (gRPC ou REST) agora oferece suporte ao uso de place (gRPC ou REST), junto com ou em vez de LatLng.

Criar uma tarefa de entrega de envio

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

Os exemplos a seguir mostram como criar uma tarefa de coleta de envio usando a biblioteca gRPC Java 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 coleta 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 seu servidor de acordo com as diretrizes descritas em Papéis da conta de serviço e tokens da Web JSON.

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

Exemplo de comando curl:

 # 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
 ```

Experimental: como um recurso experimental, o campo LocationInfo (gRPC ou REST) agora oferece suporte ao uso de place (gRPC ou REST), junto com ou em vez de LatLng.

A seguir

• Criar outros tipos de tarefas
• Atualizar tarefas