Actualizar el estado de la parada

En este documento, se supone que conoces lo siguiente:

Como se indica en Tareas programadas en Nociones básicas del motor de flota, creas tareas y las asocias con una parada del vehículo como una forma de modelar la asociación real entre la tarea y la ubicación en la que se espera que se detenga el vehículo para que el conductor pueda completar la tarea.

Desde allí, puedes administrar el progreso de las tareas a lo largo de su ciclo de vida. Para ello, envía actualizaciones a Fleet Engine para que pueda realizar mejor las actualizaciones de enrutamiento y estado a lo largo del recorrido de la tarea. Una forma clave de hacerlo es actualizar la parada del vehículo cuando este se acerca, llega y sale de la parada. Esto permite generar informes y análisis sobre el progreso de las tareas para los operadores de flotas y los usuarios finales. Estas actualizaciones de estado son las siguientes:

  • En ruta: La enumeración STATE para VehicleStop usa ENROUTE para indicar que la parada es la siguiente en la lista del itinerario del vehículo. Desde la perspectiva de la tarea, significa que cualquier tarea asociada con la parada es la siguiente en la lista que se debe completar.
  • Llegó: La enumeración STATE para VehicleStop usa ARRIVED para indicar que el vehículo llegó a la parada. Desde la perspectiva de la tarea, significa que cualquier tarea asociada con la parada en la que se está trabajando de forma activa.
  • Completada: Para marcar una parada como completa, quítala de la lista de paradas del vehículo. Cuando lo hagas, Fleet Engine marcará automáticamente todas las tareas asociadas como CERRADAS. Para obtener más detalles sobre cómo cerrar tareas, consulta Finaliza tareas.

En este documento, se describe cómo actualizar el estado de detención con enfoques del servidor. También puedes hacerlo desde la app del conductor si le brindas la capacidad de administrar tareas con un dispositivo de confianza. Usa solo un método para evitar condiciones de carrera y mantener una única fuente de información.

El vehículo está en camino a la parada

Tu sistema debe notificar a Fleet Engine cuando el vehículo comience a navegar a la siguiente parada. Esto mejora los cálculos de la hora de llegada estimada y la ruta.

Campos obligatorios para detener las actualizaciones

Fleet Engine ignora todos los demás campos de la entidad para la notificación.

CampoValor
remainingVehicleJourneySegments Es la lista de las paradas restantes del vehículo con sus estados marcados como State.NEW.

Ejemplo de ruta hacia una parada

En los siguientes ejemplos, se muestra cómo notificar a Fleet Engine que un vehículo se dirige a su próxima parada, ya sea con la biblioteca de gRPC de Java o con una llamada HTTP a REST a UpdateDeliveryVehicle.Todas las demás paradas se marcan como nuevas.

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> es un identificador único para la tarea.
  • El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que tu servidor emite <token> según los lineamientos descritos en Roles de la cuenta de servicio y Tokens web JSON.
  • El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

Comando curl de ejemplo

 # 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

El vehículo llega a la parada

Se debe notificar a Fleet Engine cuando un vehículo llega a una parada.

Campos obligatorios para detener las actualizaciones

Fleet Engine ignora todos los demás campos de la entidad para la notificación.

CampoValor
remainingVehicleJourneySegments Es la lista de las paradas restantes del vehículo con sus estados marcados como State.NEW.

Ejemplo de llegada a una parada

En los siguientes ejemplos, se muestra cómo notificar a Fleet Engine que un vehículo llegó a la parada, ya sea con la biblioteca de gRPC de Java o con una llamada HTTP REST a UpdateDeliveryVehicle. Todas las demás paradas se marcan como nuevas.

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> es un identificador único para la tarea.
  • El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que tu servidor emite <token> según los lineamientos descritos en Roles de la cuenta de servicio y Tokens web JSON.
  • El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

Comando curl de ejemplo

  # 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

El vehículo completa una parada

Se debe notificar a Fleet Engine cuando un vehículo completa una parada. Esto hace que todas las tareas asociadas con la parada se establezcan en un estado CERRADO.

Campos obligatorios para detener las actualizaciones

Fleet Engine ignora todos los demás campos de la entidad para la notificación.

CampoValor
remainingVehicleJourneySegments Es la lista de las paradas restantes del vehículo con sus estados marcados como State.NEW. El estado de la primera parada de la lista debe estar marcado como State.ENROUTE.

Completa un ejemplo de detención

En los siguientes ejemplos, se muestra cómo notificar a Fleet Engine que un vehículo llegó a la parada, ya sea con la biblioteca de gRPC de Java o con una llamada HTTP REST a UpdateDeliveryVehicle. Todas las demás paradas se marcan como nuevas.

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> es un identificador único para la tarea.
  • El encabezado de la solicitud debe contener un campo Authorization con el valor Bearer <token>, en el que tu servidor emite <token> según los lineamientos descritos en Roles de la cuenta de servicio y Tokens web JSON.
  • El cuerpo de la solicitud debe contener una entidad DeliveryVehicle:

Comando curl de ejemplo

 # 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

¿Qué sigue?