Route - Get Route Matrix

參考

服務:: Maps

API 版本:: 1.0

使用來取得路線矩陣，其中顯示出發點和目的地清單中所有可能配對的行進時間和距離。

Get Route Matrix API 是 HTTP GET 要求，可計算來源和目的地清單中所有可能配對的行進時間和距離。不同於取得路線指示 API，其提供詳細的路線指示，此 API 著重於效率，方法是提供從每個來源到每個目的地的路由成本（行程時間和距離）。如需詳細資訊，請參閱 Azure 地圖服務路線服務的最佳做法。

針對每個指定的來源，服務會計算從該來源到每個指定目的地的路由成本。一組原點和一組目的地可以視為數據表的數據行和數據列標頭，而數據表中的每個數據格都包含從源數據行到該單元格目的地的路由成本。例如，假設一家食品送貨公司有20名司機，他們需要找到最接近的司機，才能從餐廳接貨。若要解決此使用案例，他們可以呼叫矩陣路由API。

針對每個路線，都會傳回行進時間和距離。您可以使用計算成本來判斷要使用路由方向 API 計算的詳細路由。

異步要求矩陣的大小上限為 700，而同步處理要求的大小上限為 100 （原點數目乘以目的地數目）。

提交同步路由矩陣要求

如果您的案例需要同步要求，且矩陣的大小上限小於或等於 100，您可能會想要提出同步要求。此 API 矩陣的大小上限 100（原點數目乘以目的地數目）。考慮到該條件約束，可能的矩陣維度範例包括：10x10、6x8、9x8（不需要正方形）。

GET https://atlas.microsoft.com/route/matrix/sync/json?api-version=1.0&subscription-key={subscription-key}

提交異步路由矩陣要求

異步 API 適用於處理大量相對複雜的路由要求。當您使用異步要求提出要求時，服務預設會在響應標頭的 [位置] 字段中傳回 202 回應碼以及重新導向 URL。應該定期檢查此 URL，直到響應資料或錯誤資訊可用為止。如果要求中的 waitForResults 參數設定為 true，則如果要求在 120 秒內完成，使用者會收到 200 回應。

此 API 矩陣的大小上限 700（原點數目乘以目的地數目）。考慮到該條件約束，可能的矩陣維度範例包括：50x10、10x10、28x25。 10x70 （不需要正方形）。

異步回應會儲存 24 小時。如果到期期間之後使用，重新導向 URL 會傳回 404 回應。

GET https://atlas.microsoft.com/route/matrix/json?api-version=1.0&subscription-key={subscription-key}

以下是一般異步操作順序：

用戶端會將路由矩陣 GET 要求傳送至 Azure 地圖服務
伺服器會以下欄其中一項回應：

HTTP 202 Accepted - 已接受路由矩陣要求。

HTTP Error - 處理路由矩陣要求時發生錯誤。這可能是 400 不正確的要求或任何其他錯誤狀態代碼。
如果成功接受矩陣路由要求，回應中的Location標頭會包含下載要求結果的URL。此狀態 URI 如下所示：

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}

用戶端在步驟 3 取得的下載 URL 上發出 GET 要求，以下載結果

下載同步處理結果

當您對路由矩陣同步 API 提出 GET 要求時，服務會傳回 200 回應碼，以取得成功的要求和響應數位。回應本文會包含數據，而且稍後將無法擷取結果。

下載異步結果

當要求發出 202 Accepted 回應時，系統會使用我們的異步管線來處理要求。系統會提供 URL，以在回應的位置標頭中檢查異步要求進度。此狀態 URI 如下所示：

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}

位置標頭提供的 URL 會在發出 GET 要求時傳回下列回應。

HTTP 202 Accepted - 已接受矩陣要求，但仍正在處理中。請稍後再試一次。

HTTP 200 OK - 矩陣要求已成功處理。回應本文包含所有結果。

GET https://atlas.microsoft.com/route/matrix/{format}?api-version=1.0

URI 參數

名稱	位於	必要	類型	Description
format	path	True	string	成功接受矩陣路由要求之後收到的矩陣標識碼。
api-version	query	True	string	Azure 地圖服務 API 的版本號碼。

要求標頭

名稱	必要	類型	Description
x-ms-client-id		string	指定要與 Microsoft Entra ID 安全性模型搭配使用的帳戶。它代表 Azure 地圖服務帳戶的唯一標識碼，而且可以從 Azure 地圖服務管理平面帳戶 API 擷取。若要在 Azure 地圖服務中使用 Microsoft Entra ID 安全性，請參閱下列文章以取得指引。

回應

名稱	類型	Description
200 OK	RouteMatrixResult	矩陣要求已成功處理。回應本文包含所有結果。
202 Accepted		僅支援異步要求。要求已接受：要求已接受進行處理。請使用位置標頭中的 URL 來重試或存取結果。標題 Location: string
Other Status Codes	ErrorResponse	發生未預期的錯誤。

名稱

類型

Description

200 OK

RouteMatrixResult

矩陣要求已成功處理。回應本文包含所有結果。

202 Accepted

僅支援異步要求。 要求已接受：要求已接受進行處理。請使用位置標頭中的 URL 來重試或存取結果。

標題

Location: string

Other Status Codes

ErrorResponse

發生未預期的錯誤。

安全性

AADToken

這些是 Entra OAuth 2.0 流程 Microsoft。與 Azure 角色型存取配對時，控制它可用來控制 Azure 地圖服務 REST API 的存取。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務資源帳戶或子資源的存取權。任何使用者、群組或服務主體都可以透過內建角色或由一或多個 Azure 地圖服務 REST API 許可權所組成的自定義角色來授與存取權。

若要實作案例，建議您檢視驗證概念。總而言之，此安全性定義會透過能夠針對特定 API 和範圍進行訪問控制的物件，提供模型化應用程式的解決方案。

筆記

此安全性定義需要使用 x-ms-client-id 標頭來指出應用程式要求存取的 Azure 地圖服務資源。這可以從地圖管理 API取得。

Authorization URL 專屬於 Azure 公用雲端實例。主權雲端具有唯一的授權 URL，Microsoft Entra ID 設定。 * 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 Azure 管理平面設定 Azure 角色型存取控制。 * Azure 地圖服務 Web SDK 的使用方式允許針對多個使用案例設定應用程式。

如需Microsoft身分識別平臺的詳細資訊，請參閱 Microsoft 身分識別平臺概觀。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

這是當您在 Azure 入口網站或使用 PowerShell、CLI、Azure SDK 或 REST API 建立 Azure 地圖服務帳戶時所佈建的共用密鑰。

使用此金鑰，任何應用程式都可以存取所有 REST API。換句話說，此金鑰可用來做為帳戶中核發的主要密鑰。

針對公開的應用程式，我們建議使用機密用戶端應用程式方法來存取 Azure 地圖服務 REST API，以便安全地儲存您的密鑰。

類型: apiKey
位於: query

SAS Token

這是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 azure 地圖服務資源列表 SAS 作業建立共用存取簽章令牌。

使用此令牌時，任何應用程式都有權使用 Azure 角色型訪問控制進行存取，並更精細地控制特定令牌的到期、速率和區域。換句話說，SAS 令牌可用來讓應用程式以比共用密鑰更安全的方式控制存取。

對於公開的應用程式，我們建議在對應帳戶資源上設定允許的來源特定清單，以限制轉譯濫用，並定期更新 SAS 令牌。

類型: apiKey
位於: header

範例

Successfully retrieve the status for a route matrix request

範例要求

HTTP

GET https://atlas.microsoft.com/route/matrix/11111111-2222-3333-4444-555555555555?api-version=1.0

範例回覆

狀態碼:: 200

{
  "formatVersion": "0.0.1",
  "matrix": [
    [
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 495,
            "travelTimeInSeconds": 134,
            "trafficDelayInSeconds": 0,
            "departureTime": "2018-07-27T22:55:29+00:00",
            "arrivalTime": "2018-07-27T22:57:43+00:00"
          }
        }
      },
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 647651,
            "travelTimeInSeconds": 26835,
            "trafficDelayInSeconds": 489,
            "departureTime": "2018-07-27T22:55:29+00:00",
            "arrivalTime": "2018-07-28T06:22:44+00:00"
          }
        }
      }
    ],
    [
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 338,
            "travelTimeInSeconds": 104,
            "trafficDelayInSeconds": 0,
            "departureTime": "2018-07-27T22:55:29+00:00",
            "arrivalTime": "2018-07-27T22:57:13+00:00"
          }
        }
      },
      {
        "statusCode": 200,
        "response": {
          "routeSummary": {
            "lengthInMeters": 647494,
            "travelTimeInSeconds": 26763,
            "trafficDelayInSeconds": 469,
            "departureTime": "2018-07-27T22:55:29+00:00",
            "arrivalTime": "2018-07-28T06:21:32+00:00"
          }
        }
      }
    ]
  ],
  "summary": {
    "successfulRoutes": 4,
    "totalRoutes": 4
  }
}

狀態碼:: 202

定義

名稱	Description
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
RouteLegSummary	路由區段的 Summary 物件。
RouteMatrix	矩陣結果物件
RouteMatrixResult	這個物件是從成功的路由矩陣呼叫傳回。例如，如果提供2個原點和3個目的地，則每個都有3個元素的陣列。每個元素的內容都取決於查詢中提供的選項。
RouteMatrixResultResponse	輸入矩陣中目前儲存格的回應物件。
RouteMatrixSummary	Summary 物件

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳細數據。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

RouteLegSummary

路由區段的 Summary 物件。

名稱	類型	Description
arrivalTime	string	路線或腿部的估計抵達時間。時間以UTC為單位。
batteryConsumptionInkWh	number	使用電耗模型估計千瓦時（kWh）的電力能耗。如果 vehicleEngineType 設定為電動，且指定 constantSpeedConsumptionInkWhPerHundredkm，則包含。 batteryConsumptionInkWh 的值包括回收的電力，因此可以是負數（這表示獲得能量）。如果同時指定 maxChargeInkWh 和 currentChargeInkWh，則會封存，以確保電池電量永遠不會超過 maxChargeInkWh。如果未指定 maxChargeInkWh 和 currentChargeInkWh，則會在耗用量計算中假設未受限制的回收。
departureTime	string	路線或腿部的估計出發時間。時間以UTC為單位。
fuelConsumptionInLiters	number	使用燃燒耗用量模型以升為單位的估計燃料耗用量。如果 vehicleEngineType 設定為燃燒，且指定 constantSpeedConsumptionInLitersPerHundredkm，則包含。值將是非負數。
historicTrafficTravelTimeInSeconds	integer	使用時間相依的歷史流量數據計算的預估行進時間。只有當 computeTravelTimeFor = 全部用於查詢時，才會包含。
lengthInMeters	integer	Length In Meters 屬性
liveTrafficIncidentsTravelTimeInSeconds	integer	使用即時速度數據計算的預估行進時間。只有當 computeTravelTimeFor = 全部用於查詢時，才會包含。
noTrafficTravelTimeInSeconds	integer	由於交通狀況（例如擁堵）而計算的估計行程時間，好像路線上沒有延誤。只有當 computeTravelTimeFor = 全部用於查詢時，才會包含。
trafficDelayInSeconds	integer	根據交通資訊，由即時事件造成的秒數估計延遲。對於規劃未來出發時間的航線，延誤一律為 0。若要使用不同類型的流量資訊傳回其他旅行時間，必須新增parameter computeTravelTimeFor=all。
travelTimeInSeconds	integer	估計的行進時間，以秒為單位屬性，其中包含由於即時流量造成的延遲。請注意，即使 traffic=false travelTimeInSeconds 仍然包含流量造成的延遲。如果 DepartAt 是未來，則會使用時間相依的歷史交通數據來計算行進時間。

RouteMatrix

矩陣結果物件

名稱	類型	Description
response	RouteMatrixResultResponse	輸入矩陣中目前儲存格的回應物件。
statusCode	integer	輸入矩陣中目前儲存格的 StatusCode 屬性。

RouteMatrixResult

這個物件是從成功的路由矩陣呼叫傳回。例如，如果提供2個原點和3個目的地，則每個都有3個元素的陣列。每個元素的內容都取決於查詢中提供的選項。

名稱	類型	Description
formatVersion	string	Format Version 屬性
matrix	RouteMatrix[]	結果為路由摘要的 2 維陣列。
summary	RouteMatrixSummary	Summary 物件

RouteMatrixResultResponse

輸入矩陣中目前儲存格的回應物件。

名稱	類型	Description
routeSummary	RouteLegSummary	路由區段的 Summary 物件。

RouteMatrixSummary

Summary 物件

名稱	類型	Description
successfulRoutes	integer	回應中成功的路由數目。
totalRoutes	integer	要求的路由總數。輸入矩陣中的儲存格數目。

共用方式為

Route - Get Route Matrix

提交同步路由矩陣要求

提交異步路由矩陣要求

下載同步處理結果

下載異步結果

URI 參數

要求標頭

回應

安全性

AADToken

筆記

範圍

subscription-key

SAS Token

範例

Successfully retrieve the status for a route matrix request

範例要求

範例回覆

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

RouteLegSummary

RouteMatrix

RouteMatrixResult

RouteMatrixResultResponse

RouteMatrixSummary

其他資源