Route - Get Route Matrix

リファレンス

サービス:: Maps

API バージョン:: 1.0

出発地と目的地のリスト内のすべての可能なペアの移動時間と距離を示すルートマトリックスを取得するために使用します。

Get Route Matrix API は、出発地と目的地のリスト内のすべての可能なペアの移動時間と距離を計算する HTTP GET 要求です。詳細なルート指示を提供するルートルート案内の取得 API とは異なり、この API は、各出発地からすべての目的地へのルーティングのコスト (移動時間と距離) を提供することで、効率に重点を置いています。詳細については、「Azure Maps Route サービスのベストプラクティス」を参照してください。

サービスは、指定された配信元ごとに、その配信元から特定の宛先へのルーティングのコストを計算します。起点のセットと宛先のセットは、テーブルの列ヘッダーと行ヘッダーと考えることができます。テーブル内の各セルには、そのセルの起点から宛先へのルーティングコストが含まれます。たとえば、食品配達会社に 20 人のドライバーがあり、レストランから配送を受け取るために最も近いドライバーを見つける必要があるとします。このユースケースを解決するために、Matrix Route API を呼び出すことができます。

ルートごとに、移動時間と距離が返されます。計算されたコストを使用して、Route Directions 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 は、比較的複雑なルーティング要求の大量の処理に適しています。非同期要求を使用して要求を行うと、既定では、サービスは応答ヘッダーの Location フィールドのリダイレクト URL に沿って 202 応答コードを返します。この URL は、応答データまたはエラー情報が使用可能になるまで定期的に確認する必要があります。要求 waitForResults パラメーターが true に設定されている場合、要求が 120 秒以内に完了すると、ユーザーは 200 応答を受け取ります。

この API のマトリックスの最大サイズは、700 です (起点の数に宛先の数を乗算)。この制約を念頭に置いて、可能な行列ディメンションの例は 50x10、10x10、28x25 です。 10 x 70 (正方形である必要はありません)。

非同期応答は、24 時間格納されます。リダイレクト URL は、有効期限後に使用された場合、404 応答を返します。

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

非同期操作の一般的なシーケンスを次に示します。

クライアントがルートマトリックス GET 要求を Azure Maps に送信する
サーバーは、次のいずれかの応答を返します。

HTTP 202 Accepted - ルートマトリックス要求が受け入れされました。

HTTP Error - ルートマトリックス要求の処理中にエラーが発生しました。これは、400 Bad Request またはその他のエラー状態コードのいずれかです。
マトリックスルート要求が正常に受け入れられた場合、応答の 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 応答を発行すると、非同期パイプラインを使用して要求が処理されます。応答の location ヘッダーで非同期要求の進行状況を確認する URL が表示されます。この状態 URI は次のようになります。

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

location ヘッダーによって提供される URL は、GET 要求が発行されたときに次の応答を返します。

HTTP 202 Accepted - マトリックス要求は受け入れられましたが、まだ処理中です。しばらくしてからやり直してください。

HTTP 200 OK - マトリックス要求が正常に処理されました。応答本文には、すべての結果が含まれています。

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

URI パラメーター

名前	/	必須	型	説明
format	path	True	string	マトリックスルート要求が正常に受け入れられた後に受信されたマトリックス ID。
api-version	query	True	string	Azure Maps API のバージョン番号。

要求ヘッダー

名前	必須	型	説明
x-ms-client-id		string	Microsoft Entra ID セキュリティモデルと組み合わせて使用するアカウントを指定します。これは Azure Maps アカウントの一意の ID を表し、Azure Maps 管理プレーンアカウント API から取得できます。 Azure Maps で Microsoft Entra ID セキュリティを使用するには、ガイダンス次の記事を参照してください。

応答

名前	型	説明
200 OK	RouteMatrixResult	マトリックス要求が正常に処理されました。応答本文には、すべての結果が含まれています。
202 Accepted		非同期要求でのみサポートされます。受け入れ済み要求: 要求は処理のために受け入れ済みです。 Location ヘッダーの URL を使用して、再試行するか、結果にアクセスしてください。ヘッダー Location: string
Other Status Codes	ErrorResponse	予期しないエラーが発生しました。

名前

型

説明

200 OK

RouteMatrixResult

マトリックス要求が正常に処理されました。応答本文には、すべての結果が含まれています。

202 Accepted

非同期要求でのみサポートされます。 受け入れ済み要求: 要求は処理のために受け入れ済みです。 Location ヘッダーの URL を使用して、再試行するか、結果にアクセスしてください。

ヘッダー

Location: string

Other Status Codes

ErrorResponse

予期しないエラーが発生しました。

セキュリティ

AADToken

これらは、Microsoft Entra OAuth 2.0 フローです。 Azure ロールベースアクセス制御と組み合わせて使用すると、Azure Maps REST API へのアクセスを制御できます。 Azure ロールベースのアクセス制御は、1 つ以上の Azure Maps リソースアカウントまたはサブリソースへのアクセスを指定するために使用されます。 Azure Maps REST API に対する 1 つ以上のアクセス許可で構成される組み込みロールまたはカスタムロールを使用して、任意のユーザー、グループ、またはサービスプリンシパルにアクセス権を付与できます。

シナリオを実装するには、認証の概念表示することをお勧めします。要約すると、このセキュリティ定義は、特定の API とスコープに対するアクセス制御が可能なオブジェクトを介してアプリケーションをモデル化するためのソリューションを提供します。

筆記

このセキュリティ定義 では、x-ms-client-id ヘッダー 使用して、アプリケーションがアクセスを要求している Azure Maps リソースを示す必要があります。これは、Maps 管理 APIから取得できます。

Authorization URL は、Azure パブリッククラウドインスタンスに固有です。ソブリンクラウドには、一意の承認 URL と Microsoft Entra ID 構成があります。 * Azure ロールベースのアクセス制御は、Azure portal、PowerShell、CLI、Azure SDK、または REST API を使用して、Azure 管理プレーンから構成されます。 * Azure Maps Web SDK を使用すると、複数のユースケースに対するアプリケーションの構成ベースのセットアップが可能になります。

Microsoft ID プラットフォームの詳細については、「Microsoft ID プラットフォームの概要」を参照してください。

型: oauth2
フロー: implicit
Authorization URL (承認 URL): https://login.microsoftonline.com/common/oauth2/authorize

スコープ

名前	説明
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

これは、Azure portal で、または PowerShell、CLI、Azure SDK、または REST API を使用して Azure Maps アカウントを作成場合にプロビジョニングされる共有キーです。

このキーを使用すると、すべてのアプリケーションがすべての REST API にアクセスできます。つまり、このキーは、発行されたアカウントのマスターキーとして使用できます。

パブリックに公開されているアプリケーションの場合は、キーを安全に格納できるように、機密クライアントアプリケーションアプローチを使用して Azure Maps REST API にアクセスすることをお勧めします。

型: apiKey
/: query

SAS Token

これは、Azure portal、PowerShell、CLI、Azure SDK、または REST API を介して Azure 管理プレーンを介して、Azure Maps リソースのリスト SAS 操作から作成される Shared Access Signature トークンです。

このトークンを使用すると、すべてのアプリケーションは、Azure ロールベースのアクセス制御と、特定のトークンに対する使用の有効期限、レート、およびリージョンに対するきめ細かな制御を使用してアクセスすることが承認されます。つまり、SAS トークンを使用して、アプリケーションが共有キーよりもセキュリティで保護された方法でアクセスを制御できるようにします。

パブリックに公開されているアプリケーションの場合は、Map アカウントリソースの許可された配信元の特定の一覧を構成し、レンダリングの不正使用を制限し、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

定義

名前	説明
ErrorAdditionalInfo	リソース管理エラーの追加情報。
ErrorDetail	エラーの詳細。
ErrorResponse	エラー応答
RouteLegSummary	ルートセクションの概要オブジェクト。
RouteMatrix	Matrix の結果オブジェクト
RouteMatrixResult	このオブジェクトは、成功したルートマトリックス呼び出しから返されます。たとえば、2 つのオリジンと 3 つの変換先が指定されている場合、それぞれに 3 つの要素を含む 2 つの配列が存在します。各要素の内容は、クエリで提供されるオプションによって異なります。
RouteMatrixResultResponse	入力マトリックス内の現在のセルの Response オブジェクト。
RouteMatrixSummary	Summary オブジェクト

ErrorAdditionalInfo

リソース管理エラーの追加情報。

名前	型	説明
info	object	追加情報。
type	string	追加情報の種類。

ErrorDetail

エラーの詳細。

名前	型	説明
additionalInfo	ErrorAdditionalInfo[]	エラーの追加情報。
code	string	エラーコード。
details	ErrorDetail[]	エラーの詳細。
message	string	エラーメッセージ。
target	string	エラーターゲット。

ErrorResponse

エラー応答

名前	型	説明
error	ErrorDetail	エラーオブジェクト。

RouteLegSummary

ルートセクションの概要オブジェクト。

名前	型	説明
arrivalTime	string	ルートまたは区間の推定到着時間。時刻は UTC です。
batteryConsumptionInkWh	number	電力消費量モデルを使用したキロワット時 (kWh) の推定電力消費量。 vehicleEngineType が電気に設定され、constantSpeedConsumptionInkWhPerHundredkm が指定されている場合に含まれます。 batteryConsumptionInkWh の値には、再充電された電気エネルギーが含まれているため、負の値 (エネルギーの増加を示します) になる可能性があります。 maxChargeInkWh と currentChargeInkWh の両方が指定されている場合、バッテリの充電レベルが maxChargeInkWh を超えないように、再循環が制限されます。 maxChargeInkWh も currentChargeInkWh も指定されていない場合、消費計算では制約のない回復が想定されます。
departureTime	string	ルートまたは区間の推定出発時間。時刻は UTC です。
fuelConsumptionInLiters	number	燃焼消費モデルを用いた推定燃料消費量(リットル単位)。 vehicleEngineType が燃焼に設定され、constantSpeedConsumptionInLitersPerHundredkm が指定されている場合に含まれます。値は負以外になります。
historicTrafficTravelTimeInSeconds	integer	時間依存の履歴トラフィックデータを使用して計算された推定移動時間。 computeTravelTimeFor = all がクエリで使用されている場合にのみ含まれます。
lengthInMeters	integer	Length In Meters プロパティ
liveTrafficIncidentsTravelTimeInSeconds	integer	リアルタイム速度データを使用して計算された推定移動時間。 computeTravelTimeFor = all がクエリで使用されている場合にのみ含まれます。
noTrafficTravelTimeInSeconds	integer	交通状況 (輻輳など) により、ルートに遅延がないかのように計算された推定移動時間。 computeTravelTimeFor = all がクエリで使用されている場合にのみ含まれます。
trafficDelayInSeconds	integer	トラフィック情報に従ってリアルタイムインシデントによって発生した推定遅延 (秒)。将来の出発時刻で計画されているルートの場合、遅延は常に 0 です。さまざまな種類のトラフィック情報を使用して追加の移動時間を返すには、パラメーター computeTravelTimeFor=all を追加する必要があります。
travelTimeInSeconds	integer	リアルタイムトラフィックによる遅延を含む推定移動時間 (秒)。 traffic=false travelTimeInSeconds の場合でも、トラフィックによる遅延が含まれていることに注意してください。 DepartAt が将来の場合、移動時間は時間依存の履歴トラフィックデータを使用して計算されます。

RouteMatrix

Matrix の結果オブジェクト

名前	型	説明
response	RouteMatrixResultResponse	入力マトリックス内の現在のセルの Response オブジェクト。
statusCode	integer	入力マトリックス内の現在のセルの StatusCode プロパティ。

RouteMatrixResult

このオブジェクトは、成功したルートマトリックス呼び出しから返されます。たとえば、2 つのオリジンと 3 つの変換先が指定されている場合、それぞれに 3 つの要素を含む 2 つの配列が存在します。各要素の内容は、クエリで提供されるオプションによって異なります。

名前	型	説明
formatVersion	string	[バージョンの書式設定] プロパティ
matrix	RouteMatrix[]	ルートの概要の 2 次元配列としての結果。
summary	RouteMatrixSummary	Summary オブジェクト

RouteMatrixResultResponse

入力マトリックス内の現在のセルの Response オブジェクト。

名前	型	説明
routeSummary	RouteLegSummary	ルートセクションの概要オブジェクト。

RouteMatrixSummary

Summary オブジェクト

名前	型	説明
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

その他のリソース

次の方法で共有

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

その他のリソース

同期ルートマトリックス要求の送信

非同期ルートマトリックス要求を送信する