Route - Post Route Matrix

비동기 요청을 사용하여 출발지 및 대상 목록에서 가능한 모든 쌍의 이동 시간과 거리를 보여 주는 경로 행렬을 가져오는 데 사용합니다.

Post Route Matrix API는 비동기(비동기) 요청을 사용하여 원본 및 대상 위치에 정의된 경로 집합에 대한 경로 요약 행렬을 계산할 수 있는 HTTP POST 요청입니다. 동기(동기화) 요청을 만들려면 경로 매트릭스 동기화참조하세요. 지정된 모든 원본에 대해 서비스는 해당 원본에서 지정된 모든 대상으로 라우팅하는 비용을 계산합니다. 원본 집합 및 대상 집합은 테이블의 열 및 행 머리글로 간주할 수 있으며 테이블의 각 셀에는 원본에서 해당 셀의 대상으로 라우팅하는 비용이 포함됩니다. 예를 들어 음식 배달 회사에는 20명의 운전자가 있으며 식당에서 배달을 받을 가장 가까운 드라이버를 찾아야 한다고 가정해 보겠습니다. 이 사용 사례를 해결하기 위해 행렬 경로 API를 호출할 수 있습니다.

각 경로에 대해 이동 시간 및 거리가 반환됩니다. 계산 비용을 사용하여 경로 방향 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는 비교적 복잡한 라우팅 요청의 큰 볼륨을 처리하는 데 적합합니다. 비동기 요청을 사용하여 요청을 수행하면 기본적으로 서비스는 응답 헤더의 위치 필드에 있는 리디렉션 URL을 따라 202 응답 코드를 반환합니다. 이 URL은 응답 데이터 또는 오류 정보를 사용할 수 있을 때까지 주기적으로 확인해야 합니다. 요청의 waitForResults 매개 변수가 true로 설정된 경우 요청이 120초 미만으로 완료되면 사용자에게 200 응답이 표시됩니다.

이 API에 대한 행렬의 최대 크기는 700(원본 수에 대상 수를 곱한 값)입니다. 이러한 제약 조건을 염두에 두고 가능한 행렬 차원의 예는 50x10, 10x10, 28x25입니다. 10x70(정사각형일 필요는 없음).

비동기 응답은 24시간 동안 저장됩니다. 리디렉션 URL은 만료 기간 이후에 사용되는 경우 404 응답을 반환합니다.

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

다음은 일반적인 비동기 작업 시퀀스입니다.

1. 클라이언트가 Azure Maps에 경로 매트릭스 POST 요청을 보냅니다.

2. 서버는 다음 중 하나로 응답합니다.

   HTTP 202 Accepted - 경로 매트릭스 요청이 수락되었습니다.

   HTTP Error - Route Matrix 요청을 처리하는 동안 오류가 발생했습니다. 400 잘못된 요청 또는 기타 오류 상태 코드일 수 있습니다.

3. 행렬 경로 요청이 성공적으로 수락된 경우 응답의 위치 헤더에는 요청 결과를 다운로드할 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 응답을 발급하면 비동기 파이프라인을 사용하여 요청이 처리됩니다. 응답의 위치 헤더에서 비동기 요청의 진행률을 확인하는 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 - 행렬 요청이 성공적으로 처리되었습니다. 응답 본문에는 모든 결과가 포함됩니다.

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 역할 기반 액세스 제어는 하나 이상의 Azure Maps 리소스 계정 또는 하위 리소스에 대한 액세스를 지정하는 데 사용됩니다. 모든 사용자, 그룹 또는 서비스 주체는 Azure Maps REST API에 대한 하나 이상의 권한으로 구성된 기본 제공 역할 또는 사용자 지정 역할을 통해 액세스 권한을 부여할 수 있습니다.

시나리오를 구현하려면인증 개념을 확인하는 것이 좋습니다. 요약하자면, 이 보안 정의는 특정 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
Flow: implicit
권한 부여 URL: https://login.microsoftonline.com/common/oauth2/authorize

범위

subscription-key

Azure Portal에서 Azure Maps 계정 만들거나 PowerShell, CLI, Azure SDK 또는 REST API를 사용할 때 프로비전되는 공유 키입니다.

이 키를 사용하면 모든 애플리케이션이 모든 REST API에 액세스할 수 있습니다. 즉, 이 키를 발급된 계정에서 마스터 키로 사용할 수 있습니다.

공개적으로 노출된 애플리케이션의 경우 키를 안전하게 저장할 수 있도록 기밀 클라이언트 애플리케이션 접근 방식을 사용하여 Azure Maps REST API에 액세스하는 것이 좋습니다.

형식: apiKey
In(다음 안에): query

SAS Token

공유 액세스 서명 토큰은 Azure Portal, PowerShell, CLI, Azure SDK 또는 REST API를 통해 Azure 관리 평면을 통해 Azure Maps 리소스의 SAS 나열 작업에서 만들어집니다.

이 토큰을 사용하면 모든 애플리케이션이 Azure 역할 기반 액세스 제어를 사용하여 액세스하고 특정 토큰에 사용할 만료, 속도 및 지역에 대한 세분화된 제어 권한을 부여받습니다. 즉, SAS 토큰을 사용하여 애플리케이션이 공유 키보다 더 보안이 유지되는 방식으로 액세스를 제어할 수 있습니다.

공개적으로 노출된 애플리케이션의 경우 렌더링 남용을 제한하고 정기적으로 SAS 토큰을 갱신하도록 맵 계정 리소스 허용된 원본의 특정 목록을 구성하는 것이 좋습니다.

형식: apiKey
In(다음 안에): 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 기하 도형 형식입니다. 자세한 내용은 RFC 7946 참조하세요.

InclineLevel

스릴 넘치는 경로에 대한 언덕의 정도. 이 매개 변수는 routeType=thrilling과 함께만 사용할 수 있습니다.

JsonFormat

원하는 응답 형식입니다. json 형식만 지원됩니다.

RouteAvoidType

경로를 결정할 때 경로 계산에서 피해야 하는 항목을 지정합니다. 한 요청에서 여러 번 지정할 수 있습니다( 예: '&avoid=motorways&avoid=tollRoads&avoid=ferries'). 경로 범위 요청에서 이미UsedRoads 값을 사용하면 안 됩니다.

RouteLegSummary

경로 섹션에 대한 요약 개체입니다.

RouteMatrix

행렬 결과 개체

RouteMatrixQuery

좌표 행렬이 있는 개체입니다.

RouteMatrixResult

이 개체는 성공적인 Route Matrix 호출에서 반환됩니다. 예를 들어 2개의 원본과 3개의 대상이 제공되면 각각 3개의 요소가 있는 2개의 배열이 있습니다. 각 요소의 콘텐츠는 쿼리에 제공된 옵션에 따라 달라집니다.

RouteMatrixResultResponse

입력 행렬에 있는 현재 셀의 응답 개체입니다.

RouteMatrixSummary

요약 개체

RouteType

요청된 경로의 유형입니다.

SectionType

경로 응답에서 보고되는 섹션 유형을 지정합니다.

예를 들어 sectionType = 보행자에 적합한 구역만 반환됩니다. 한 요청에서 여러 번 지정할 수 있습니다(예: '§ionType=carTrain§ionType=pedestrian§ionType=motorway'). 기본 sectionType은 travelMode 입력을 참조합니다. 기본적으로 travelMode는 자동차로 설정됩니다.

TravelMode

요청된 경로에 대한 이동 모드입니다. 정의되지 않은 경우 기본값은 'car'입니다. 요청된 travelMode를 전체 경로에 사용할 수 없습니다. 요청된 travelMode를 특정 섹션에 사용할 수 없는 경우 해당 섹션에 대한 응답의 travelMode 요소는 "other"가 됩니다. 여행 모드 버스, 오토바이, 택시 및 밴은 BETA 기능입니다. 일부 영역에서는 전체 제한 데이터를 사용할 수 없습니다.

VehicleLoadType

위험 물질로 분류되고 일부 도로에서 제한될 수 있는 화물 유형입니다. 사용 가능한 vehicleLoadType 값은 미국 Hazmat 클래스 1~9와 다른 국가/지역에서 사용할 일반 분류입니다. USHazmat로 시작하는 값은 미국 라우팅을 위한 것이고 다른 모든 국가/지역에는 otherHazmat을 사용해야 합니다. vehicleLoadType을 여러 번 지정할 수 있습니다. 이 매개 변수는 현재 travelMode=truck에 대해서만 고려됩니다.

WindingnessLevel

스릴 넘치는 경로에 대한 회전의 수준. 이 매개 변수는 routeType=thrilling과 함께만 사용할 수 있습니다.