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,
  "languageCode": string,
  "regionCode": string,
  "extraComputations": [
    enum (ExtraComputation)
  ]
}
欄位
origins[]

object (RouteMatrixOrigin)

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

  • 在任何情況下，元素 (來源 × 目的地) 的數量不得大於 625。
  • 如果 routePreference 設為 TRAFFIC_AWARE_OPTIMAL，則元素數量 (來源 × 目的地) 不得大於 100。
  • 指定為 placeId 的路線控點 (出發地 + 目的地) 數量不得超過 50。
destinations[]

object (RouteMatrixDestination)

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

enum (RouteTravelMode)

選填欄位，指定交通方式。
routingPreference

enum (RoutingPreference)

選填欄位，指定如何計算路徑。伺服器會嘗試使用所選的轉送偏好設定來計算路徑。如果轉送偏好設定導致錯誤或較長的延遲時間，則會傳回錯誤。只有在 travelMode 為 DRIVE 或 TWO_WHEELER 時，才可指定這個選項，否則要求將會失敗。
departureTime

string (Timestamp format)

選填欄位，出發時間。如未設定這個值，預設值為您提出要求的時間。如果將這個值設定為已經發生的時間，請求就會失敗。

RFC3339 UTC 的「Zulu」格式的時間戳記，單位為奈秒解析度，最多可達 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
languageCode

string

選填欄位，BCP-47 語言代碼，例如「en-US」或「sr-Latn」。詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。如需支援的語言清單，請參閱語言支援。如未提供這個值，系統將根據第一個來源的位置推測顯示語言。
regionCode

string

選填欄位，以 ccTLD (「頂層網域」) 為兩個字元的值來指定區域代碼。詳情請參閱 https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains
extraComputations[]

enum (ExtraComputation)

選填欄位，可用於完成要求的額外運算清單。注意： 這些額外運算可能會在回應中傳回額外的欄位。您必須在欄位遮罩中指定這些額外欄位，以在回應中傳回。

回應主體

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

封裝在 v2.computeRouteMatrix API 中為起點/目的地對組計算的路線資訊。這個 proto 可以串流至用戶端。

JSON 表示法 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "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)

在某些情況下，如果伺服器無法依照該特定來源/目的地組合的指定偏好設定計算路徑，可能會改用不同的計算模式。使用備用模式時，這個欄位會包含備用回應的詳細資訊。否則系統會取消設定這個欄位。
originIndex

integer

要求中來源的零索引索引。
destinationIndex

integer

要求中的目的地為零的索引。

路徑矩陣

ComputeRouteMatrixRequest 的單一來源

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

object (Waypoint)

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

object (RouteModifiers)

選填欄位，所有以此做為起點的來源路徑的修飾符

路徑馬德里

ComputeRouteMatrixRequest 的單一目的地

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

object (Waypoint)

必要欄位。目的地路線控點

額外計算

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

列舉
EXTRA_COMPUTATION_UNSPECIFIED 未使用。包含此值的要求會失敗。
TOLLS 矩陣元素的收費路段資訊。

RouteMatrixElementCondition

所傳迴路線的條件。

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