Aggiorna lo stato della fermata

Questo documento presuppone la conoscenza dei seguenti argomenti:

Come indicato in Attività programmate in Fleet Engine Essentials, crei le attività e le associ a una fermata del veicolo per modellare l'associazione nel mondo reale tra l'attività e la località in cui il veicolo dovrebbe fermarsi in modo che l'autista possa completare l'attività.

A questo punto, gestisci l'avanzamento delle attività durante il loro ciclo di vita inviando aggiornamenti a Fleet Engine in modo che possa eseguire al meglio gli aggiornamenti di routing e stato durante il percorso dell'attività. Un modo fondamentale per farlo è aggiornare la fermata del veicolo quando il veicolo si avvicina, arriva e lascia la fermata. In questo modo è possibile generare report e analisi sull'avanzamento delle attività sia per gli operatori della flotta sia per gli utenti finali. Questi aggiornamenti di stato sono i seguenti:

  • In viaggio: l'enum STATE per VehicleStop utilizza ENROUTE per indicare che la fermata è la successiva nell'elenco dell'itinerario del veicolo. Dal punto di vista dell'attività, significa che qualsiasi attività associata alla fermata è la successiva nell'elenco da completare.
  • Arrivato: l'enum STATE per VehicleStop utilizza ARRIVED per indicare che il veicolo è arrivato alla fermata. Dal punto di vista dell'attività, significa che qualsiasi attività associata alla fermata è in fase di elaborazione attiva.
  • Completato: contrassegni una fermata come completata rimuovendola dall'elenco delle fermate del veicolo. In questo caso, Fleet Engine contrassegna automaticamente tutte le attività associate come CHIUSE. Per maggiori dettagli sulla chiusura delle attività, consulta Finalizzare le attività.

Questo documento descrive come aggiornare lo stato della fermata utilizzando approcci lato server. Puoi farlo anche dall'app per autisti se fornisci all'autista la possibilità di gestire le attività utilizzando un dispositivo attendibile. Utilizza un solo metodo per evitare condizioni di race e mantenere un'unica fonte di verità.

Il veicolo è in viaggio verso la fermata

Il sistema deve notificare a Fleet Engine quando il veicolo inizia la navigazione verso la fermata successiva. In questo modo si migliorano i calcoli dell'orario di arrivo stimato e del percorso.

Campi obbligatori per gli aggiornamenti delle fermate

Fleet Engine ignora tutti gli altri campi dell'entità per la notifica.

CampoValore
remainingVehicleJourneySegments Elenco delle fermate del veicolo rimanenti con gli stati contrassegnati come State.NEW.

Esempio di in viaggio verso la fermata

Gli esempi seguenti mostrano come notificare a Fleet Engine che un veicolo è in viaggio verso la fermata successiva, utilizzando la libreria Java gRPC o una chiamata HTTP REST a UpdateDeliveryVehicle.Tutte le altre fermate sono contrassegnate come nuove.

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> è un identificatore univoco per l'attività.
  • L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> viene emesso dal server in base alle linee guida descritte in Ruoli degli account di servizio e token web JSON.
  • Il corpo della richiesta deve contenere un'entità DeliveryVehicle:

Esempio di 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": "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

Il veicolo arriva alla fermata

Fleet Engine deve ricevere una notifica quando un veicolo arriva a una fermata.

Campi obbligatori per gli aggiornamenti delle fermate

Fleet Engine ignora tutti gli altri campi dell'entità per la notifica.

CampoValore
remainingVehicleJourneySegments Elenco delle fermate del veicolo rimanenti con gli stati contrassegnati come State.NEW.

Esempio di arrivo alla fermata

Gli esempi seguenti mostrano come notificare a Fleet Engine che un veicolo è arrivato alla fermata, utilizzando la libreria Java gRPC o una chiamata HTTP REST a UpdateDeliveryVehicle. Tutte le altre fermate sono contrassegnate come nuove.

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> è un identificatore univoco per l'attività.
  • L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> viene emesso dal server in base alle linee guida descritte in Ruoli degli account di servizio e token web JSON.
  • Il corpo della richiesta deve contenere un'entità DeliveryVehicle:

Esempio di 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": "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

Il veicolo completa una fermata

Fleet Engine deve ricevere una notifica quando un veicolo completa una fermata. In questo modo, tutte le attività associate alla fermata vengono impostate sullo stato CHIUSO.

Campi obbligatori per gli aggiornamenti delle fermate

Fleet Engine ignora tutti gli altri campi dell'entità per la notifica.

CampoValore
remainingVehicleJourneySegments Elenco delle fermate del veicolo rimanenti con gli stati contrassegnati come State.NEW. Lo stato della prima fermata dell'elenco deve essere contrassegnato come State.ENROUTE.

Esempio di completamento di una fermata

Gli esempi seguenti mostrano come notificare a Fleet Engine che un veicolo è arrivato alla fermata, utilizzando la libreria Java gRPC o una chiamata HTTP REST a UpdateDeliveryVehicle. Tutte le altre fermate sono contrassegnate come nuove.

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> è un identificatore univoco per l'attività.
  • L'intestazione della richiesta deve contenere un campo Authorization con il valore Bearer <token>, dove <token> viene emesso dal server in base alle linee guida descritte in Ruoli degli account di servizio e token web JSON.
  • Il corpo della richiesta deve contenere un'entità DeliveryVehicle:

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

Passaggi successivi