Atualizar tarefas do veículo de entrega

Este documento pressupõe que você esteja familiarizado 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. 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 para viajar. 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. Isso pode ser feito 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 existente.
  • Atualize a ordem das tarefas atuais associadas a uma determinada parada de veículo.
  • Mude 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, 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.
  • Feche as tarefas atribuídas anteriormente para que elas não apareçam na ordenação atualizada. Consulte Concluir tarefas para mais detalhes.

Agendar 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 Driver, se você permitir que o motorista gerencie tarefas usando um dispositivo confiável. Use apenas um método para evitar disputas e manter uma única fonte de verdade.

Para mudar uma entrega de um veículo para outro, encerre a tarefa original e recrie-a antes de atribuir a outro veículo. Se você atualizar um veículo de entrega para incluir uma tarefa já 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 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 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 gRPC Java 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 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 Funções da conta de serviço e Tokens da Web JSON.

  • 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