Method: computeRouteMatrix

Nhận danh sách các điểm xuất phát và điểm đến, sau đó trả về một luồng chứa thông tin tuyến đường cho mỗi tổ hợp điểm xuất phát và điểm đến.

LƯU Ý: Phương thức 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ạ trường phản hồi bằng cách sử dụng tham số URL $fields hoặc fields hoặc bằng cách sử dụng tiêu đề HTTP/gRPC X-Goog-FieldMask (xem các tham số và tiêu đề URL hiện có). Giá trị này là danh sách đườ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 này 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 của thời lượng tuyến, khoảng cách, trạng thái phần tử, tình trạng và chỉ mục phần tử (ví dụ về chế độ thiết lập sản xuất): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

Bạn cần phải đưa status vào mặt nạ trường, nếu không tất cả thông báo sẽ xuất hiện là OK. Google không khuyến khích 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 mà bạn cần giúp máy chủ của chúng tôi tiết kiệm được chu kỳ tính toán, cho phép chúng tôi trả về kết quả cho bạn với độ trễ thấp hơn.
  • Việc chỉ chọn những trường mà bạn cần trong công việc sản xuất sẽ đảm bảo hiệu suất độ trễ ổn định. Trong tương lai, chúng tôi có thể thêm các trường phản hồi khác và các trường mới đó có thể cần thêm thời gian tính toán. Nếu chọn tất cả các trường hoặc nếu chọn tất cả các trường ở cấp cao nhất, thì bạn có thể thấy hiệu suất giảm vì mọi trường mới mà chúng tôi thêm vào sẽ tự động được đưa vào phản hồi.
  • Việc chỉ chọn các trường mà bạn cần sẽ giúp giảm kích thước phản hồi, nhờ đó tăng băng thông mạng.

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 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 số lượng giá trị riêng biệt của nguồn và đích:

  • Tổng số lượng điểm xuất phát + số lượng điểm đến được chỉ định là placeId hoặc address không được lớn hơn 50.
  • Trong mọi trường hợp, tích của số lượng điểm xuất phát × số lượng điểm đến không được lớn hơn 625.
  • Sản phẩm của số lượng điểm xuất phát × số lượng điểm đến không được lớn hơn 100 nếu bạn đặt routingPreference thành TRAFFIC_AWARE_OPTIMAL.
  • Sản phẩm của số lượng điểm xuất phát × số lượng điểm đến không được lớn hơn 100 nếu travelMode được đặt thành TRANSIT.
destinations[]

object (RouteMatrixDestination)

Bắt buộc. Mảng đích 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. Chỉ định phương tiện giao thông.
routingPreference

enum (RoutingPreference)

Không bắt buộc. Chỉ định cách tính toán tuyến đường. Máy chủ sẽ cố gắng sử dụng lựa chọn ưu tiê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á lâu, thì lỗi sẽ được trả về. 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ị này sẽ mặc định là thời điểm bạn đưa ra 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 ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. 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 Ý: Bạn 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 được chỉ định cả hai.

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. 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 phần Giá trị nhận dạng ngôn ngữ Unicode. Hãy xem phần Hỗ trợ ngôn ngữ để biết danh sách 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

string

Không bắt buộc. Mã vùng, được chỉ định dưới dạng giá trị gồm hai ký tự ccTLD ("miền cấp cao nhất"). Để biết thêm thông tin, hãy xem bài viết Miền cấp cao nhất theo 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ể được 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 trong 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 thời gian trong 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 duration (thời lượng) trong RouteMatrixElement. Trường này chứa thời gian dự đoán trong lưu lượng truy cập dựa trên mức trung bình trong quá khứ. RoutingPreference đến TRAFFIC_AWARE_OPTIMAL và RouteTravelMode đến DRIVE. 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 tuỳ chọn ưu tiên ảnh hưởng đến tuyến đường được trả về cho các tuyến đường 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 một cặp điểm xuất phát/điểm đến trong API v2.computeRouteMatrix. Bạn có thể truyền trực tuyến proto này đến ứng dụng.

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

Quãng đường đ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 theo 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, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
staticDuration

string (Duration format)

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, có tối đa 9 chữ số thập phân, 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à thông tin về đường thu phí
fallbackInfo

object (FallbackInfo)

Trong một số trường hợp, khi 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 xuất phát/điểm đến 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 chế độ dự phòng được sử dụng, trường này sẽ 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ủa các thuộc tính của RouteMatrixElement.
originIndex

integer

Chỉ mục gốc dựa trên 0 trong yêu cầu.
destinationIndex

integer

Chỉ mục dựa trên số 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 đường lấy giá trị này làm 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 trung gian đến

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 về phí cầu đường cho(các) phần tử ma trận.

RouteMatrixElementCondition

Tình trạng 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 đường 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 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 thị 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)

Khoảng cách di chuyển được thể hiện ở dạng văn bản.
duration

object (LocalizedText)

Thời lượng được thể hiện dưới dạng văn bản, có tính đến điều kiện lưu lượng truy cập. Lưu ý: Nếu bạn không yêu cầu thông tin về lưu lượng truy cập, thì giá trị này sẽ giống với staticDuration.
staticDuration

object (LocalizedText)

Thời lượng được thể hiện ở dạng văn bản mà không tính đến điều kiện lưu lượng truy cập.
transitFare

object (LocalizedText)

Giá vé phương tiện công cộng được thể hiện ở dạng văn bản.