En este documento, se describe cómo actualizar un viaje y administrar su estado, lo que implica usar una máscara de campo para establecer los campos relevantes de un viaje. Se da por sentado que configuraste Fleet Engine como se describe en este sitio y que trabajas con un vehículo asignado a un viaje.
Conceptos básicos de las actualizaciones de viaje
El sistema usa Fleet Engine para actualizar un viaje en las siguientes situaciones:
- Cuando asignas un vehículo a un viaje después de crearlo.
- Cuando cambia el estado del viaje, por ejemplo, cuando el vehículo pasa por puntos de referencia.
- Cuando actualizas los campos de viaje, como la cantidad de pasajeros y el punto de destino.
Para actualizar un viaje, envía una solicitud con gRPC o REST.
Usa las credenciales adecuadas para la cuenta de servicio de tu proyecto, como se describe en Fleet Engine: Roles de la cuenta de servicio.
Actualiza los campos de viaje
Puedes actualizar cualquiera de los campos de viaje que se describen en Campos de viaje en Cómo crear un viaje a un solo destino. Por ejemplo, después de crear un viaje, es una práctica habitual primero encontrar un vehículo y, luego, actualizar el campo vehicle_id del viaje para asociarlo con el vehículo que realizará el viaje.
Usa máscaras de campo
Las máscaras de campo son una forma para que los emisores de la API enumeren los campos que una solicitud debe actualizar o no. El uso de una FieldMask evita trabajos innecesarios y mejora el rendimiento. Fleet Engine usa máscaras de campo para actualizar campos en todos los recursos.
Actualiza el viaje con el ID del vehículo
Debes configurar un viaje con un ID de vehículo para que el motor de flota pueda hacer un seguimiento del vehículo a lo largo de su ruta. En el siguiente ejemplo de código, se muestra cómo actualizar el viaje con un ID de vehículo.
static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// The trip settings to update.
Trip trip = Trip.newBuilder()
.setVehicleId("8241890")
.build();
// The trip update request.
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder() // No need for the header.
.setName(tripName)
.setTrip(trip)
.setUpdateMask(FieldMask.newBuilder().addPaths("vehicle_id"))
.build();
// Error handling.
// If the Fleet Engine has both a trip and vehicle with IDs, and if the
// credentials validate, then the service updates the trip.
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Neither the trip nor vehicle exist.
break;
case PERMISSION_DENIED:
break;
}
return;
}
Administra el estado de los viajes
Especifica el estado de un viaje con uno de los valores de enumeración TripStatus. Cuando cambia el estado de un viaje, por ejemplo, de ENROUTE_TO_PICKUP a ARRIVED_AT_PICKUP, debes actualizarlo en Fleet Engine. El ciclo de vida del viaje siempre comienza con un valor de estado de NEW y termina con un valor de COMPLETE o CANCELED.
Ejemplo de actualización de viaje
A continuación, se muestra cómo actualizar el estado de un viaje consecutivo en Fleet Engine.
static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to be updated.
Trip trip = Trip.newBuilder()
.setTripStatus(TripStatus.ARRIVED_AT_PICKUP)
.build();
// Trip update request
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(FieldMask.newBuilder().addPaths("trip_status"))
.build();
// Error handling.
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // The trip doesn't exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid.
break;
case PERMISSION_DENIED:
break;
}
return;
}
Puedes ver otros ejemplos de cómo actualizar viajes en la sección Otros tipos de viajes.
Cómo controlar los errores de viaje
Cuando actualices o encuentres viajes existentes, es posible que encuentres un caso de error DEADLINE_EXCEEDED, en cuyo caso se desconoce el estado de Fleet Engine.
Para investigar esto, primero vuelve a llamar a CreateTrip con el mismo ID de viaje que intentas actualizar o supervisar. Se debería mostrar un código 201 (CREATED) o 409 (CONFLICT). En el último caso, la solicitud anterior se realizó correctamente antes de DEADLINE_EXCEEDED.
Consulta la lista de errores de red en el SDK para consumidores, ya sea para Android o iOS.