Actualizar el estado de la parada

En este documento, se da por sentado que tienes conocimientos sobre los siguientes temas:

  • [Crea tareas de envío][1]
  • La introducción a las [tareas programadas][3], que abarca la relación entre las tareas, las paradas y los vehículos en detalle.

Como se indica en [Tareas programadas][3] en los conceptos básicos de Fleet Engine, creas tareas y las asocias con una parada de vehículo como una forma de modelar la asociación del mundo 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 durante todo su ciclo de vida enviando actualizaciones a Fleet Engine para que pueda realizar mejor las actualizaciones de ruta 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 se va de la parada. Esto permite generar informes y análisis sobre el progreso de la tarea para los operadores de la flota y los usuarios finales. Estas actualizaciones de estado son las siguientes:

  • En ruta: El enum 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 completará.
  • Llegó: El enum STATE para VehicleStop usa ARRIVED para indicar que el vehículo llegó a la parada. Desde la perspectiva de la tarea, significa que se detiene el trabajo activo en cualquier tarea asociada con la parada.
  • Completada: Para marcar una parada como completada, quítala de la lista de paradas del vehículo. Cuando lo haces, Fleet Engine marca automáticamente todas las tareas asociadas como CLOSED. Para obtener más detalles sobre cómo cerrar tareas, consulta [Finaliza tareas][4].

En este documento, se describe cómo actualizar el estado de la parada con enfoques del servidor. También puedes hacerlo desde la app para conductores si les proporcionas la capacidad de administrar tareas con un dispositivo de confianza. Usa solo un método para evitar las 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 la navegación hacia la siguiente parada. Esto mejora los cálculos de la hora estimada de llegada y de la ruta.

Campos obligatorios para las actualizaciones de paradas

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

CampoValor
remainingVehicleJourneySegments Es la lista de paradas restantes del vehículo 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][5] 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
 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][6] y [Tokens web JSON][6].
  • 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

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

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.

CampoValor
remainingVehicleJourneySegments Es la lista de 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 para Java][5] 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][6] y [Tokens web JSON][6].
  • 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 las actualizaciones de paradas

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

CampoValor
remainingVehicleJourneySegments Es la lista de paradas restantes del vehículo 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 para Java][5] 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][6] y [Tokens web JSON][6].
  • 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

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

¿Qué sigue?

  • [Finaliza las tareas][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