Atualizar tarefas do veículo de entrega

Este documento pressupõe que você já conhece os seguintes conceitos:

Em um cenário de entrega real, as empresas atribuem tarefas de envio de entrega aos motoristas, que usam um veículo para entregá-las ao destinatário em um local planejado, como uma residência ou uma sala de entrega em um complexo de edifícios. Você modela isso no Fleet Engine criando uma tarefa e emitindo uma solicitação de atualização do veículo de entrega, que atualiza a entidade do veículo com uma lista de paradas a serem percorridas. 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 os seguintes fins:

  • Programar tarefas para um veículo concluir. Você pode fazer isso com uma solicitação de atualização que adiciona uma nova parada ao veículo ou com uma solicitação de atualização que adiciona uma nova tarefa a uma parada atual.
  • Atualizar a ordem das tarefas atuais associadas a uma determinada parada do 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 a ela. Se preferir, você pode especificar locais específicos para tarefas individuais. Por exemplo, um veículo pode parar em um grande complexo para entregar vários pacotes, cada um deles atribuído a uma sala de entrega de correspondências específica.
  • Fechar as tarefas atribuídas anteriormente para deixá-las fora da ordem atualizada. Consulte Finalizar tarefas para mais detalhes.

Programar ou mudar tarefas de entrega

É possível programar ou mudar 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 tarefas usando um dispositivo confiável. Use apenas um método para evitar condições de corrida e manter uma única fonte de verdade.

Para mudar um envio 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

Esta seção documenta os campos obrigatórios a serem 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 segmentos de jornada para tarefas na ordem em que devem ser executadas. A primeira tarefa na 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 nessa 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 Java gRPC e uma chamada HTTP REST 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 para o qual você pretende atualizar a ordem das tarefas. É o identificador especificado 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 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 DeliveryVehicle.

Exemplo de comando curl:

  # 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