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

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, quãng đường đã đi và thời gian đến dự kiến (ETA) của tài xế. Vì những thông tin cập nhật này phản ánh tuyến đường theo thời gian thực mà tài xế đang di chuyển, nên chúng có thể khác với các tuyến đường mà phần phụ trợ của bạn đã tính toán trước (xem 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 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 di chuyể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ố 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 còn lại của tuyến đường (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 đa tuyến còn lại của tuyến đường 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ọ.

Bạn có thể thu thập và xử lý dữ liệu này để cung cấp cho một số tính năng trong ứng dụng của mình, bao gồm các ví dụ sau:

  • Cung cấp bản đồ theo dõi trực tiếp: Kết xuất đường đa tuyến còn lại của tuyến đường trên một bản đồ trên web hoặc thiết bị di động dành cho khách hàng để 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 ETA: Kết hợp đường đa tuyế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 chuyến 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ế (xem Câu hỏi thường gặp để biết thông tin chi tiết về lý do các tuyến đường theo thời gian thực và các tuyến đường được tính toán trước có thể khác nhau).

Navigation Connect sẽ trả về thông tin chi tiết còn lại của 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 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 đường đa tuyế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 Tuỳ chỉnh định dạng đường đa tuyến.

Đối với tất cả các định dạng đường đa tuyế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 ánh xạ các danh mục lưu lượng truy cập đến chỉ mục đường đa tuyế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 đa tuyế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, SLOW hoặc TRAFFIC_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 còn lại của tuyến đường 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 đa tuyế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 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 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 (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ý của phần 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 phải ở 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 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ế quay 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 xuất hiện cảnh báo an toà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ề tính năng 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 do 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 một chuyến đi có điểm đến khác.
  • Tài xế ở 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.
 Chuyển về tính năng theo dõi trạng thái thủ công trong ứng dụng của bạn.