This document describes how to update a trip and manage its state, which involves using a field mask to set relevant fields for a trip. It assumes you have set up Fleet Engine as described in this site and are working with a vehicle assigned to a trip.
Trip update basics
Your system uses Fleet Engine to update a trip in the following situations:
- When assigning a vehicle to a trip after it's created.
- When the status of the trip changes; for example, when the vehicle passes through waypoints.
- When you update trip fields, such as the number of passengers and the drop-off point.
To update a trip, send a request using either gRPC and REST.
Use the appropriate credentials for the service account of your project as described in Fleet Engine: Service account roles .
Update trip fields
You can update any of the trip fields described in Trip fields
in Create
a single destination trip. For example, after you create a trip, it's a common
practice to first find a vehicle and then update the trip vehicle_id
field to
associate it with the vehicle that will carry out the trip.
Use field masks
Field masks are a way for API callers to list the fields that a request should or update. Using a FieldMask avoids unnecessary works and improves performance. Fleet Engine uses field masks for updating fields across all resources.
Update the trip with the vehicle ID
You must configure a trip with a vehicle ID so that the Fleet Engine can track the vehicle along its route. The following code sample demonstrates how to update the trip with a vehicle ID.
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
;
}
Manage trip state for trips
You specify the state of a trip using one of the TripStatus
enumeration
values. When a trip's state changes; for example from ENROUTE_TO_PICKUP
to ARRIVED_AT_PICKUP
, you update the trip state in Fleet Engine. The trip
lifecycle always begins with a state value of NEW
, and ends with a value of
either COMPLETE
or CANCELED
.
Example trip update
The following demonstrates how to update the trip state for a back-to-back trip in 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
;
}
You can see other examples of how to update trips in the Other trip typessection.
Handle trip errors
When updating or finding existing trips, you might encounter a case of a DEADLINE_EXCEEDED
error, in which case the state of Fleet Engine is unknown.
To investigate this, first call CreateTrip
again using the same trip ID you
are trying to update or monitor. This should return either a 201 (CREATED) or
409 (CONFLICT). In the latter case, the previous request succeeded before DEADLINE_EXCEEDED
.
See the list of network errors in the Consumer SDK, either for Android or iOS .
