Tài liệu này mô tả cách cập nhật một chuyến đi và quản lý trạng thái của chuyến đi đó, bao gồm cả việc sử dụng mặt nạ trường để đặt các trường có liên quan cho một chuyến đi. Hướng dẫn này giả định rằng bạn đã thiết lập Fleet Engine như mô tả trên trang web này và đang làm việc với một chiếc xe được chỉ định cho một chuyến đi.
Kiến thức cơ bản về thông tin cập nhật chuyến đi
Hệ thống của bạn sử dụng Fleet Engine để cập nhật chuyến đi trong các trường hợp sau:
- Khi chỉ định một chiếc xe cho một chuyến đi sau khi chuyến đi đó được tạo.
- Khi trạng thái của chuyến đi thay đổi; ví dụ: khi xe đi qua các điểm tham chiếu.
- Khi bạn cập nhật các trường của chuyến đi, chẳng hạn như số lượng hành khách và điểm trả khách.
Để cập nhật một chuyến đi, hãy gửi yêu cầu bằng cách sử dụng gRPC và REST.
Sử dụng thông tin đăng nhập phù hợp cho tài khoản dịch vụ của dự án như mô tả trong phần Fleet Engine: Vai trò của tài khoản dịch vụ.
Cập nhật các trường chuyến đi
Bạn có thể cập nhật bất kỳ trường nào của chuyến đi được mô tả trong phần Trường chuyến đi trong bài viết Tạo chuyến đi đến một điểm đến. Ví dụ: sau khi tạo một chuyến đi, bạn thường tìm một chiếc xe trước rồi cập nhật trường vehicle_id của chuyến đi để liên kết chuyến đi đó với chiếc xe sẽ thực hiện chuyến đi.
Sử dụng mặt nạ trường
Mặt nạ trường là một cách để người gọi API liệt kê các trường mà một yêu cầu cần hoặc nên cập nhật. Việc sử dụng FieldMask giúp tránh những việc không cần thiết và cải thiện hiệu suất. Fleet Engine sử dụng mặt nạ trường để cập nhật các trường trên tất cả các tài nguyên.
Cập nhật chuyến đi bằng mã nhận dạng xe
Bạn phải định cấu hình một chuyến đi có mã nhận dạng xe để Fleet Engine có thể theo dõi xe trên tuyến đường. Mẫu mã sau đây minh hoạ cách cập nhật chuyến đi bằng mã nhận dạng xe.
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;
}
Quản lý trạng thái chuyến đi
Bạn chỉ định trạng thái của một chuyến đi bằng một trong các giá trị liệt kê TripStatus. Khi trạng thái của một chuyến đi thay đổi (ví dụ: từ ENROUTE_TO_PICKUP thành ARRIVED_AT_PICKUP), bạn sẽ cập nhật trạng thái chuyến đi trong Fleet Engine. Vòng đời của chuyến đi luôn bắt đầu bằng giá trị trạng thái NEW và kết thúc bằng giá trị COMPLETE hoặc CANCELED.
Ví dụ về thông tin cập nhật chuyến đi
Sau đây minh hoạ cách cập nhật trạng thái chuyến đi cho một chuyến đi liên tiếp trong 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;
}
Bạn có thể xem các ví dụ khác về cách cập nhật chuyến đi trong phần Các loại chuyến đi khác.
Xử lý lỗi chuyến đi
Khi cập nhật hoặc tìm chuyến đi hiện có, bạn có thể gặp phải trường hợp lỗi DEADLINE_EXCEEDED. Trong trường hợp này, trạng thái của Fleet Engine là không xác định.
Để điều tra vấn đề này, trước tiên, hãy gọi lại cho CreateTrip bằng mã chuyến đi mà bạn đang cố gắng cập nhật hoặc theo dõi. Thao tác này sẽ trả về mã 201 (ĐÃ TẠO) hoặc 409 (XUNG ĐỘT). Trong trường hợp thứ hai, yêu cầu trước đó đã thành công trước DEADLINE_EXCEEDED.
Xem danh sách lỗi mạng trong Consumer SDK, cho Android hoặc iOS.