Atualizar status da parada

Este documento pressupõe que você esteja familiarizado com o seguinte:

• [Criar tarefas de envio][1]
• A introdução às [tarefas programadas][3], que aborda a relação entre tarefas, paradas e veículos em detalhes.

Conforme declarado em [Tarefas programadas][3] no Fleet Engine Essentials, você cria tarefas e as associa a uma parada de veículo como uma forma de modelar a associação no mundo real entre a tarefa e o local onde o veículo deve parar para que o motorista possa concluir a tarefa.

A partir daí, você gerencia o progresso das tarefas ao longo do ciclo de vida delas enviando atualizações para o Fleet Engine. Assim, ele pode realizar atualizações de roteamento e status da melhor forma possível durante a jornada da tarefa. Uma das principais maneiras de fazer isso é atualizar a parada do veículo quando ele se aproxima, chega e sai do local. Isso permite a geração de relatórios e análises sobre o progresso da tarefa para operadores de frota e usuários finais. Estas são as atualizações de status:

• Em trânsito: o enum STATE para VehicleStop usa ENROUTE para indicar que a parada é a próxima na lista do itinerário do veículo. Do ponto de vista da tarefa, isso significa que qualquer tarefa associada à parada é a próxima na lista a ser concluída.
• Chegou: o enum STATE para VehicleStop usa ARRIVED para indicar que o veículo chegou à parada. Do ponto de vista da tarefa, isso significa que qualquer tarefa associada à parada está sendo trabalhada ativamente.
• Concluída: para marcar uma parada como concluída, remova-a da lista de paradas do veículo. Quando você faz isso, o Fleet Engine marca automaticamente todas as tarefas associadas como "CLOSED". Para mais detalhes sobre como encerrar tarefas, consulte [Finalizar tarefas][4].

Neste documento, descrevemos como atualizar o status de interrupção usando abordagens do lado do servidor. Você também pode fazer isso no app de motorista se permitir que ele gerencie tarefas usando um dispositivo confiável. Use apenas um método para evitar disputas e manter uma única fonte de verdade.

O veículo está a caminho da parada

Seu sistema precisa notificar o Fleet Engine quando o veículo iniciar o trajeto até a próxima parada. Isso melhora o HEC e os cálculos de rota.

Campos obrigatórios para atualizações de paradas

O Fleet Engine ignora todos os outros campos na entidade para a notificação.

Campo	Valor
remainingVehicleJourneySegments	Lista das paradas restantes do veículo com os estados marcados como State.NEW.

Exemplo de rota para parada

Os exemplos a seguir mostram como notificar o Fleet Engine de que um veículo está a caminho da próxima parada, usando a [biblioteca Java gRPC][5] ou uma chamada HTTP REST para UpdateDeliveryVehicle.Todas as outras paradas são marcadas como novas.

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String VEHICLE_ID = "vehicle-8241890";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Vehicle settings
 DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
     // Next stop marked as ENROUTE
     .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.ENROUTE)))
     // All other stops marked as 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 updateDeliveryVehicleRequest =
   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 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 [Funções da conta de serviço][6] e [Tokens da Web JSON][6].
• O corpo da solicitação precisa conter uma entidade DeliveryVehicle:

Comando curl de exemplo:

Observação: esse comando substitui qualquer remainingVehicleJourneySegments já definido no veículo de entrega.

 # 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": "ENROUTE",
         "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

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

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

O veículo chega à parada

O Fleet Engine precisa ser notificado quando um veículo chega a uma parada.

Campos obrigatórios para atualizações de paradas

O Fleet Engine ignora todos os outros campos na entidade para a notificação.

Campo	Valor
remainingVehicleJourneySegments	Lista das paradas restantes do veículo com os estados marcados como State.NEW.

Exemplo de chegada na parada

Os exemplos a seguir mostram como notificar o Fleet Engine de que um veículo chegou na parada, usando a [biblioteca Java gRPC][5] ou uma chamada HTTP REST para UpdateDeliveryVehicle. Todas as outras paradas são marcadas como novas.

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";
  static final String VEHICLE_ID = "vehicle-8241890";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Vehicle settings
  String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
  DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
      // Marking the arrival at stop.
      .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
         .setStop(VehicleStop.newBuilder()
             .setPlannedLocation(LocationInfo.newBuilder()
                 .setPoint(LatLng.newBuilder()
                     .setLatitude(37.7749)
                     .setLongitude(122.4194)))
             .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
             .setState(VehicleStop.State.ARRIVED)))
      // All other remaining stops marked as 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))) // Remaining stops must be NEW.
      .build();

  // DeliveryVehicle request
  UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
    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 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 [Funções da conta de serviço][6] e [Tokens da Web JSON][6].
• O corpo da solicitação precisa conter uma entidade DeliveryVehicle:

Comando curl de exemplo:

Observação: esse comando substitui qualquer remainingVehicleJourneySegments já definido no veículo de entrega.

  # 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": "ARRIVED",
          "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

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

O veículo conclui uma parada

O Fleet Engine precisa ser notificado quando um veículo conclui uma parada. Isso faz com que todas as tarefas associadas à parada sejam definidas como um estado CLOSED.

Campos obrigatórios para atualizações de paradas

O Fleet Engine ignora todos os outros campos na entidade para a notificação.

Campo	Valor
remainingVehicleJourneySegments	Lista das paradas restantes do veículo com os estados marcados como State.NEW. A primeira parada na lista precisa ter o estado marcado como State.ENROUTE.

Conclui um exemplo de parada

Os exemplos a seguir mostram como notificar o Fleet Engine de que um veículo chegou na parada, usando a [biblioteca Java gRPC][5] ou uma chamada HTTP REST para UpdateDeliveryVehicle. Todas as outras paradas são marcadas como novas.

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";
  static final String VEHICLE_ID = "vehicle-8241890";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Vehicle settings
  String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
  DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
      // This stop has been completed and is commented out to indicate it
      // should be removed from the list of vehicle journey segments.
      // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
      //    .setStop(VehicleStop.newBuilder()
      //        .setPlannedLocation(LocationInfo.newBuilder()
      //            .setPoint(LatLng.newBuilder()
      //                .setLatitude(37.7749)
      //                .setLongitude(122.4194)))
      //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
      //        .setState(VehicleStop.State.ARRIVED)))
      // All other remaining stops marked as NEW.
      // The next stop could be marked as ENROUTE if the vehicle has begun
      // its journey to the next stop.
      .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next 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 updateDeliveryVehicleRequest =
    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=remaining_vehicle_journey_segments`

• <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 [Funções da conta de serviço][6] e [Tokens da Web JSON][6].
• O corpo da solicitação precisa conter uma entidade DeliveryVehicle:

Comando curl de exemplo:

Observação: esse comando substitui qualquer remainingVehicleJourneySegments já definido no veículo de entrega.

 # 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.3382,
             "longitude": 121.8863
           }
         },
         "tasks": [
           {
             "taskId": "${TASK2_ID}"
           }
         ]
       }
     }
   ]
 }
 EOM

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

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

A seguir

• [Finalizar tarefas][4]

[1]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks [3]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [4]: /maps/documentation/mobility/fleet-engine/journeys/tasks/finalize-tasks [5]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts