Route - Post Route Matrix

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

Post Route Matrix API は HTTP POST 要求であり、非同期 (非同期) 要求を使用して、出発地と宛先の場所によって定義された一連のルートのルートの概要のマトリックスを計算できます。 同期 (同期) 要求を行うには、「ルート後マトリックス同期 を参照してください。サービスは、指定された配信元ごとに、その配信元から特定の宛先へのルーティングのコストを計算します。 起点のセットと宛先のセットは、テーブルの列ヘッダーと行ヘッダーと考えることができます。テーブル内の各セルには、そのセルの起点から宛先へのルーティングコストが含まれます。 たとえば、食品配達会社に 20 人のドライバーがあり、レストランから配送を受け取るために最も近いドライバーを見つける必要があるとします。 このユース ケースを解決するために、Matrix Route API を呼び出すことができます。

ルートごとに、移動時間と距離が返されます。 計算されたコストを使用して、Route Directions API を使用して計算する詳細なルートを決定できます。

非同期要求のマトリックスの最大サイズは 700 で、同期要求の場合は 100 (配信元の数に宛先の数を乗算) 。

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

シナリオで同期要求が必要で、マトリックスの最大サイズが 100 以下の場合は、同期要求を行うことができます。 この API のマトリックスの最大サイズは、100 です (起点の数に宛先の数を乗算)。 この制約を念頭に置いて、可能な行列ディメンションの例は 10x10、6x8、9x8 です (正方形である必要はありません)。

POST 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 応答を返します。

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

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

1. クライアントがルート マトリックス POST 要求を Azure Maps に送信する

2. サーバーは、次のいずれかの応答を返します。

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

   HTTP Error - ルート マトリックス要求の処理中にエラーが発生しました。 これは、400 Bad Request またはその他のエラー状態コードのいずれかです。

3. マトリックス ルート要求が正常に受け入れられた場合、応答の Location ヘッダーには、要求の結果をダウンロードするための URL が含まれます。 この状態 URI は次のようになります。

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

4. クライアントは、手順 3 で取得したダウンロード URL に GET 要求を発行して結果をダウンロードします

同期結果のダウンロード

ルート マトリックス同期 API に対して POST 要求を行うと、成功した要求と応答配列に対して 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 - マトリックス要求が正常に処理されました。 応答本文には、すべての結果が含まれています。

POST https://atlas.microsoft.com/route/matrix/json?api-version=1.0

POST https://atlas.microsoft.com/route/matrix/json?api-version=1.0&waitForResults={waitForResults}&computeTravelTimeFor={computeTravelTimeFor}&sectionType={sectionType}&arriveAt={arriveAt}&departAt={departAt}&vehicleAxleWeight={vehicleAxleWeight}&vehicleLength={vehicleLength}&vehicleHeight={vehicleHeight}&vehicleWidth={vehicleWidth}&vehicleMaxSpeed={vehicleMaxSpeed}&vehicleWeight={vehicleWeight}&windingness={windingness}&hilliness={hilliness}&travelMode={travelMode}&avoid={avoid}&traffic={traffic}&routeType={routeType}&vehicleLoadType={vehicleLoadType}

URI パラメーター

要求ヘッダー

要求本文

応答

セキュリティ

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

スコープ

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 submit a route matrix request

POST https://atlas.microsoft.com/route/matrix/json?api-version=1.0&routeType=shortest

{
  "origins": {
    "type": "MultiPoint",
    "coordinates": [
      [
        4.85106,
        52.36006
      ],
      [
        4.85056,
        52.36187
      ]
    ]
  },
  "destinations": {
    "type": "MultiPoint",
    "coordinates": [
      [
        4.85003,
        52.36241
      ],
      [
        13.42937,
        52.50931
      ]
    ]
  }
}

{
  "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
  }
}

operation-Location: New URL to check the status of the long-running operation.

定義

ComputeTravelTime

さまざまな種類の交通情報 (なし、履歴、ライブ) と既定の最適推定移動時間を使用して、追加の移動時間を返すかどうかを指定します。

ErrorAdditionalInfo

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

ErrorDetail

エラーの詳細。

ErrorResponse

エラー応答

GeoJsonMultiPoint

有効な GeoJSON MultiPoint geometry 型。 詳細については、RFC 7946 を参照してください。

InclineLevel

スリル満点のルートのためのヒルネスの程度。 このパラメーターは、routeType=thrilling と組み合わせてのみ使用できます。

JsonFormat

応答の目的の形式。 json 形式のみがサポートされています。

RouteAvoidType

ルートを決定するときに、ルートの計算で回避する必要がある何かを指定します。 1 つの要求で複数回指定できます。たとえば、'&avoid=高速道路&avoid=tollRoads&avoid=ferrys' です。 ルート範囲要求では、値 alreadyUsedRoads を使用しないでください。

RouteLegSummary

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

RouteMatrix

Matrix の結果オブジェクト

RouteMatrixQuery

座標の行列を持つオブジェクト。

RouteMatrixResult

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

RouteMatrixResultResponse

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

RouteMatrixSummary

Summary オブジェクト

RouteType

要求されたルートの種類。

SectionType

ルート応答で報告されるセクションの種類を指定します。

たとえば、sectionType = 歩行者の場合、歩行者のみに適したセクションが返されます。 '§ionType=carTrain§ionType=歩行者§ionType=高速道路' など、1 つの要求で複数回指定できます。 既定の sectionType は travelMode 入力を参照します。 既定では、travelMode は car に設定されています

TravelMode

要求されたルートの移動モード。 定義されていない場合、既定値は 'car' です。 要求された travelMode は、ルート全体で使用できない場合があることに注意してください。 要求された travelMode が特定のセクションで使用できない場合、そのセクションの応答の travelMode 要素は "other" になります。 バス、オートバイ、タクシー、バンの移動モードはベータ機能であることに注意してください。 すべての領域で完全な制限データを使用できるわけではありません。

VehicleLoadType

危険物として分類され、一部の道路から制限される可能性のある貨物の種類。 使用可能な vehicleLoadType 値は、米国の Hazmat クラス 1 から 9 に加えて、他の国/地域で使用するための一般的な分類です。 USHazmat で始まる値は米国のルーティング用ですが、他のすべての国/地域には otherHazmat を使用する必要があります。 vehicleLoadType は複数回指定できます。 このパラメーターは現在、travelMode=truck に対してのみ考慮されます。

WindingnessLevel

スリル満点のルートのターンのレベル。 このパラメーターは、routeType=thrilling と組み合わせてのみ使用できます。