Method: computeRouteMatrix

Nhận danh sách các điểm xuất phát và điểm đến, đồng thời trả về một luồng chứa thông tin về tuyến đường cho từng 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 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à một 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ạ cho 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, khoảng cách, trạng thái phần tử, điều kiện và chỉ mục phần tử của tuyến đường (ví dụ về chế độ thiết lập sản xuất): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

Bạn phải thêm 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 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 giúp máy chủ của chúng tôi tiết kiệm cá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.
  • Chỉ chọn những trường 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 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ể gặp phải tình trạng giảm hiệu suất vì mọi trường mới mà chúng tôi thêm sẽ tự động được đưa vào phản hồi.
  • Chỉ chọn những trường bạn cần sẽ giúp giảm kích thước phản hồi, nhờ đó tăng thông lượ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 với 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ố 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ố điểm xuất phát + số đ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.
  • 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 100 nếu routingPreference được đặt thành TRAFFIC_AWARE_OPTIMAL.
  • 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 100 nếu travelMode được đặt 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. 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ủ cố gắng sử dụng lựa chọn ưu tiên về định tuyến đã chọn để tính toán tuyến đường. Nếu lựa chọn ưu tiên về định tuyến dẫn đến lỗi hoặc độ trễ quá dài, thì lỗi sẽ được trả về. Bạn chỉ có thể chỉ định lựa 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 gian 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.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
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.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
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 bài viết Mã nhận dạng ngôn ngữ theo chuẩn 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 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 2 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 ý: Những 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 toán thời gian di chuyển. 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 khi có lưu lượng truy cập dựa trên mức trung bình trong quá khứ. TrafficModel chỉ dành cho những yêu cầu đã đặt RoutingPreference thành TRAFFIC_AWARE_OPTIMAL và RouteTravelMode thành 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 lựa 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 một transitPreferences khi RouteTravelMode được đặt thành TRANSIT.

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 điểm xuất phát/đích đến trong API v2.computeRouteMatrix. Proto này có thể được truyền trực tuyến đế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 tuyến đường có được tìm thấy hay không. Không phụ thuộc vào trạng thái.
distanceMeters

integer

Quãng đường di chuyển 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 có 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".
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, 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ề 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 theo các lựa chọn ưu tiên đã cho đối với cặp điểm xuất phát/đích đến cụ thể này, thì 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 dùng, trường này chứa thông tin chi tiết về câu trả lờ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 trong yêu cầu (bắt đầu từ 0).
destinationIndex

integer

Chỉ mục dựa trên 0 của đích đến trong yêu cầu.

RouteMatrixOrigin

Một nguồn 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 ban đầu
routeModifiers

object (RouteModifiers)

Không bắt buộc. Các đối tượng sửa đổi cho mọi tuyến đường lấy điểm này làm điểm xuất phát

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 trên đường đi

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 dùng. Những yêu cầu có 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ỉ dùng khi status của phần tử không phải là OK.
ROUTE_EXISTS Hệ thống đã 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 về tuyến đường, chẳng hạn như distanceMeters hoặc duration, sẽ không được điền sẵ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 di chuyển được thể hiện dưới dạng văn bản.
duration

object (LocalizedText)

Thời lượng được biểu thị dưới dạng văn bản, có tính đến tình trạng giao thông. 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 giá trị staticDuration.
staticDuration

object (LocalizedText)

Thời lượng được biểu thị dưới dạng văn bản mà không xem xét tình trạng giao thông.
transitFare

object (LocalizedText)

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