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://routespreferred.googleapis.com/v1:computeRouteMatrix

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

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string
}
欄位
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 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

回應主體

如果成功，回應主體會包含 RouteMatrixElement 的執行例項。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/maps-platform.routespreferred

詳情請參閱 OAuth 2.0 總覽。