Atualizar tarefas do veículo de entrega

Este documento pressupõe que você tenha familiaridade com o seguinte:

Em um cenário de entrega real, as empresas atribuem tarefas de entrega a motoristas, que usam um veículo para entregar os itens ao destinatário em um local planejado, como uma residência ou uma sala de entrega em um complexo de edifícios. Para modelar isso no Fleet Engine, crie uma tarefa e emita uma solicitação de atualização do veículo de entrega, que atualiza a entidade do veículo com uma lista de paradas para percorrer. Você atribui a cada parada uma lista de tarefas a serem concluídas.

É possível atualizar as tarefas do veículo a qualquer momento, mas geralmente isso é feito para as seguintes finalidades:

  • Programar tarefas para um veículo concluir. Para isso, faça uma solicitação de atualização que adicione uma nova parada ao veículo ou uma solicitação de atualização que adicione uma nova tarefa a uma parada atual.
  • Atualizar a ordem das tarefas associadas a uma determinada parada de veículo.
  • Mudar o local de conclusão da tarefa. Por padrão, o Fleet Engine marca o local de conclusão da tarefa como o mesmo local da parada do veículo associada à tarefa. Se preferir, especifique locais específicos para tarefas individuais. Por exemplo, um veículo pode parar em um grande complexo para entregar vários pacotes, cada um atribuído a uma sala de entrega de correspondência específica.
  • Feche as tarefas atribuídas anteriormente para que elas não sejam incluídas na ordem atualizada. Consulte Finalizar tarefas para mais detalhes.

Programar ou mudar tarefas de entrega

É possível programar ou alterar as tarefas atribuídas a um veículo em um ambiente de servidor ou usando o SDK do Driver se você permitir que o motorista gerencie as tarefas usando um dispositivo de confiança. Use apenas um método para evitar disputas e manter uma única fonte de verdade.

Para mudar uma remessa de um veículo para outro, feche a tarefa original e recrie-a antes de atribuir a um veículo diferente. Se você atualizar um veículo de entrega para incluir uma tarefa que já está atribuída a um veículo diferente, vai receber um erro.

Campos obrigatórios para atualizar tarefas

Nesta seção, documentamos os campos obrigatórios que precisam ser definidos ao atualizar uma tarefa para um veículo. Nenhum campo opcional é fornecido. O Fleet Engine ignora todos os outros campos na entidade para a atualização.

Campo obrigatórioValor
remainingVehicleJourneySegments Uma lista de trechos de jornada para tarefas na ordem em que devem ser executadas. A primeira tarefa da lista é executada primeiro.
remainingVehicleJourneySegments[i].stop A parada da tarefa i na lista.
remainingVehicleJourneySegments[i].stop.plannedLocation O local planejado para a parada.
remainingVehicleJourneySegments[i].stop.tasks Uma lista de tarefas a serem realizadas nesta parada do veículo.
remainingVehicleJourneySegments[i].stop.state State.NEW

Exemplo de atribuição de tarefas

Os exemplos a seguir mostram como usar a biblioteca gRPC do Java e uma chamada REST HTTP para UpdateDeliveryVehicle para adicionar duas novas tarefas ao veículo.

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String VEHICLE_ID = "vehicle-8241890";
 static final String TASK1_ID = "task-756390";
 static final String TASK2_ID = "task-849263";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Vehicle settings
 String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
 DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
     .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
        .setStop(VehicleStop.newBuilder()
            .setPlannedLocation(LocationInfo.newBuilder()
                .setPoint(LatLng.newBuilder()
                    .setLatitude(37.7749)
                    .setLongitude(122.4194)))
            .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
            .setState(VehicleStop.State.NEW)))
     .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
        .setStop(VehicleStop.newBuilder()
            .setPlannedLocation(LocationInfo.newBuilder()
                .setPoint(LatLng.newBuilder()
                    .setLatitude(37.3382)
                    .setLongitude(121.8863)))
            .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
            .setState(VehicleStop.State.NEW)))
     .build();

 // DeliveryVehicle request
 UpdateDeliveryVehicleRequest updateDeliveryRequest =
   UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
       .setName(vehicleName)
       .setDeliveryVehicle(deliveryVehicle)
       .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
       .build();

 try {
   DeliveryVehicle updatedDeliveryVehicle =
       deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
 } catch (StatusRuntimeException e) {
   Status s = e.getStatus();
   switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
   }
   return;
 }

REST

 PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

  • <id> é um identificador exclusivo de um veículo de entrega na sua frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou ao criar o veículo.

  • 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 Web.

  • O corpo da solicitação precisa conter uma entidade DeliveryVehicle.

Comando curl de exemplo:

  # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
  # environment
  curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
    -H "Content-type: application/json" \
    -H "Authorization: Bearer ${JWT}" \
    --data-binary @- << EOM
  {
    "remainingVehicleJourneySegments": [
      {
        "stop": {
          "state": "NEW",
          "plannedLocation": {
            "point": {
              "latitude": 37.7749,
              "longitude": -122.084061
            }
          },
          "tasks": [
            {
              "taskId": "${TASK1_ID}"
            }
          ]
        }
      },
      {
        "stop": {
          "state": "NEW",
          "plannedLocation": {
            "point": {
              "latitude": 37.3382,
              "longitude": 121.8863
            }
          },
          "tasks": [
            {
              "taskId": "${TASK2_ID}"
            }
          ]
        }
      }
    ]
  }
  EOM

A seguir