- Yêu cầu HTTP
- Nội dung yêu cầu
- Nội dung phản hồi
- RouteMatrixOrigin
- RouteMatrixDestination
- ExtraComputation
- RouteMatrixElementCondition
- LocalizedValues
Lấy danh sách điểm gốc và điểm đến rồi trả về luồng chứa thông tin tuyến đường cho từng tổ hợp điểm gốc và điểm đến.
LƯU Ý: Phương pháp này yêu cầu bạn chỉ định 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ạ cho trường (field mask) 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ị là một danh sách các đường dẫn trường được phân tách bằng dấu phẩy. Xem tài liệu chi tiết này về cách tạo đường dẫn trường.
Ví dụ: trong phương thức này:
- Mặt nạ cho trường (field mask) 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 của thời lượng tuyến đường, khoảng cách, trạng thái, điều kiện và chỉ mục phần tử của tuyến đường (ví dụ về cách thiết lập 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ạ cho trường (field mask) vì nếu không thì tất cả thông báo sẽ có vẻ như bình thường. Google không khuyến khích việc sử dụng mặt nạ cho trường phản hồi ký tự đại diện (*
) vì:
- Việc chỉ chọn các trường mà 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ả về kết quả cho bạn với độ trễ thấp hơn.
- Bạn chỉ nên chọn các trường mà bạn cần trong công việc sản xuất để đảm bảo hiệu suất độ trễ ổn định. 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ó thể sẽ 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.
- Chỉ chọn các trường bạn cần sẽ làm giảm kích thước phản hồi, từ đó mang lại 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 các đí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. Chỉ đị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 tuỳ chọn định tuyến đã chọn để tính toán tuyến. Nếu tuỳ chọn định tuyến dẫn đến lỗi hoặc độ trễ quá dài, 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ị này sẽ mặc định theo thời gian bạn thực hiện yêu cầu. LƯU Ý: Bạn chỉ có thể chỉ định Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, với độ phân giải nano giây và tối đa 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 ở định dạng "Zulu" RFC3339 UTC, với độ phân giải nano giây và tối đa 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 phần Mã nhận dạng ngôn ngữ Unicode. Xem trang 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 gốc đầu tiên. |
regionCode |
Không bắt buộc. Mã vùng được chỉ định ở dạng ccTLD (miền cấp cao nhất) gồm 2 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 ý: Những phép tính bổ sung này có thể trả về các trường bổ sung trong câu trả lời. Các trường bổ sung này cũng phải được chỉ định trong mặt nạ trường (field mask) để được trả về trong phản hồi. |
trafficModel |
Không bắt buộc. Nêu các giả định cần sử dụng khi tính thời gian 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 về tuyến đường được tính toán cho một cặp nguồn gốc/đích đến trong API v2.computeRouteMatrix. Proto này có thể được truyền trực tuyến đến ứng dụng 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 của phần tử này. |
condition |
Cho biết liệu tuyến đường có được tìm thấy 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 thiết lập Thời lượng tính bằng giây với tối đa 9 chữ số thập phân, kết thúc bằng " |
staticDuration |
Thời gian di chuyển qua 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ố thập phân, 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à thông tin về phí cầu đường |
fallbackInfo |
Trong một số trường hợp khi không thể tính toán tuyến với các tuỳ chọn đã cho cho cặp điểm gốc/đích cụ thể này, máy chủ có thể quay lại sử dụng 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 |
Văn bản đại diện cho 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 dựa trên 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 đường lấy giá trị này làm điểm 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 cần 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ành công. |
TOLLS |
Thông tin cước phí cho(các) phần tử ma trận. |
RouteMatrixElementCondition
Tình trạng của tuyến được trả về.
Enum | |
---|---|
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED |
Chỉ được dùng khi status của phần tử không ổn. |
ROUTE_EXISTS |
Đã tìm thấy một tuyến và thông tin tương ứng đã được điền 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
Phần văn bản đại diện cho một số thuộc tính nhất định.
Biểu diễn dưới dạng JSON |
---|
{ "distance": { object ( |
Trường | |
---|---|
distance |
Quãng đường đi được thể hiện dưới dạng văn bản. |
duration |
Thời lượng được biểu thị ở dạng văn bản có tính đến điều kiện giao thông. Lưu ý: Nếu bạn không yêu cầu thông tin lưu lượng truy cập, thì giá trị này giống với giá trị staticDuration. |
staticDuration |
Thời lượng được biểu thị dưới dạng văn bản mà không tính đến điều kiện giao thông. |
transitFare |
Giá vé phương tiện công cộng được thể hiện ở dạng văn bản. |