Method: computeRouteMatrix

接收起點和目的地清單，並傳回包含每個起點和目的地組合路線資訊的串流。

注意：這個方法需要您在輸入內容中指定回應欄位遮罩。您可以使用網址參數 $fields 或 fields，或使用 HTTP/gRPC 標頭 X-Goog-FieldMask 提供回應欄位遮罩 (請參閱可用的網址參數和標頭)。值是以半形逗號分隔的欄位路徑清單。請參閱這份詳細說明文件，瞭解如何建構欄位路徑。

舉例來說，在這個方法中：

  • 所有可用欄位的欄位遮罩 (適用於手動檢查)：X-Goog-FieldMask: *
  • 路徑時間、距離、元素狀態、條件和元素索引的欄位遮罩 (生產設定範例)：X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

請務必在欄位遮罩中加入 status，否則所有訊息都會顯示為正常。Google 不建議使用萬用字元 (*) 回應欄位遮罩，原因如下：

  • 只選取需要的欄位，有助於伺服器節省運算週期，讓我們以較低的延遲時間將結果傳回給您。
  • 在實際執行作業中只選取所需欄位，可確保延遲效能穩定。我們日後可能會新增更多回應欄位，而這些新欄位可能需要額外的運算時間。如果您選取所有欄位，或是在頂層選取所有欄位，系統可能會自動在回應中加入我們新增的欄位，導致效能降低。
  • 只選取所需欄位可縮減回應大小，進而提高網路輸送量。

HTTP 要求

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體會包含結構如下的資料：

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)
  }
}
欄位
origins[]

object (RouteMatrixOrigin)

必要欄位。來源陣列，用於決定回應矩陣的資料列。來源和目的地的基數有幾項大小限制：

  • 指定為 placeId 或 address 的起點數量和目的地數量總和不得超過 50。
  • 在任何情況下，起點數量 × 目的地數量不得大於 625。
  • 如果 routingPreference 設為 TRAFFIC_AWARE_OPTIMAL，起點數 × 目的地數的乘積不得大於 100。
  • 如果 travelMode 設為 TRANSIT，起點數量 × 目的地數量不得超過 100。
destinations[]

object (RouteMatrixDestination)

必要欄位。目的地陣列，決定回應矩陣的資料欄。
travelMode

enum (RouteTravelMode)

(選用步驟) 指定交通方式。
routingPreference

enum (RoutingPreference)

(選用步驟) 指定路線的計算方式。伺服器會嘗試使用所選的轉送偏好設定來計算路徑。如果路由偏好設定導致錯誤或延遲時間過長，系統會傳回錯誤。只有在 travelMode 為 DRIVE 或 TWO_WHEELER 時，才能指定這個選項，否則要求會失敗。
departureTime

string (Timestamp format)

(選用步驟) 出發時間。如未設定這個值，系統會預設為您提出要求的時間。注意：只有在 RouteTravelMode 設為 TRANSIT 時，才能指定過去的 departureTime。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
arrivalTime

string (Timestamp format)

(選用步驟) 抵達時間。注意：只有在 RouteTravelMode 設為 TRANSIT 時，才能設定這項屬性。您可以選擇指定 departureTime 或 arrivalTime，但不能兩者同時指定。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
languageCode

string

(選用步驟) BCP-47 語言代碼，例如「en-US」或「sr-Latn」。詳情請參閱「Unicode 語言代碼」。如需支援的語言清單，請參閱「語言支援」一文。如未提供這個值，系統會根據第一個來源的位置推斷顯示語言。
regionCode

string

(選用步驟) 區碼，指定為 ccTLD (「頂層網域」) 的兩位字元值。詳情請參閱「國家/地區代碼頂層網域」。
units

enum (Units)

(選用步驟) 指定顯示欄位的測量單位。
extraComputations[]

enum (ExtraComputation)

(選用步驟) 可用於完成要求的額外運算清單。注意：這些額外計算可能會在回應中傳回額外欄位。這些額外欄位也必須在欄位遮罩中指定，才能在回應中傳回。
trafficModel

enum (TrafficModel)

(選用步驟) 指定計算交通時間時要採用的假設。這項設定會影響 RouteMatrixElement 中「時間長度」欄位傳回的值，其中包含根據歷來平均值預估的交通時間。TrafficModel 僅適用於將 RoutingPreference 設為 TRAFFIC_AWARE_OPTIMAL，並將 RouteTravelMode 設為 DRIVE 的要求。如果要求提供流量，但未指定 TrafficModel，則預設值為 BEST_GUESS。
transitPreferences

object (TransitPreferences)

(選用步驟) 指定偏好設定，影響 TRANSIT 路線傳回的路線。注意：只有在 RouteTravelMode 設為 TRANSIT 時，才能指定 transitPreferences。

回應主體

包含 v2.computeRouteMatrix API 中，針對起點/目的地組合計算的路線資訊。這個 proto 可以串流至用戶端。

如果成功，回應主體會含有以下結構的資料：

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
}
欄位
status

object (Status)

這個元素的錯誤狀態碼。
condition

enum (RouteMatrixElementCondition)

指出是否找到路線。與狀態無關。
distanceMeters

integer

路線的移動距離 (以公尺為單位)。
duration

string (Duration format)

導覽路線所需的時間長度。如果將 routingPreference 設為 TRAFFIC_UNAWARE，這個值就會與 staticDuration 相同。如果將 routingPreference 設為 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，系統會考量路況來計算這個值。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
staticDuration

string (Duration format)

不考量路況的路線行車時間。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
travelAdvisory

object (RouteTravelAdvisory)

路線的其他資訊。例如：限制資訊和收費資訊
fallbackInfo

object (FallbackInfo)

在某些情況下，如果伺服器無法根據特定起點/目的地組合的偏好設定計算路線，可能會改用其他計算模式。使用備援模式時，這個欄位會包含備援回應的詳細資訊。否則這個欄位不會設定。
localizedValues

object (LocalizedValues)

RouteMatrixElement 屬性的文字表示法。
originIndex

integer

要求中來源的索引，從零開始。
destinationIndex

integer

要求中目的地的索引，從零開始。

RouteMatrixOrigin

ComputeRouteMatrixRequest 的單一來源

JSON 表示法 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
欄位
waypoint

object (Waypoint)

必要欄位。起點路線控點
routeModifiers

object (RouteModifiers)

(選用步驟) 以這個做為起點的每條路線的修飾符

RouteMatrixDestination

ComputeRouteMatrixRequest 的單一目的地

JSON 表示法 
{
  "waypoint": {
    object (Waypoint)
  }
}
欄位
waypoint

object (Waypoint)

必要欄位。目的地航點

ExtraComputation

完成要求時要執行的額外計算。

列舉
EXTRA_COMPUTATION_UNSPECIFIED 未使用。含有這個值的要求會失敗。
TOLLS 矩陣元素適用的收費資訊。

RouteMatrixElementCondition

傳回路線的狀況。

列舉
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED 只有在元素 status 不正常時才會使用。
ROUTE_EXISTS 系統找到路徑，並為元素填入相應資訊。
ROUTE_NOT_FOUND 找不到路線。元素中不會填入含有路線資訊的欄位，例如 distanceMeters 或 duration。

LocalizedValues

特定屬性的文字表示法。

JSON 表示法 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
欄位
distance

object (LocalizedText)

以文字形式表示的行駛距離。
duration

object (LocalizedText)

以文字形式表示的預估時間，會考量路況。注意：如果未要求提供即時路況資訊，這個值會與 staticDuration 相同。
staticDuration

object (LocalizedText)

以文字形式表示的時長，未考量流量狀況。
transitFare

object (LocalizedText)

以文字形式表示的大眾運輸票價。