Mettre à jour l'état des arrêts

Dans ce document, nous partons du principe que vous connaissez les éléments suivants :

• [Créer des tâches d'envoi][1]
• La présentation des [tâches planifiées][3], qui décrit en détail la relation entre les tâches, les arrêts et les véhicules.

Comme indiqué dans [Tâches planifiées][3] dans Fleet Engine Essentials, vous créez des tâches et les associez à un arrêt de véhicule pour modéliser l'association réelle entre la tâche et l'emplacement où le véhicule doit s'arrêter pour que le conducteur puisse effectuer la tâche.

À partir de là, vous gérez la progression des tâches tout au long de leur cycle de vie en envoyant des mises à jour à Fleet Engine afin qu'il puisse effectuer au mieux le routage et les mises à jour d'état tout au long du parcours de la tâche. Pour ce faire, vous devez mettre à jour l'arrêt du véhicule lorsque celui-ci s'approche de l'arrêt, y arrive et le quitte. Cela permet de créer des rapports et d'analyser la progression des tâches pour les opérateurs de parc et les utilisateurs finaux. Voici les différents états possibles :

• En route : l'énumération STATE pour VehicleStop utilise ENROUTE pour indiquer que l'arrêt est le prochain sur la liste de l'itinéraire du véhicule. Du point de vue de la tâche, cela signifie que toute tâche associée à l'arrêt est la suivante sur la liste des tâches à effectuer.
• Arrived : l'énumération STATE pour VehicleStop utilise ARRIVED pour indiquer que le véhicule est arrivé à l'arrêt. Du point de vue de la tâche, cela signifie que toute tâche associée à l'arrêt n'est plus traitée activement.
• Terminé : vous marquez un arrêt comme terminé en le supprimant de la liste des arrêts du véhicule. Dans ce cas, Fleet Engine marque automatiquement toutes les tâches associées comme CLOSED. Pour en savoir plus sur la clôture des tâches, consultez [Finaliser les tâches][4].

Ce document explique comment mettre à jour l'état d'arrêt à l'aide d'approches côté serveur. Vous pouvez également le faire depuis votre application de chauffeur si vous lui permettez de gérer les tâches à l'aide d'un appareil de confiance. N'utilisez qu'une seule méthode pour éviter les conditions de concurrence et conserver une source unique de vérité.

Le véhicule est en route vers l'arrêt

Votre système doit avertir Fleet Engine lorsque le véhicule commence à naviguer vers l'arrêt suivant. Cela permet d'améliorer les calculs d'itinéraire et d'heure d'arrivée prévue.

Champs obligatoires pour les mises à jour des arrêts

Fleet Engine ignore tous les autres champs de l'entité pour la notification.

Champ	Valeur
remainingVehicleJourneySegments	Liste des arrêts de véhicule restants, dont l'état est marqué comme State.NEW.

Exemple d'arrêt en cours de route

Les exemples suivants montrent comment indiquer à Fleet Engine qu'un véhicule est en route vers son prochain arrêt, à l'aide de la [bibliothèque gRPC Java][5] ou d'un appel REST HTTP à UpdateDeliveryVehicle.Tous les autres arrêts sont marqués comme nouveaux.

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> est un identifiant unique pour la tâche.
• L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est émis par votre serveur conformément aux consignes décrites dans [Rôles de compte de service][6] et [Jetons Web JSON][6].
• Le corps de la requête doit contenir une entité DeliveryVehicle :

Exemple de commande curl :

Remarque : Cette commande remplace tout remainingVehicleJourneySegments déjà défini sur le véhicule de livraison.

 # 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

Expérimental : en tant que fonctionnalité expérimentale, le champ LocationInfo (gRPC ou REST) est désormais compatible avec l'utilisation de place (gRPC ou REST), en plus ou à la place 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

Le véhicule arrive à l'arrêt

Fleet Engine doit être averti lorsqu'un véhicule arrive à un arrêt.

Champs obligatoires pour les mises à jour des arrêts

Fleet Engine ignore tous les autres champs de l'entité pour la notification.

Champ	Valeur
remainingVehicleJourneySegments	Liste des arrêts de véhicule restants, dont l'état est marqué comme State.NEW.

Exemple d'arrivée à l'arrêt

Les exemples suivants montrent comment indiquer à Fleet Engine qu'un véhicule est arrivé à l'arrêt, à l'aide de la [bibliothèque gRPC Java][5] ou d'un appel REST HTTP à UpdateDeliveryVehicle. Tous les autres arrêts sont marqués comme nouveaux.

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> est un identifiant unique pour la tâche.
• L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est émis par votre serveur conformément aux consignes décrites dans [Rôles de compte de service][6] et [Jetons Web JSON][6].
• Le corps de la requête doit contenir une entité DeliveryVehicle :

Exemple de commande curl :

Remarque : Cette commande écrase tout remainingVehicleJourneySegments déjà défini sur le véhicule de livraison.

  # 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

Expérimental : en tant que fonctionnalité expérimentale, le champ LocationInfo (gRPC ou REST) est désormais compatible avec l'utilisation de place (gRPC ou REST), en plus ou à la place de LatLng.

Le véhicule s'arrête

Fleet Engine doit être averti lorsqu'un véhicule effectue un arrêt. Toutes les tâches associées à l'arrêt sont alors définies sur l'état CLOSED.

Champs obligatoires pour les mises à jour des arrêts

Fleet Engine ignore tous les autres champs de l'entité pour la notification.

Champ	Valeur
remainingVehicleJourneySegments	Liste des arrêts de véhicule restants, dont l'état est marqué comme State.NEW. Le premier arrêt de la liste doit être marqué comme State.ENROUTE.

Termine un exemple d'arrêt

Les exemples suivants montrent comment indiquer à Fleet Engine qu'un véhicule est arrivé à l'arrêt, à l'aide de la [bibliothèque gRPC Java][5] ou d'un appel REST HTTP à UpdateDeliveryVehicle. Tous les autres arrêts sont marqués comme nouveaux.

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> est un identifiant unique pour la tâche.
• L'en-tête de requête doit contenir un champ Authorization avec la valeur Bearer <token>, où <token> est émis par votre serveur conformément aux consignes décrites dans [Rôles de compte de service][6] et [Jetons Web JSON][6].
• Le corps de la requête doit contenir une entité DeliveryVehicle :

Exemple de commande curl :

Remarque : Cette commande écrase tout remainingVehicleJourneySegments déjà défini sur le véhicule de livraison.

 # 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

Expérimental : en tant que fonctionnalité expérimentale, le champ LocationInfo (gRPC ou REST) est désormais compatible avec l'utilisation de place (gRPC ou REST), en plus ou à la place 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

Étape suivante

• [Finaliser les tâches][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