- Yêu cầu HTTP
- Nội dung yêu cầu
- Nội dung phản hồi
- RouteMatrixOrigin
- RouteMatrixDestination
- ExtraComputation
- RouteMatrixElementCondition
- LocalizedValues
Nhận danh sách các điểm gốc và đích đến rồi trả về một luồng chứa thông tin tuyến đường cho từng tổ hợp điểm khởi hành và đích đến.
LƯU Ý: Phương thức này yêu cầu bạn chỉ định một mặt nạ trường phản hồi trong dữ liệu đầu vào. Bạn có thể cung cấp mặt nạ trường phản hồi bằng cách sử dụng tham số URL $fields
hoặc fields
hoặc tiêu đề HTTP/gRPC X-Goog-FieldMask
(xem các tham số và tiêu đề URL có sẵn). Giá trị này là một danh sách các đường dẫn trường được phân tách bằng dấu phẩy. Hãy xem tài liệu chi tiết về cách tạo đường dẫn trường.
Ví dụ: trong phương thức này:
- Mặt nạ trường của tất cả các trường có sẵn (để kiểm tra thủ công):
X-Goog-FieldMask: *
- Mặt nạ trường thể hiện thời lượng tuyến đường, khoảng cách, trạng thái phần tử, điều kiện và chỉ mục phần tử (ví dụ về chế độ thiết lập phiên bản chính thức):
X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration
Điều quan trọng là bạn phải thêm status
vào mặt nạ trường vì nếu không tất cả tin nhắn sẽ có vẻ ổn. Google không khuyến khích việc sử dụng mặt nạ trường phản hồi ký tự đại diện (*
) vì:
- Việc chỉ chọn những trường bạn cần sẽ giúp máy chủ của chúng tôi lưu chu kỳ tính toán, nhờ đó chúng tôi có thể trả lại kết quả cho bạn với độ trễ thấp hơn.
- Bạn chỉ nên chọn những trường mà bạn cần trong công việc phát hành công khai để đảm bảo hiệu suất ổn định về độ trễ. Chúng tôi có thể thêm các trường phản hồi khác trong tương lai và những trường mới đó có thể cần thêm thời gian tính toán. Nếu bạn chọn tất cả các trường hoặc chọn tất cả các trường ở cấp cao nhất, thì hiệu suất của bạn có thể bị suy giảm vì mọi trường mới mà chúng tôi thêm đều sẽ tự động được đưa vào câu trả lời.
- Việc chỉ chọn các trường bạn cần sẽ giúp kích thước phản hồi nhỏ hơn, từ đó giúp thông lượng mạng cao hơn.
Yêu cầu HTTP
POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix
URL sử dụng cú pháp Chuyển mã gRPC.
Nội dung yêu cầu
Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:
Biểu diễn dưới dạng JSON |
---|
{ "origins": [ { object ( |
Trường | |
---|---|
origins[] |
Bắt buộc. Mảng nguồn gốc xác định các hàng của ma trận phản hồi. Một số quy định hạn chế về kích thước áp dụng cho lượng số của nguồn gốc và đích đến:
|
destinations[] |
Bắt buộc. Mảng đích đến, xác định các cột của ma trận phản hồi. |
travelMode |
Không bắt buộc. Xác định phương thức di chuyển. |
routingPreference |
Không bắt buộc. Chỉ định cách tính toán tuyến. Máy chủ cố gắng sử dụng lựa chọn ưu tiên định tuyến đã chọn để tính toán tuyến đường. Nếu lựa chọn ưu tiên định tuyến gây ra lỗi hoặc độ trễ thêm lâu, thì hệ thống sẽ trả về lỗi. Bạn chỉ có thể chỉ định tuỳ chọn này khi |
departureTime |
Không bắt buộc. Thời gian khởi hành. Nếu bạn không đặt giá trị này thì giá trị mặc định sẽ là thời gian bạn yêu cầu. LƯU Ý: Bạn chỉ có thể chỉ định Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: |
arrivalTime |
Không bắt buộc. Thời gian đến. LƯU Ý: Chỉ có thể đặt khi Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: |
languageCode |
Không bắt buộc. Mã ngôn ngữ BCP-47, chẳng hạn như "en-US" hoặc "sr-Latn". Để biết thêm thông tin, hãy xem Mã nhận dạng ngôn ngữ Unicode. Hãy xem phần Hỗ trợ ngôn ngữ để biết danh sách các ngôn ngữ được hỗ trợ. Khi bạn không cung cấp giá trị này, ngôn ngữ hiển thị sẽ được suy ra từ vị trí của nguồn đầu tiên. |
regionCode |
Không bắt buộc. Mã vùng, được chỉ định dưới dạng ccTLD ("miền cấp cao nhất") gồm hai ký tự. Để biết thêm thông tin, hãy xem phần Miền cấp cao nhất của mã quốc gia. |
units |
Không bắt buộc. Chỉ định đơn vị đo lường cho các trường hiển thị. |
extraComputations[] |
Không bắt buộc. Danh sách các phép tính bổ sung có thể dùng để hoàn tất yêu cầu. Lưu ý: Các phép tính bổ sung này có thể trả về các trường bổ sung trên phản hồi. Bạn cũng phải chỉ định các trường bổ sung này trong mặt nạ trường để được trả về trong phản hồi. |
trafficModel |
Không bắt buộc. Chỉ định các giả định cần sử dụng khi tính toán thời gian tham gia lưu lượng truy cập. Chế độ cài đặt này ảnh hưởng đến giá trị được trả về trong trường thời lượng trong |
transitPreferences |
Không bắt buộc. Chỉ định các lựa chọn ưu tiên ảnh hưởng đến tuyến được trả về cho các tuyến |
Nội dung phản hồi
Chứa thông tin tuyến đường được tính toán cho cặp điểm khởi hành/đích trong API v2.computeRouteMatrix. Proto này có thể được truyền trực tuyến đến máy khách.
Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:
Biểu diễn dưới dạng JSON |
---|
{ "status": { object ( |
Trường | |
---|---|
status |
Mã trạng thái lỗi cho phần tử này. |
condition |
Cho biết liệu có tìm thấy tuyến đường hay không. Không phụ thuộc vào trạng thái. |
distanceMeters |
Khoảng cách đi lại của tuyến đường, tính bằng mét. |
duration |
Khoảng thời gian cần thiết để điều hướng tuyến đường. Nếu bạn đặt Thời lượng tính bằng giây với tối đa 9 chữ số phân số, kết thúc bằng " |
staticDuration |
Thời gian di chuyển trên tuyến đường mà không tính đến tình trạng giao thông. Thời lượng tính bằng giây với tối đa 9 chữ số phân số, kết thúc bằng " |
travelAdvisory |
Thông tin bổ sung về tuyến đường. Ví dụ: thông tin về quy định hạn chế và phí cầu đường |
fallbackInfo |
Trong một số trường hợp khi máy chủ không thể tính toán tuyến đường bằng các lựa chọn ưu tiên đã cho cho cặp điểm đi/đích cụ thể này, máy chủ có thể quay lại sử dụng một chế độ tính toán khác. Khi sử dụng chế độ dự phòng, trường này chứa thông tin chi tiết về phản hồi dự phòng. Nếu không, trường này sẽ không được đặt. |
localizedValues |
Biểu diễn văn bản các thuộc tính của |
originIndex |
Chỉ mục gốc 0 của nguồn gốc trong yêu cầu. |
destinationIndex |
Chỉ mục từ 0 của đích đến trong yêu cầu. |
RouteMatrixOrigin
Một nguồn gốc duy nhất cho ComputeRouteMatrixRequest
Biểu diễn dưới dạng JSON |
---|
{ "waypoint": { object ( |
Trường | |
---|---|
waypoint |
Bắt buộc. Điểm tham chiếu gốc |
routeModifiers |
Không bắt buộc. Đối tượng sửa đổi cho mọi tuyến lấy tuyến này làm nguồn gốc |
RouteMatrixDestination
Một đích đến duy nhất cho ComputeRouteMatrixRequest
Biểu diễn dưới dạng JSON |
---|
{
"waypoint": {
object ( |
Trường | |
---|---|
waypoint |
Bắt buộc. Điểm tham chiếu đích |
ExtraComputation
Các phép tính bổ sung để thực hiện trong khi hoàn tất yêu cầu.
Enum | |
---|---|
EXTRA_COMPUTATION_UNSPECIFIED |
Không được sử dụng. Các yêu cầu chứa giá trị này sẽ không thực hiện được. |
TOLLS |
Thông tin tính phí cho(các) phần tử ma trận. |
RouteMatrixElementCondition
Điều kiện của tuyến đường được trả về.
Enum | |
---|---|
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED |
Chỉ được dùng khi status của phần tử không OK. |
ROUTE_EXISTS |
Đã tìm thấy một tuyến và điền thông tin tương ứng cho phần tử. |
ROUTE_NOT_FOUND |
Không tìm thấy tuyến đường nào. Các trường có chứa thông tin tuyến đường, chẳng hạn như distanceMeters hoặc duration , sẽ không được điền trong phần tử. |
LocalizedValues
Biểu diễn văn bản của một số thuộc tính.
Biểu diễn dưới dạng JSON |
---|
{ "distance": { object ( |
Trường | |
---|---|
distance |
Quãng đường đi được thể hiện trong dạng văn bản. |
duration |
Thời lượng được thể hiện ở dạng văn bản có tính đến điều kiện giao thông. Lưu ý: Nếu thông tin lưu lượng truy cập không được yêu cầu, thì giá trị này sẽ giống với giá trị staticDuration. |
staticDuration |
Thời lượng được thể hiện ở dạng văn bản mà không tính đến tình trạng giao thông. |
transitFare |
Giá vé đi phương tiện công cộng được trình bày ở dạng văn bản. |