Khi bạn truy xuất dữ liệu chuyến đi, phần phụ trợ của bạn sẽ nhận được các tải trọng JSON nêu chi tiết tiến trình chuyến đi của người lái xe. 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 người lái xe khi họ tiến hành hoặc khi 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 người lái xe bắt đầu chỉ đường, định kỳ dọc theo tuyến đường (mặc định là 60 giây một lần) và khi người lái xe đến đích. Mỗi thông báo JSON chứa dữ liệu chuyến đi liên quan, bao gồm cả toạ độ được điều chỉnh theo đường của người lái xe, quãng đường đã đi và thời gian đến dự kiến (ETA). Vì những thông tin cập nhật này phản ánh tuyến đường đang hoạt động theo thời gian thực của người lái xe, nên có thể chúng khác với các tuyến đường mà hệ thống phụ trợ của bạn đã tính toán trước (xem phần Câu hỏi thường gặp).
Mẫu mã sau đây cho thấy tải trọng dữ liệu chuyến đi khi người lái xe bắt đầu chỉ đường 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 của chuyến đi đang hoạt động
Để xác nhận quá trình bắt đầu thành công và theo dõi tiến trình, hãy đánh giá trường state 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 đi theo chỉ dẫn. |
ENROUTE |
Người lái xe đang chủ động đi theo chỉ dẫn đến điểm đến. 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 trong khi đi theo chỉ dẫn. Nếu có, 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 người lái xe hướng đến đích đế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à phù hợp với chức năng tiêu chuẩn của ứng dụng đó:
- Google Maps: Người lái xe có thể thêm nhiều điểm dừng vào tuyến đường.
- Waze: Người lái xe chỉ có thể thêm một điểm dừng. Nếu người lái xe 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ề quy trình xác thực và khởi động
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. 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 sang ENROUTE, thì thiết bị của người lái xe có thể đang ngăn chặ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. Hãy xác minh những điều sau:
- Người lái xe đã 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.
- Người lái xe không sử dụng Android Auto hoặc Apple CarPlay.
- Người lái xe 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ợ của bạn sẽ nhận được đường đa tuyến của tuyến đường còn lại và tình trạng giao thông theo thời gian thực từ vị trí hiện tại của người lái xe đến điểm đến cuối cùng.
Bạn có thể nhập và xử lý dữ liệu này để hỗ trợ một số tính năng trong các ứng dụng của mình, bao gồm cả những ví dụ sau:
- Bản đồ theo dõi trực tiếp: Kết xuất đường đa tuyến còn lại trên bản đồ web hoặc bản đồ di động mà khách hàng nhìn thấy để cung cấp thông tin về hành trình của người lái xe.
- Nâng cao độ chính xác của thời gian dự kiến đến: Kết hợp đường đa tuyến được gắn với đường và tốc độ theo khoảng thời gian của lưu lượng truy cập để 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 dịch vụ giao hàng.
- Phân tích mức độ tuân thủ quy tắc định tuyến: So sánh hình học tuyến đường còn lại với các tuyến đường dự kiến để đánh giá mức độ tuân thủ của người lái xe (xem phần Câu hỏi thường gặp để biết thông tin chi tiết về lý do khiến tuyến đường theo thời gian thực và tuyến đường được tính toán trước có thể khác nhau).
Navigation Connect trả về thông tin chi tiết còn lại về tuyến đường 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 tải trọng của dữ liệu này 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 sẽ 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 phần Tuỳ chỉnh định dạng nhiều đường.
Đối với tất cả các định dạng đường nhiều đoạn, 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 liên kết danh mục lưu lượng truy cập với 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 lưu lượng truy cập trên đường nhiều đoạn.endPolylinePointIndex: Chỉ mục kết thúc của khoảng thời gian lưu lượng truy cập.speed: Danh mục lưu lượng truy cập cho phân khúc này:NORMAL,SLOWhoặcTRAFFIC_JAM.
Thông tin cập nhật về Google Cloud Pub/Sub
Khi bạn truy xuất dữ liệu chuyến đi bằng Pub/Sub, các bản cập nhật luôn trả về dữ liệu tuyến đường còn lại trong một FeatureCollection GeoJSON hợp nhất trong trường execution.remainingRoute.
Định dạng này kết hợp trực tiếp hình học đường nhiều đoạn với tốc độ giao thông, giúp bạn không cần phải lập chỉ mục theo cách thủ công.
Xem ví dụ về tải trọng Pub/Sub
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 một 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 còn lại của tuyến đường vào thông báo Pub/Sub có thể làm tăng đáng kể kích thước tải trọng (lên đến 13 – 14 KB cho mỗi thông báo). Nếu bạn nhận được thông tin cập nhật thường xuyên, thì khối lượng này có thể làm tăng mức tải xử lý phụ trợ và chi phí sử dụng.
Để tối ưu hoá luồng phát, 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 phần Cấu hình không bắt buộc.
Xử lý các trường hợp đi chệch đường (chỉ Waze)
Nếu bạn đã bật tính năng báo cáo sai lệch so với tuyến đường trong quá trình tạo chuyến đi, thì khi người lái xe đi sai tuyến đường, API sẽ trả về siêu dữ liệu về sai lệch so với tuyến đường. Bạn có thể truy cập vào dữ liệu này theo những cách sau:
- Theo yêu cầu: Gọi phương thức
GetTrip. Máy chủ duy trì trạng thái sai lệch đã biết gần đây nhất. - Theo thời gian thực: Đăng ký Google Cloud Pub/Sub. Dịch vụ này xuất bản thông tin cập nhật về độ lệch bằng cách sử dụng sự kiện
updated_triphiện có trong vòng 5 giây kể từ khi phát hiện.
Đọc tải trọng sai lệch
Đối tượng last_route_deviation cung cấp siêu dữ liệu sau đây để giúp bạn phân tích sự kiện.
| Trường | Loại | Mô tả |
|---|---|---|
location |
LatLng |
Toạ độ vĩ độ và kinh độ tại vị trí mà thiết bị khách ghi nhận độ lệch. |
source |
TriggerSource |
Lý do có sự khác biệt. Sử dụng thông tin này để xác định xem người lái xe có thực hiện hành động không mong muốn hay làm theo hướng dẫn của hệ thống hay không:
|
client_timestamp |
Timestamp |
Thời gian thiết bị khách phát hiện thấy độ lệch. |
server_timestamp |
Timestamp |
Thời gian máy chủ xử lý thông tin cập nhật về độ lệch. |
Xử lý các trạng thái kết thúc chuyến đi
Khi người lái xe đến điểm đến hoặc ngừng điều hướng, tải trọng sẽ trả về một trong các trạng thái kết thúc sau đâ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ạ độ chính xác, hãy cân nhắc cung cấp chỉ đường đi bộ trong ứng dụng của bạn. |
SUSPENDED |
Người lái xe đã thoát khỏi chế độ chỉ đường từng chặng theo cách thủ công trước khi đến đích. Vì Google Maps hoặc Waze không tự động đưa người lái xe quay lại ứng dụng của bạn khi họ thoát phiên sớm, nên người lái xe phải nhấn 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. Điều 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. Người lái xe có thể vẫn đang đi theo chỉ dẫn, nhưng bạn sẽ không nhận được thông tin cập nhật. | Quay lại chế độ theo dõi trạng thái thủ công trong ứng dụng. |
CLIENT_ERROR |
Trạng thái này xuất hiện vì một trong những lý do sau:
|
Quay lại chế độ theo dõi trạng thái thủ công trong ứng dụng. |