Xử lý dữ liệu chuyến đi

Khi bạn truy xuất dữ liệu chuyến đi, phần phụ trợ của bạn sẽ nhận được tải trọng JSON nêu chi tiết tiến trình chuyến đi của tài xế. 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 chuyến đi hiện tại để xác định bước tiếp theo cho tài xế 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 máy chủ Navigation Connect khi người lái xe bắt đầu đi theo chỉ dẫn, đị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 có liên quan, bao gồm cả toạ độ được điều chỉnh theo đường đi của tài xế, 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 tài xế, nên có thể khác với tuyến đường được tính toán trước bằng phần phụ trợ của bạn (xem Câu hỏi thường gặp).

Mã mẫu sau đây cho thấy tải trọng dữ liệu chuyến đi khi tài xế bắt đầu đi theo chỉ dẫ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 việc 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 Tài xế đang đ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 của họ 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 tài xế đến điểm đến ban đầu. Các chỉ số như thời gian đến dự kiến (ETA), quãng đường và thời gian sẽ tăng lên để bao gồm cả các điểm dừng được thêm vào.

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: 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 đi theo chỉ dẫn 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 của phần phụ trợ để hỗ trợ tính năng này.

Khắc phục sự cố 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 thông 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 thành ENROUTE, thì có thể thiết bị của tài xế đang ngăn chặn việc 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 thông tin 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.
  • 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

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 hình nhiều đường 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 tài xế đến điểm đến cuối cùng của họ. Tài xế cần có Waze phiên bản 5.20.0.2 trở lên trên Android, 5.20.0.1 trở lên trên iOS hoặc Google Maps cho Android phiên bản 26.27 trở lên.

Bạn có thể nhập và xử lý dữ liệu này để hỗ trợ một số tính năng trong ứng dụng, bao gồm các ví dụ sau:

  • Cung cấp bản đồ theo dõi trực tiếp: Hiển thị hình nhiều đường của tuyến đường còn lại trên bản đồ web hoặc thiết bị di động mà khách hàng nhìn thấy để cung cấp thông tin về hành trình của tài xế.
  • Nâng cao độ chính xác của thời gian đến dự kiến: Kết hợp hình nhiều đường được bám vào đường và tốc độ theo khoảng thời gian của tình trạng giao thông để cải thiện hoạt động hậu cần nội bộ hoặc thông tin dự đoán về thời gian giao hàng.
  • Phân tích mức độ tuân thủ tuyến đường: So sánh hình học tuyến đường còn lại với tuyến đường điều phối dự kiến để đánh giá mức độ tuân thủ của tài xế (xem phần Câu hỏi thường gặp để biết thông tin chi tiết về lý do 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 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 tải trọng định dạng và cấu trúc 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 hình nhiều đường 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 hình nhiều đường.

Đối với tất cả định dạng hình nhiều đường, Navigation Connect sẽ trả về thông tin giao thông 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 hình nhiều đường bằng cách sử dụ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 hình nhiều đường.
  • endPolylinePointIndex: Chỉ mục kết thúc của khoảng 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, SLOW hoặc TRAFFIC_JAM.

Nội dung 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, thông tin cập nhật luôn trả về dữ liệu tuyến đường còn lại trong một GeoJSON FeatureCollection 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 của hình nhiều đường với tốc độ giao thông, loại bỏ nhu cầu á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 (lên đến 13-14 KB mỗi thông báo). Nếu bạn nhận được thông tin cập nhật với tần suất cao, thì lượng thông tin 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 nặng. Để 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ý trường hợp lệch khỏi tuyến đường (chỉ dành cho Waze)

Tài xế cần có Waze phiên bản 5.22 trở lên.

Nếu bạn đã bật tính năng báo cáo việc lệch khỏi tuyến đường trong quá trình tạo chuyến đi, thì khi tài xế đi lệch khỏi tuyến đường, API sẽ trả về siêu dữ liệu về việc lệch khỏ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 gần đây nhất mà hệ thống biết.
  • Theo thời gian thực: Đăng ký Google Cloud Pub/Sub. Dịch vụ này sẽ 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_trip hiện có trong vòng 5 giây kể từ khi phát hiện.

Đọc tải trọng độ 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 độ nơi thiết bị khách ghi lại độ lệch.
source TriggerSource Lý do dẫn đến độ lệch. 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 ngoài dự kiến hay làm theo hướng dẫn của hệ thống hay không:
  • DRIVER_INITIATED_REROUTE: Tài xế đã chủ động lựa chọn (ví dụ: rẽ nhầm hoặc chọn một tuyến đường mới theo cách thủ công).
  • SYSTEM_INITIATED_REROUTE: Ứng dụng chỉ đường đã tính toán một tuyến đường mới (ví dụ: do tình trạng giao thông thay đổi hoặc đường bị đóng).
client_timestamp Timestamp Thời điểm thiết bị của khách hàng 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ý trạng thái kết thúc chuyến đi

Khi tài xế đến điểm đến hoặc ngừng đi theo chỉ dẫn, 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 phù 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. Xem remainingDistanceMeters. Nếu tài xế đỗ xe gần đó nhưng không đúng toạ độ, hãy cân nhắc việc cung cấp đườ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 khỏi một phiên sớm, 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 quãng đường, 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 Một 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 thể tính toán 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. 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:
  • Tài xế thu hồi sự đồng ý.
  • Tài xế sử dụng một nền tảng không được hỗ trợ, chẳng hạn như Android Auto hoặc Apple CarPlay.
  • Ứng dụng của bạn sử dụng lại mã thông báo chuyến đi cho nhiều chuyến đi riêng biệt. Ví dụ: Navigation Connect từ chối các yêu cầu thay đổi điểm đến của chuyến đi hoặc cập nhật chuyến đi đã hoàn tất.
  • Tài xế đang ở Hoa Kỳ tại bất kỳ thời điểm nào trong chuyến đi, nhưng ứng dụng của bạn không bật tính năng chia sẻ dữ liệu ở Hoa Kỳ khi bạn xác minh ứng dụng trong quá trình thiết lập.
Quay lại chế độ theo dõi trạng thái thủ công trong ứng dụng.