Atualizar tarefas do veículo de entrega

Para seguir este documento, é preciso ter familiaridade com os seguintes tópicos:

Em um cenário de entrega real, as empresas atribuem tarefas de envio de entrega a 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 edifício. Para criar esse modelo 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 viajar. Você atribui a cada parada uma lista de tarefas a serem concluídas.

Você pode atualizar as tarefas do veículo a qualquer momento, mas geralmente faz isso para os seguintes fins:

  • Programar tarefas para um veículo. 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 inclua uma nova tarefa a uma parada existente.
  • Atualizar a ordem das tarefas atuais associadas a uma determinada parada do veículo.
  • Mude o local da conclusão da tarefa. Por padrão, o Fleet Engine marca o local de conclusão da tarefa como o mesmo local da parada de veículo associada a ela. Se preferir, você pode especificar locais específicos para tarefas individuais. Por exemplo, você pode ter um veículo que para em um grande complexo para entregar vários pacotes, cada um atribuído a uma sala de entrega de correspondências específica.
  • Feche as tarefas atribuídas anteriormente para que elas fiquem de fora da ordem atualizada. Consulte Finalizar tarefas para mais detalhes.

Programar ou alterar 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 disputa e manter uma única fonte da verdade.

Para mudar um envio de um veículo para outro, feche a tarefa original e a recrie antes de atribuir a um veículo diferente. Se você atualizar um veículo de entrega para incluir uma tarefa que já foi atribuída a outro veículo, 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 foi fornecido. O mecanismo de frota ignora todos os outros campos na entidade para a atualização.

Campo obrigatórioValor
remainingVehicleJourneySegments Uma lista de segmentos da jornada para tarefas na ordem em que elas precisam 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 de veículo.
remainingVehicleJourneySegments[i].stop.state State.NEW

Exemplo de atribuição de tarefas

Nos exemplos a seguir, mostramos como usar a biblioteca Java gRPC e uma chamada REST HTTP para UpdateDeliveryVehicle a fim de 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 Papéis da conta de serviço e tokens JSON da 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