Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Tạo tuyến đường và thời gian dự kiến đến cho xe có kích thước lớn

Đối tượng của hướng dẫn này: Hãy đọc hướng dẫn này nếu bạn là nhà phát triển đang xây dựng các dịch vụ lập kế hoạch và thực hiện chuyến đi bằng xe tải hoặc các loại xe lớn khác. Các trường hợp sử dụng liên quan bao gồm tính toán thời gian và khoảng cách di chuyển, tính toán thời gian đến dự kiến hoặc tạo các tuyến đường mà ứng dụng chỉ đường sẽ sử dụng.

Nội dung hướng dẫn này đề cập đến: Hướng dẫn này đề cập đến cách sử dụng Routes API với tính năng Định tuyến cho xe cỡ lớn để yêu cầu các tuyến đường, khoảng cách di chuyển, thời gian di chuyển dự kiến và thời gian đến dự kiến có tính đến các thuộc tính cụ thể của xe cỡ lớn, chẳng hạn như xe tải thương mại hoặc xe buýt chở khách.

Để biết thông tin về cách thực hiện các phép tính ở cấp đội xe cho xe có kích thước lớn bằng Route Optimization API, hãy xem Tài liệu về tính năng định tuyến cho xe tải của Route Optimization.

Kiến thức bạn sẽ học được

Bạn sẽ tìm hiểu cách thực hiện những việc sau:

Tạo một yêu cầu định tuyến hợp lệ.
Chỉ định thông tin về xe cho xe thực tế của bạn, sử dụng kích thước, trọng lượng và các đặc điểm khác.
Diễn giải phản hồi, bao gồm cả mã thông báo tuyến đường và cờ an toàn khi di chuyển.

Điều kiện tiên quyết

Bạn phải tạo dự án trên Google Cloud và bật Routes API.
Bạn phải cung cấp dự án cho tính năng Định tuyến cho xe cỡ lớn. Tính năng định tuyến cho xe lớn chỉ được cung cấp cho một số ít khách hàng, hãy liên hệ với chúng tôi để yêu cầu cấp quyền truy cập

Các điểm hạn chế

Trước khi bắt đầu, bạn phải lưu ý những hạn chế và yêu cầu sau.

Phạm vi cung cấp theo khu vực địa lý: Tính năng định tuyến cho xe lớn được cung cấp ở 48 tiểu bang liền kề của Hoa Kỳ (Cung cấp công khai) và Nhật Bản (Thử nghiệm). Dịch vụ này không có ở Alaska, Hawaii hoặc các lãnh thổ thuộc Hoa Kỳ.
Thông tin tư vấn và an toàn cho người lái xe. Người lái xe không được chỉ dựa vào các tuyến đường do API này trả về để đảm bảo an toàn hoặc hợp pháp. Chúng tôi không đảm bảo rằng các tuyến đường phù hợp với xe và việc đi theo các tuyến đường này có thể khiến người lái xe gặp phải các mối nguy hiểm như cầu thấp hoặc đường cấm xe cỡ lớn.
Các tuyến đường được tính toán theo khả năng. Trong một số trường hợp, API không thể tìm thấy một tuyến đường hoàn toàn tuân thủ các quy định hạn chế đi lại. Thay vào đó, API này trả về một tuyến đường "cố gắng hết sức" có thể vẫn đi qua các khu vực bị hạn chế. Phản hồi của Routes API sẽ gắn cờ rõ ràng những tuyến đường này trong trường routeRestrictionsPartiallyIgnored. Trong những trường hợp này, hãy lên kế hoạch cẩn thận cho tuyến đường của bạn, tốt nhất là sử dụng dữ liệu từ nguồn khác. Không sử dụng tuyến đường bị gắn cờ làm nguồn thông tin đáng tin cậy duy nhất để lập kế hoạch hoặc chỉ đường.
Các tính năng không được hỗ trợ: Tính năng định tuyến cho xe lớn không hỗ trợ những tính năng sau:
- Giá phí cầu đường cho xe tải
- Giới hạn tốc độ
- Định tuyến cho vật liệu nguy hiểm phóng xạ
Giới hạn sử dụng: Tất cả các yêu cầu đều phải tuân theo giới hạn tiêu chuẩn về số lượng truy vấn mỗi giây (QPS).

Tạo yêu cầu về tuyến đường cho xe tải

Để nhận được tuyến đường cho xe tải, bạn gửi một yêu cầu HTTPS đến một điểm cuối Routes API với các tham số cụ thể mô tả xe của bạn. Các khái niệm trong phần này áp dụng cho cả yêu cầu về tuyến đường đơn lẻ và ma trận tuyến đường.

Điểm cuối

Bạn có thể sử dụng 2 điểm cuối để định tuyến cho xe tải:

computeRoutes: Tính toán một tuyến đường duy nhất giữa một điểm xuất phát và một điểm đến.
computeRouteMatrix: Tính toán khoảng cách và thời lượng cho một ma trận gồm các điểm xuất phát và điểm đến, nhưng không trả về một đường đa tuyến của tuyến đường.

Các tham số yêu cầu chính

Trong phần nội dung yêu cầu, bạn phải thêm các tham số sau để bật tính năng định tuyến cho xe tải:

travelMode: Đặt giá trị này thành TRUCK.
routingPreference: Đặt giá trị này thành TRAFFIC_AWARE_OPTIMAL.
routeModifiers: Đối tượng này chứa đối tượng vehicleInfo nơi bạn xác định các thuộc tính của xe. Đối tượng vehicleInfo được mô tả chi tiết bên dưới.

Chỉ định các thuộc tính của xe

Để gửi yêu cầu, bạn phải cung cấp một nội dung yêu cầu có đối tượng vehicleInfo mô tả xe của bạn. Hãy coi thông tin này là một quy cách phù hợp với các thông tin chi tiết về chiếc xe thực tế của bạn. Dịch vụ này yêu cầu những thông tin chi tiết này để trả về các tuyến đường có tính đến những hạn chế về đường dựa trên các thuộc tính của xe.

Số đo của xe

Cung cấp trọng lượng xe (tính bằng ki-lô-gam) và kích thước xe (tính bằng milimet), như được biểu thị bằng tên trường. Ví dụ: bạn phải cung cấp tổng chiều cao bằng milimet (totalHeightMm). Vì kích thước xe tải thường được biểu thị bằng feet hoặc mét, nên bạn có thể phải chuyển đổi đơn vị.

Chuyển đổi từ hệ đo lường Anh sang hệ đo lường mét

Khi chuyển đổi từ đơn vị đo lường của Anh, hãy luôn cân nhắc kích thước cụ thể của xe cùng với giới hạn kích thước tiêu chuẩn của đường và hầm chui. Điều này có thể đặc biệt quan trọng đối với các giá trị phân số. Tuỳ thuộc vào kích thước của xe thực tế, việc làm tròn giá trị thập phân có thể dẫn đến việc định tuyến quá hạn chế cho xe.

Ví dụ:

Chiều rộng: Nhiều rơ-moóc ở Hoa Kỳ có chiều rộng 8' 6" (tương đương 2.590,8 mm). Làm tròn lên 2.591 mm sẽ cho biết xe có chiều cao lớn hơn 8' 6", tức là xe quá khổ trên đường ở Hoa Kỳ. Sau đó, điều này sẽ dẫn đến một tuyến đường được tính toán theo các ràng buộc khác biệt một cách có ý nghĩa so với dự định.
Chiều cao: Tuyến đường dẫn xuống dưới một cây cầu cao 3,35 m sẽ không phù hợp với xe đầu kéo thông thường có chiều cao 4,1 m. Tuy nhiên, các xe tải thùng nhỏ có chiều dài khoảng 10 feet có thể đi qua hầm chui này. Do đó, bạn cần phải chỉ định chính xác các thuộc tính xe.

Sơ đồ minh hoạ kích thước của một chiếc xe tải so với kích thước của một hầm chui

Sau đây là một đoạn mã cho thấy ví dụ về đối tượng vehicleInfo:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

`vehicleInfo` trường đối tượng

Bảng sau đây cho thấy tất cả các định nghĩa về xe và tải trọng mà bạn có thể gửi bằng yêu cầu.

Trường	Nội dung mô tả	Ghi chú / Giá trị
`totalHeightMm`	Chiều cao tối đa của xe.	Tính bằng milimet, được làm tròn xuống. Hãy xem bài viết Chuyển đổi từ hệ đo lường Anh sang hệ đo lường quốc tế để biết thêm thông tin về việc làm tròn.
`totalWidthMm`	Chiều rộng tối đa của xe.	Tính bằng milimet, được làm tròn xuống.
`totalLengthMm`	Tổng chiều dài kết hợp của xe và mọi rơ moóc.	Tính bằng milimet, được làm tròn xuống.
`totalWeightKg`	Tổng trọng lượng xe (bao gồm cả rơ moóc và hàng hoá).	Tính bằng kilôgam, làm tròn xuống.
`totalAxleCount`	Tổng số trục trên xe và mọi rơ moóc.	Chính xác.
`trailerInfo` (Không bắt buộc)	Một mảng gồm các đối tượng, mỗi đối tượng cho một đoạn giới thiệu.	Bỏ qua đối với xe không có rơ moóc, chẳng hạn như xe tải thùng.
`hazardousGoodsTypes` (Không bắt buộc)	Một mảng chỉ định mọi vật liệu nguy hiểm trên máy bay.	CHẤT NỔ, KHÍ, DỄ CHÁY, DỄ BẮT LỬA, HỮU CƠ, ĐỘC HẠI, ĂN MÒN, NGUY CƠ HÍT PHẢI, NGUY CƠ ĐỐI VỚI MÔI TRƯỜNG, KHÁC

Sử dụng mặt nạ cho trường

Để có kết quả tốt nhất, hãy thêm tiêu đề X-Goog-FieldMask vào yêu cầu của bạn để chỉ định chính xác những trường mà bạn muốn trong phản hồi. Mặt nạ trường giúp giảm độ trễ và đảm bảo bạn nhận được các trường tư vấn quan trọng. Ít nhất, hãy luôn thêm routes.travelAdvisory.routeRestrictionsPartiallyIgnored vào mặt nạ trường, vì điều này cho biết tuyến đường có một hoặc nhiều quy định hạn chế áp dụng cho xe của bạn hay không.

Để biết thêm thông tin chi tiết về FieldMasks với Routes API, hãy xem bài viết này.

Đường thu phí

Để ưu tiên các tuyến đường không thu phí, hãy chỉ định avoidTolls trong thuộc tính routeModifiers của một yêu cầu. Để biết thêm thông tin về các đối tượng sửa đổi tuyến đường, hãy xem bài viết Chỉ định các đối tượng trên tuyến đường cần tránh.

Việc chỉ định avoidTolls không đảm bảo rằng các tuyến đường miễn phí sẽ xuất hiện trong phản hồi. Trong một số trường hợp, bạn phải sử dụng đường có thu phí để di chuyển giữa điểm xuất phát và điểm đến. Nếu bạn thêm routes.warnings vào fieldmask của yêu cầu API Routes, thì các tuyến đường có đường thu phí sẽ được chú thích cho phù hợp trong trường này.

Các hành vi định tuyến khác

Khi bạn đặt travelMode thành TRUCK, API sẽ tự động tối ưu hoá tuyến đường để xe cỡ lớn có thể di chuyển dễ dàng. Các tuyến đường được tạo tránh đường vòng và ưu tiên đường liên tiểu bang và đường cao tốc hơn các đường nhỏ. Bạn không cần đặt thêm bất kỳ thông số hoặc giá trị sửa đổi nào để bật các hành vi này.

Tính toán một tuyến đường bằng `computeRoutes`

Sử dụng điểm cuối computeRoutes để tính toán một tuyến đường dành riêng cho xe tải giữa một điểm xuất phát và một điểm đến.

Ví dụ về yêu cầu `computeRoutes`

Sau đây là yêu cầu curl hoàn chỉnh cho một xe tải bán rơ-moóc thông thường. Ví dụ này bao gồm điểm cuối, tiêu đề và nội dung yêu cầu.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

Ví dụ về phản hồi `computeRoutes`

Đây là một ví dụ về phản hồi cho yêu cầu trước đó được trình bày ở trên. Xin lưu ý rằng trong đối tượng travelAdvisory, cờ routeRestrictionsPartiallyIgnored không được đưa vào. Điều này cho biết tuyến đường không được gắn cờ và được cho là hoàn toàn tuân thủ các thuộc tính của xe.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

Giải thích phản hồi `computeRoutes`

Một yêu cầu thành công đến điểm cuối computeRoutes sẽ trả về một đối tượng phản hồi JSON chứa một hoặc nhiều tuyến đường có thể.

Các trường phản hồi chính

Hình học tuyến đường được mã hoá: routes.polyline. Bạn có thể dùng đối tượng này để kết xuất tuyến đường trên bản đồ.
Thời lượng ước tính của chuyến đi: routes.duration (tính bằng giây). Thời lượng chuyến đi bằng xe lớn sử dụng một mô hình mới được huấn luyện dựa trên tốc độ di chuyển quan sát được của xe tải thực tế trên mạng lưới đường bộ. Bạn cũng có thể dùng thông tin này để tính thời gian đến dự kiến bằng cách cộng thời gian dự kiến của chuyến đi với thời gian khởi hành dự kiến.
Tổng quãng đường của tuyến đường: routes.distanceMeters (tính bằng mét).
Mã thông báo tuyến đường: routes.routeToken. Đây là một mã thông báo mờ đại diện cho tuyến đường được tính toán chính xác. Bạn truyền mã thông báo này đến Navigation SDK để đảm bảo người lái xe nhìn thấy cùng một tuyến đường dành riêng cho xe tải. Để biết thông tin chi tiết, hãy xem hướng dẫn về Navigation SDK cho Android hoặc iOS.

Kiểm tra các cờ an toàn trên tuyến đường

Khi nhận được phản hồi, việc đầu tiên bạn nên làm là kiểm tra các cờ an toàn của tuyến đường. Nếu một tuyến đường được cung cấp có một hoặc nhiều quy định hạn chế khiến tuyến đường đó không phù hợp với xe, bạn sẽ thấy trường travelAdvisory.routeRestrictionsPartiallyIgnored được đặt thành true.

Trường này đóng vai trò là một cờ để trả lời câu hỏi "Tuyến đường này có bị gắn cờ là có thể xảy ra vấn đề không?"

false(hoặc bị bỏ qua trong phản hồi): Tuyến đường không bị gắn cờ. Hệ thống đã tìm thấy một tuyến đường được cho là hoàn toàn tuân thủ các thông số mà bạn cung cấp trong yêu cầu.
true: Tuyến đường bị gắn cờ. Hệ thống không tìm thấy tuyến đường hoàn toàn tuân thủ và đã trả về một tuyến đường "tốt nhất có thể" có thể không an toàn hoặc hợp pháp. Bạn phải hết sức thận trọng khi sử dụng tuyến đường này.

Tính toán ma trận các tuyến đường (`computeRouteMatrix`)

Sử dụng điểm cuối computeRouteMatrix để so sánh hiệu quả thời gian di chuyển và khoảng cách giữa nhiều điểm xuất phát và điểm đến. Ví dụ: bạn có thể dùng tính năng này để tìm chiếc xe tải gần nhất với một vị trí đến lấy hàng mới. Sau khi xác định được nguồn gốc của chiếc xe mà bạn muốn sử dụng cho mục đích của mình, bạn có thể đưa ra yêu cầu computeRoutes để nhận thông tin chi tiết về tuyến đường và mã thông báo tuyến đường cho chiếc xe được đề xuất.

Để sử dụng computeRouteMatrix, bạn chỉ định vehicleInfo trong mỗi đối tượng origin thay vì ở gốc của yêu cầu.

Ví dụ về yêu cầu `computeRouteMatrix`

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Ví dụ về phản hồi `computeRouteMatrix`

Phản hồi là một mảng, trong đó mỗi đối tượng chứa thời lượng và distanceMeters cho một cặp điểm xuất phát – điểm đến.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Các bước tiếp theo

Cung cấp đường đi từng chặng: Tìm hiểu cách sử dụng routeToken trong Navigation SDK cho Android hoặc iOS.
Tối ưu hoá ở cấp đội xe: Sử dụng Route Optimization API với tính năng Định tuyến cho xe lớn.
Tài liệu tham khảo API: Để xem danh sách đầy đủ tất cả các trường và giá trị có thể có, hãy xem Tài liệu tham khảo API Routes.