取得路徑矩陣

路線矩陣是路線資訊的二維陣列，其中資料列對應起點，資料欄則對應目的地。只要提供起點和目的地清單，Route Matrix 類別就會計算從每個起點出發，抵達每個目的地的路線距離和時間。使用 Route Matrix 類別計算多個起點和目的地的路線距離和時間。

要求限制

RouteMatrix.computeRouteMatrix() 方法會對使用地址或地點例項的航點，以及項目強制執行下列要求限制。項目是指路線矩陣中每個起點和目的地之間的路線，因此項目數量等於起點數量乘以目的地數量。舉例來說，如果您有 10 個出發地和 10 個目的地，就會有 100 個項目：

  • 如果不是 TRANSIT 路線，項目數量不得超過 625 個。
  • 如果指定 TRANSIT 路徑，項目數量不得超過 100 個。
  • 如果您指定 TRAFFIC_AWARE_OPTIMAL，項目數量不得超過 100 個。
  • 如果您使用地址或地點執行個體指定來源或目的地，最多可以指定 50 個。

路徑矩陣要求範例

以下範例顯示 ComputeRouteMatrixRequest。這個範例會執行下列操作：

  • 顯示指定兩個起點和兩個目的地路線控點的陣列。這個方法會計算從每個起點到每個目的地的路線，因此回應會包含四條路線。
    在陣列中，第一個元素的索引為 0，第二個元素的索引為 1，以此類推。
  • 指定要傳回的欄位。在本範例中，請設定要求，針對每個路徑傳回 durationMillis、distanceMeters 和 condition。
const request = {
  origins: [origin1, origin2],
  destinations: [destinationA, destinationB],
  travelMode: google.maps.TravelMode.DRIVING,
  units: google.maps.UnitSystem.METRIC,
  fields: ['durationMillis', 'distanceMeters', 'condition'], 
};

回應包含所有起點和目的地中途點組合的四條可能路線，如下列範例所示：

"matrix": {
  "rows": [
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 202587,
          "durationMillis": 10040000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 252734,
          "durationMillis": 12240000
        }
      ]
    },
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 166135,
          "durationMillis": 6596000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 216282,
          "durationMillis": 8797000
        }
      ]
    }
  ]
}

使用起點和目的地索引，在 2D 陣列中找出對應的 RouteMatrixItem，即可識別結果中的每條路線。舉例來說，描述從要求中索引 1 的起點和目的地 0 計算出的路線，會位於 RouteMatrix.rows 陣列的第 2 個元素和 RouteMatrixRow.items 陣列的第 1 個元素中。 RouteMatrixItem

下列程式碼片段說明如何找出 RouteMatrixItem，以便尋找特定起點和目的地的路線：

// Find the route for origin 'x' and destination 'y'.
const {matrix} = await RouteMatrix.computeRouteMatrix(request);
const myRouteMatrixItem = matrix.rows[x].items[y];

選擇要傳回的欄位

要求路徑矩陣時，您必須使用欄位遮罩指定回應應傳回的資訊。

使用欄位遮罩也能確保您不會要求不必要的資料，進而縮短回應延遲時間，並避免傳回系統不需要的資訊。

設定 ComputeRoutesMatrixRequest.fields 屬性，指定所需欄位清單，如下方程式碼片段所示： 

fields: ['durationMillis', 'distanceMeters', 'condition'],

決定要使用的欄位遮罩

以下說明如何判斷要使用的欄位，並為這些欄位建構欄位遮罩：

  1. 使用 ['*'] 的欄位遮罩要求所有欄位。
  2. 查看您所需欄位的 RouteMatrixItem 類別中欄位階層。

  3. 使用下列格式，根據上一步顯示的欄位階層建構欄位遮罩：

    topLevelField[.secondLevelField][.thirdLevelField][...]

舉例來說，如果是以下 RouteMatrixItem：

  "travelAdvisory": {
    "fuelConsumptionMicroliters": 0,
    "tollInfo": {
      "estimatedPrices": [
        {
          "currencyCode": "USD",
          "units": 4,
          "nanos": 400000000
        }
      ]
    }
  },

如要只傳回 RouteMatrixItem 的 tollInfo 欄位，欄位遮罩如下：

fields: ['travelAdvisory.tollInfo']

如要改為要求預估燃料消耗量，您的欄位遮罩如下所示：

fields: ['travelAdvisory.fuelConsumptionMicroliters']

如要同時要求這兩項資訊，欄位遮罩如下：

fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']

如要要求完整的一組旅遊警示，欄位遮罩如下所示：

fields: ['travelAdvisory']