Khi bạn truy xuất dữ liệu chuyến đi, phần phụ trợ sẽ nhận được tải trọng JSON trình bày chi tiết tiến trình chuyến đi của tài xế. Hãy phân tích cú pháp các tải trọng này để theo dõi chuyến đi, cập nhật hệ thống điều phối và diễn giải trạng thái hiện tại của chuyến đi để xác định bước tiếp theo cho tài xế khi họ di chuyển hoặc khi một chuyến đi kết thúc.
Đọc tải trọng dữ liệu
Google Maps hoặc Waze sẽ gửi tải trọng dữ liệu chuyến đi đến các máy chủ Navigation Connect khi tài xế bắt đầu di chuyển, định kỳ dọc theo tuyến đường (theo mặc định là 60 giây một lần) và khi tài xế đến điểm đến. Mỗi thông báo JSON chứa dữ liệu chuyến đi có liên quan, bao gồm cả toạ độ được gắn vào đường đi của tài xế, quãng đường đã đi và thời gian đến dự kiến (ETA).
Mẫu mã sau đây cho thấy tải trọng dữ liệu chuyến đi khi tài xế bắt đầu di chuyển cho một chuyến đi từ King's Cross đến Central St. Giles.
{
"name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
"state": "ENROUTE",
"execution": {
"origin": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
}
},
"destination": {
"point": {
"latitude": 51.515598,
"longitude": -0.1277623
}
},
"location": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
},
"sourceTime": "2025-05-30T12:37:26Z",
"serverTime": "2025-05-30T12:37:26.221069Z"
},
"traveledDuration": "0s",
"remainingDuration": "990s",
"traveledDistanceMeters": 0,
"remainingDistanceMeters": 2879,
"stopAddedInRoute": false
}
}
Theo dõi trạng thái chuyến đi đang hoạt động
Để xác nhận rằng chuyến đi đã bắt đầu thành công và theo dõi tiến trình, hãy đánh giá trường trạng thái trong mọi tải trọng.
| Trạng thái | Mô tả |
|---|---|
NEW |
Chuyến đi đã được tạo, nhưng tài xế chưa bắt đầu di chuyển. |
ENROUTE |
Tài xế đang tích cực di chuyển đến điểm đến. Hãy sử dụng trạng thái này để xác nhận rằng chuyến đi đã được xác thực và bắt đầu thành công. |
Xử lý các điểm dừng đã thêm
Tài xế có thể thêm điểm dừng vào tuyến đường của họ trong khi di chuyển. Nếu họ làm như vậy, Navigation Connect sẽ đặt trường execution.stopAddedInRoute thành true trong tải trọng dữ liệu JSON. Navigation Connect API tiếp tục theo dõi tài xế hướng đến điểm đến ban đầu. Các chỉ số như thời gian đến dự kiến (ETA), khoảng cách và thời lượng sẽ tăng lên để bao gồm cả các điểm dừng đã thêm.
Hành vi thêm điểm dừng phụ thuộc vào ứng dụng chỉ đường và khớp với chức năng tiêu chuẩn của ứng dụng đó:
- Google Maps: Tài xế có thể thêm nhiều điểm dừng vào tuyến đường của họ.
- Waze: Tài xế chỉ có thể thêm một điểm dừng. Nếu tài xế cố gắng thêm một điểm dừng khác, Waze sẽ nhắc họ bắt đầu một phiên chỉ đường mới thay vì thêm điểm dừng vào tuyến đường hiện tại.
Bạn không cần điều chỉnh dữ liệu đầu vào phụ trợ để hỗ trợ tính năng này.
Khắc phục sự cố về xác thực và bắt đầu
Nếu bạn không nhận được trạng thái ENROUTE, thì có thể đã xảy ra lỗi xác thực. Các nguyên nhân phổ biến bao gồm tham số API bị sai chính tả hoặc mã thông báo chuyến đi đã hết hạn. Hãy kiểm tra thời gian hết hạn của mã thông báo trong phản hồi CreateTrip ban đầu.
Nếu trạng thái không thay đổi từ NEW thành ENROUTE, thì thiết bị của tài xế có thể đang ngăn quá trình xác thực. Navigation Connect không gửi thông báo lỗi cho những trường hợp này. Xác minh những điều sau:
- Tài xế đã cài đặt Waze phiên bản 5.15.5 trở lên hoặc Google Maps phiên bản 26.14 trở lên.
- Tài xế không sử dụng Android Auto hoặc Apple CarPlay.
- Tài xế có kết nối Internet đang hoạt động.
Xử lý dữ liệu tuyến đường còn lại (chỉ Waze)
Nếu bạn đã bật tính năng báo cáo tuyến đường còn lại trong quá trình tạo chuyến đi, thì phần phụ trợ sẽ nhận được đường nhiều đoạn của tuyến đường đang hoạt động và điều kiện giao thông theo thời gian thực từ vị trí hiện tại của tài xế đến điểm đến cuối cùng của họ.
Bạn có thể thu thập và xử lý dữ liệu này để cung cấp một số tính năng trong ứng dụng của mình, bao gồm các ví dụ sau:
- Bản đồ theo dõi trực tiếp mạnh mẽ: Kết xuất hình nhiều đường của tuyến đường còn lại trên một trang web hoặc bản đồ dành cho thiết bị di động dành cho khách hàng để cung cấp khả năng hiển thị về hành trình của tài xế.
- Nâng cao độ chính xác của ETA: Kết hợp đường nhiều đoạn được gắn vào đường đi và tốc độ theo khoảng thời gian giao thông để cải thiện hoạt động hậu cần nội bộ hoặc dự đoán thời gian đến của hoạt động giao hàng.
- Phân tích mức độ tuân thủ quy trình định tuyến: So sánh hình học của tuyến đường còn lại với các tuyến đường điều phối dự kiến để đánh giá mức độ tuân thủ của tài xế.
Navigation Connect trả về thông tin chi tiết về tuyến đường còn lại trong trường execution.remainingRoute, cho dù bạn gửi yêu cầu GetTrip hay nhận thông tin cập nhật dựa trên sự kiện bằng Google Cloud Pub/Sub. Tuy nhiên, cách định dạng và cấu trúc dữ liệu này của tải trọng phụ thuộc vào phương thức truy xuất mà bạn sử dụng.
Phương thức GetTrip
Khi bạn gọi phương thức GetTrip, định dạng phản hồi cho đường nhiều đoạn phụ thuộc vào tham số routePolylineFormat mà bạn đã chỉ định trong yêu cầu. Để biết thêm
thông tin, hãy xem bài viết Tuỳ chỉnh định dạng đường nhiều đoạn.
Đối với tất cả các định dạng hình nhiều đường, Navigation Connect sẽ trả về lưu lượng truy cập dưới dạng một danh sách riêng biệt gồm các đối tượng SpeedReadingInterval trong trường execution.remainingRoute.trafficInformation. Các đối tượng này ánh xạ các danh mục lưu lượng truy cập đến chỉ mục đường nhiều đoạn bằng các giá trị sau:
startPolylinePointIndex: Chỉ mục bắt đầu của khoảng thời gian giao thông trên đường nhiều đoạn.endPolylinePointIndex: Chỉ mục kết thúc của khoảng thời gian giao thông.speed: Danh mục lưu lượng truy cập cho phân đoạn này:NORMAL,SLOWhoặcTRAFFIC_JAM.
Thông tin cập nhật của Google Cloud Pub/Sub
Khi bạn truy xuất dữ liệu chuyến đi bằng Pub/Sub,
thông tin cập nhật sẽ luôn trả về dữ liệu tuyến đường còn lại trong một GeoJSON hợp nhất
FeatureCollection trong trường execution.remainingRoute.
Định dạng này kết hợp trực tiếp hình học của đường nhiều đoạn với tốc độ giao thông, giúp bạn không cần phải ánh xạ chỉ mục theo cách thủ công.
Xem tải trọng Pub/Sub mẫu
Mã mẫu sau đây cho thấy cấu trúc GeoJSON được trả về trong trường execution.remainingRoute trong đối tượng updatedTrip của thông báo Pub/Sub:
{ "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.3934, 37.7955], [-122.4010, 37.7980] ] }, "properties": { "speed": "SLOW" } }, { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.4010, 37.7980], [-122.4058, 37.8025], [-122.4187, 37.8021] ] }, "properties": { "speed": "NORMAL" } } ] }
Tối ưu hoá kích thước tải trọng
Vì mảng toạ độ có kích thước lớn, nên việc đưa dữ liệu tuyến đường còn lại vào thông báo Pub/Sub có thể làm tăng đáng kể kích thước tải trọng (tối đa 13–14 KB mỗi thông báo). Nếu bạn nhận được thông tin cập nhật có tần suất cao, thì khối lượng này có thể làm tăng tải xử lý phụ trợ và chi phí sử dụng.
Để tối ưu hoá luồng, hãy sử dụng tham số pubsubFieldMask trong đối tượng TripConfig trong quá trình tạo chuyến đi để loại trừ các trường có kích thước lớn. Để biết
thông tin chi tiết, hãy xem Cấu hình không bắt buộc.
Xử lý trạng thái kết thúc chuyến đi
Khi tài xế đến điểm đến hoặc ngừng di chuyển, tải trọng sẽ trả về một trong các trạng thái kết thúc sau. Hãy sử dụng các trạng thái này để kích hoạt các bước tiếp theo thích hợp trong ứng dụng của bạn.
| Trạng thái | Mô tả | Hành động được đề xuất |
|---|---|---|
ARRIVED |
Tài xế đã đến điểm đến. | Kiểm tra remainingDistanceMeters. Nếu tài xế đỗ xe
ở gần nhưng không đúng toạ độ, hãy cân nhắc cung cấp chỉ đường đi bộ
trong ứng dụng của bạn. |
SUSPENDED |
Tài xế đã thoát khỏi chế độ chỉ đường từng chặng theo cách thủ công trước khi đến điểm đến. Vì Google Maps hoặc Waze không tự động đưa tài xế trở lại ứng dụng của bạn khi họ thoát sớm khỏi một phiên, nên tài xế phải nhấn vào nút quay lại theo cách thủ công. |
Để giúp tài xế hoàn thành hành trình, hãy so sánh
execution.location với điểm đến. Nếu vẫn còn khoảng cách, hãy cung cấp một nút hoặc đường liên kết để tiếp tục chuyến đi hoặc chuyển sang
chế độ đi bộ. |
FAILED |
Đã xảy ra lỗi kỹ thuật làm gián đoạn kết nối. Lỗi này xảy ra nếu ứng dụng không tính toán được tuyến đường hoặc cảnh báo an toàn xuất hiện. Tài xế có thể vẫn đang di chuyển, nhưng bạn sẽ không nhận được thông tin cập nhật. | Chuyển về chế độ theo dõi trạng thái thủ công trong ứng dụng của bạn. |
CLIENT_ERROR |
Trạng thái này xuất hiện vì một trong những lý do sau:
|
Chuyển về chế độ theo dõi trạng thái thủ công trong ứng dụng của bạn. |