Actualizar el estado de la parada

En este documento, se supone que tienes conocimientos sobre los siguientes temas:

• Cómo crear tareas de envío
• La introducción a las tareas programadas, que abarca en detalle la relación entre las tareas, las paradas y los vehículos

Como se indica en Tareas programadas en Fundamentos del motor de flota, se crean tareas y se asocian con una parada del vehículo como una forma de modelar la asociación del mundo real entre la tarea y el lugar donde se espera que el vehículo se detenga para que el conductor pueda completar la tarea.

Desde ahí, usted gestiona el progreso de las tareas a lo largo de su ciclo de vida enviando actualizaciones a Fleet Engine para que pueda realizar de la mejor manera el enrutamiento y las actualizaciones de estado durante el 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 la elaboración de informes y análisis sobre el progreso de las tareas tanto para los operadores de flotas como para los usuarios finales. Las actualizaciones de estado son las siguientes:

• En ruta: La enumeración STATE para VehicleStop utiliza 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 para completarse.
• Arrived: La enumeración STATE para VehicleStop utiliza ARRIVED para indicar que el vehículo ha llegado a la parada. Desde la perspectiva de la tarea, significa que cualquier tarea asociada con la interrupción del trabajo activo deja de realizarse.
• Completado: Marcas una parada como completada eliminándola de la lista de paradas del vehículo. Cuando lo haces, Fleet Engine marca automáticamente todas las tareas asociadas como CERRADAS. Para obtener más detalles sobre el cierre de tareas, consulta Finaliza tareas.

Este documento describe cómo actualizar el estado de detención utilizando enfoques del lado del servidor. También puedes hacerlo desde tu app para conductores si le brindas al conductor 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 detenerse

Su sistema debe notificar a Fleet Engine cuando el vehículo comience la navegación hacia la siguiente parada. Esto mejora los cálculos de la ETA y la ruta.

Campos obligatorios para las actualizaciones de paradas

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

Campo	Valor
remainingVehicleJourneySegments	Es una lista de las paradas de vehículos restantes con sus estados marcados como State.NEW.

Ejemplo de ruta hacia la parada

En los siguientes ejemplos, se muestra cómo notificar a Fleet Engine que un vehículo está en camino a su próxima parada, ya sea con la biblioteca de gRPC de Java o con una llamada a UpdateDeliveryVehicle de REST HTTP.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>, donde <token> lo emite tu servidor según los lineamientos que se describen 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

Nota: Este comando reemplaza cualquier remainingVehicleJourneySegments ya establecido en el vehículo de reparto.

 # 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 función experimental, el campo LocationInfo (gRPC o REST) ahora admite el uso de place (gRPC o REST), ya sea junto con LatLng o en lugar de este.

El vehículo llega a la parada

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

Campos obligatorios para las actualizaciones de paradas

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

Campo	Valor
remainingVehicleJourneySegments	Es una lista de las paradas de vehículos restantes con sus estados marcados como State.NEW.

Ejemplo de llegada a la 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 a UpdateDeliveryVehicle a través de HTTP REST. 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>, donde <token> lo emite tu servidor según los lineamientos que se describen 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

Nota: Este comando reemplaza cualquier remainingVehicleJourneySegments ya establecido en el vehículo de reparto.

  # 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 función experimental, el campo LocationInfo (gRPC o REST) ahora admite el uso de place (gRPC o REST), ya sea junto con LatLng o en lugar de este.

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 detención se establezcan en el estado CLOSED.

Campos obligatorios para las actualizaciones de paradas

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

Campo	Valor
remainingVehicleJourneySegments	Es una lista de las paradas de vehículos restantes con sus estados marcados como State.NEW. La primera parada de la lista debe tener su estado 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 a UpdateDeliveryVehicle a través de HTTP REST. 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>, donde <token> lo emite tu servidor según los lineamientos que se describen 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

Nota: Este comando reemplaza cualquier remainingVehicleJourneySegments ya establecido en el vehículo de reparto.

 # 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 función experimental, el campo LocationInfo (gRPC o REST) ahora admite el uso de place (gRPC o REST), ya sea junto con LatLng o en lugar de este.

¿Qué sigue?

• Finalizar tareas