Method: computeRouteMatrix

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 (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
Trường
origins[]

object (RouteMatrixOrigin)

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:

  • Tổng số nguồn gốc + số lượng đích đến được chỉ định là placeId hoặc address không được lớn hơn 50.
  • Tích của số nguồn gốc × số lượng đích đến không được lớn hơn 625 trong mọi trường hợp.
  • Tích của số nguồn gốc × số lượng đích đến không được lớn hơn 100 nếu định tuyếnPreference được đặt thành TRAFFIC_AWARE_OPTIMAL.
  • Tích của số điểm khởi hành × số lượng điểm đến không được lớn hơn 100 nếu bạn đặt TravelMode thành TRANSIT.
destinations[]

object (RouteMatrixDestination)

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

enum (RouteTravelMode)

Không bắt buộc. Xác định phương thức di chuyển.
routingPreference

enum (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 travelMode là DRIVE hoặc TWO_WHEELER, nếu không, yêu cầu sẽ không thành công.
departureTime

string (Timestamp format)

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 departureTime trong quá khứ khi RouteTravelMode được đặt thành TRANSIT.

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ụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".
arrivalTime

string (Timestamp format)

Không bắt buộc. Thời gian đến. LƯU Ý: Chỉ có thể đặt khi RouteTravelMode được đặt thành TRANSIT. Bạn có thể chỉ định departureTime hoặc arrivalTime, nhưng không thể chỉ định cả hai.

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ụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".
languageCode

string

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

string

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

enum (Units)

Không bắt buộc. Chỉ định đơn vị đo lường cho các trường hiển thị.
extraComputations[]

enum (ExtraComputation)

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

enum (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 RouteMatrixElement. Trường này chứa thời gian dự đoán lưu lượng truy cập dựa trên mức trung bình trước đây. RoutingPreference đến TRAFFIC_AWARE_OPTIMAL và RouteTravelMode đến DRIVE. Giá trị mặc định là BEST_GUESS nếu lưu lượng truy cập được yêu cầu và TrafficModel không được chỉ định.
transitPreferences

object (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 TRANSIT. LƯU Ý: Bạn chỉ có thể chỉ định transitPreferences khi RouteTravelMode được đặt thành TRANSIT.

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 (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
Trường
status

object (Status)

Mã trạng thái lỗi cho phần tử này.
condition

enum (RouteMatrixElementCondition)

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

integer

Khoảng cách đi lại của tuyến đường, tính bằng mét.
duration

string (Duration format)

Khoảng thời gian cần thiết để điều hướng tuyến đường. Nếu bạn đặt routingPreference thành TRAFFIC_UNAWARE, thì giá trị này sẽ giống với staticDuration. Nếu bạn đặt routingPreference thành TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL, thì giá trị này sẽ được tính toán có tính đến điều kiện 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 "s". Ví dụ: "3.5s".
staticDuration

string (Duration format)

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 "s". Ví dụ: "3.5s".
travelAdvisory

object (RouteTravelAdvisory)

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

object (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

object (LocalizedValues)

Biểu diễn văn bản các thuộc tính của RouteMatrixElement.
originIndex

integer

Chỉ mục gốc 0 của nguồn gốc trong yêu cầu.
destinationIndex

integer

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 (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
Trường
waypoint

object (Waypoint)

Bắt buộc. Điểm tham chiếu gốc
routeModifiers

object (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 (Waypoint)
  }
}
Trường
waypoint

object (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 (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
Trường
distance

object (LocalizedText)

Quãng đường đi được thể hiện trong dạng văn bản.
duration

object (LocalizedText)

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

object (LocalizedText)

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

object (LocalizedText)

Giá vé đi phương tiện công cộng được trình bày ở dạng văn bản.