Route - Post Route Matrix Async

Route Matrix Async API는 비동기(비동기) 요청을 사용하여 원본 및 대상 위치에 정의된 경로 집합에 대한 경로 요약 행렬을 계산할 수 있는 HTTP POST 요청입니다. 지정된 모든 원본에 대해 서비스는 해당 원본에서 지정된 모든 대상으로 라우팅하는 비용을 계산합니다. 원본 집합 및 대상 집합은 테이블의 열 및 행 머리글로 간주할 수 있으며 테이블의 각 셀에는 원본에서 해당 셀의 대상으로 라우팅하는 비용이 포함됩니다. 경로 매트릭스는 운전, 도보 및 트럭 경로에 대해 계산할 수 있습니다.

경로 매트릭스는 TSP(Traveling Salesman 문제) 및 VRP(차량 라우팅 문제)를 해결하는 데 가장 일반적으로 사용되는 여러 유형의 애플리케이션에서 사용됩니다. 행렬의 각 출발지-대상 쌍에 대해 이동 시간과 거리가 반환됩니다. 계산 비용을 사용하여 경로 방향 API를 사용하여 계산할 자세한 경로를 결정할 수 있습니다.

비동기 요청에 대한 행렬의 최대 크기는 50000(원본 수에 대상 수를 곱한 값)입니다.

비동기 경로 매트릭스 요청 제출

비동기 API는 비교적 복잡한 라우팅 요청의 큰 볼륨을 처리하는 데 적합합니다. 비동기 요청을 사용하여 요청을 수행하면 기본적으로 서비스는 Azure Maps 지리 엔드포인트 '{geography}.atlas.microsoft.com 응답 헤더의 operation-Location 필드에 있는 URL을 따라 202 응답 코드를 반환합니다. 이 URL은 상태가 성공될 때까지 주기적으로 확인해야 합니다.

이 API에 대한 행렬의 최대 크기는 50000(원본 수에 대상 수를 곱한 값)입니다. 이러한 제약 조건을 염두에 두고 가능한 행렬 차원의 예는 500x100, 100x100, 280x170입니다. 100x50(정사각형일 필요는 없음).

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

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

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

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

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

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

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

3. 행렬 경로 요청이 성공적으로 수락된 경우 응답의 operation-location 헤더에는 요청 상태를 가져오는 URL이 포함됩니다. 이 상태 URI는 다음과 같습니다.

  GET https://atlas.microsoft.com/route/operations/{id}?api-version=2025-01-01?subscription-key={subscription-key}

4. 클라이언트가 3단계에서 가져온 resultUrl에 대해 GET 요청을 실행하여 결과를 가져옵니다.

  GET https://atlas.microsoft.com/route/operations/{id}/result?api-version=2025-01-01?subscription-key={subscription-key}

API 제한 사항

행렬의 비동기 처리는 무거운 경로 계산이 필요한 더 큰 행렬에 가장 적합합니다. 다음 제한 사항은 비동기 요청에 적용할 수 있습니다. 다음 표에 있는 행 중 요청의 매개 변수와 일치하는 행이 없으면 요청이 요구 사항을 충족하지 않으며 처리되지 않습니다.

POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01

URI 매개 변수

요청 헤더

Media Types: "application/geo+json"

요청 본문

Media Types: "application/geo+json"

응답

보안

AADToken

다음은 Microsoft Entra OAuth 2.0 흐름에 . Azure 역할 기반 액세스 컨트롤과 쌍을 이루는 경우 Azure Maps REST API에 대한 액세스를 제어하는 데 사용할 수 있습니다. Azure 역할 기반 액세스 제어는 하나 이상의 Azure Maps 리소스 계정 또는 하위 리소스에 대한 액세스를 지정하는 데 사용됩니다. 모든 사용자, 그룹 또는 서비스 주체는 Azure Maps REST API에 대한 하나 이상의 권한으로 구성된 기본 제공 역할 또는 사용자 지정 역할을 통해 액세스 권한을 부여할 수 있습니다.

시나리오를 구현하려면인증 개념을 확인하는 것이 좋습니다. 요약하자면, 이 보안 정의는 특정 API 및 범위에 대한 액세스 제어가 가능한 개체를 통해 애플리케이션을 모델링하기 위한 솔루션을 제공합니다.

형식: oauth2
Flow: implicit
권한 부여 URL: https://login.microsoftonline.com/common/oauth2/authorize

범위

subscription-key

Azure Portal, PowerShell, CLI, Azure SDK 또는 REST API를 통해 Azure 관리 평면을 통해 Azure Maps 리소스를 만들 때 프로비전되는 공유 키입니다.

이 키를 사용하면 모든 애플리케이션이 모든 REST API에 액세스할 수 있는 권한이 부여됩니다. 즉, 이러한 키는 현재 발급된 계정의 마스터 키로 처리될 수 있습니다.

공개적으로 노출된 애플리케이션의 경우 이 키를 안전하게 저장할 수 있는 Azure Maps REST API의 서버-서버 액세스를 사용하는 것이 좋습니다.

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

SAS Token

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

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

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

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

예제

Submit an asynchronous request for matrix

POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            9.15049,
            45.458545
          ],
          [
            11.050541,
            45.403337
          ]
        ]
      },
      "properties": {
        "pointType": "origins"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            11.499931,
            48.149853
          ],
          [
            14.538226,
            50.033688
          ]
        ]
      },
      "properties": {
        "pointType": "destinations"
      }
    }
  ],
  "departAt": "2022-12-19T16:39:57+01:00",
  "optimizeRoute": "fastest",
  "traffic": "historical",
  "travelMode": "truck",
  "avoid": [
    "unpavedRoads"
  ]
}

Operation-Location: https://atlas.microsoft.com/route/operations/bc3f9365-3ee0-4564-aa27-825016325557?api-version=2025-01-01

정의

AdrTunnelRestrictionCodeEnum

ADR 터널 제한 코드입니다. ADR은 도로로 위험물의 국제 운송에 관한 유럽 협정입니다. ADR 터널 제한 코드는 차량이 위험물 운송에 대한 제한 사항이 있는 터널을 통과할 수 있는지 여부를 결정하는 데 사용됩니다.

FeaturesItemTypeEnum

GeoJSON 형식을 지정합니다. 유일하게 지원되는 개체 유형은 Feature입니다. 자세한 내용은 RFC 7946참조하세요.

FeatureTypeEnum

GeoJSON 형식을 지정합니다. 지원되는 유일한 개체 형식은 FeatureCollection. 자세한 내용은 RFC 7946참조하세요.

GeoJsonMultiPoint

유효한 GeoJSON MultiPoint 기하 도형 형식입니다. 자세한 내용은 RFC 7946 참조하세요.

InputRouteMatrixFeaturesItem

GeoJSON MultiPoint 기능 개체의 입력 원본 및 대상 지점 및 추가 속성을 지정합니다. 자세한 내용은 RFC 7946 참조하세요.

InputRouteMatrixProperties

입력 행렬의 속성 개체를 지정합니다.

MapsErrorDetail

오류 세부 정보입니다.

MapsErrorResponse

실패한 작업에 대한 오류 세부 정보를 반환하는 Azure Maps API에 대한 일반적인 오류 응답입니다.

MapsInnerError

오류에 대한 현재 개체보다 더 구체적인 정보를 포함하는 개체입니다.

RouteMatrixAsyncOptimizeRouteEnum

경로를 최적화하는 데 사용할 매개 변수를 지정합니다. 정의되지 않은 경우 기본값은 이동 시간을 최소화하기 위해 경로를 반환하는 "가장 빠른"입니다.

예: "optimizeRoute":"shortest"

RouteMatrixAsyncRequest

출발지 및 대상 목록에서 가능한 모든 쌍의 이동 시간과 거리를 보여 주는 경로 행렬을 가져오는 데 사용합니다. 기능 개체 및 추가 속성을 GeoJSON. 자세한 내용은 RFC 7946 참조하세요.

RouteMatrixAvoidEnum

경로를 결정할 때 경로 계산에서 적용해야 하는 제한을 지정합니다. 요청에서 여러 값을 지원하지 않으며 운전 및 트럭 travelMode에 대해서만 지원됩니다.

RouteMatrixTrafficEnum

트래픽이 컴퓨팅 경로에 고려되는 방식을 지정합니다.

기본값: historical

RouteMatrixTravelModeEnum

행렬을 계산할 때 고려할 이동 프로필을 지정합니다. 지정하지 않으면 기본값은 "운전"입니다.

예: "travelMode":"운전"

RouteMatrixTypeEnum

입력 매트릭스의 원본 MultiPoint 유형 및 대상 MultiPoint 형식을 지정합니다.

RouteMatrixVehicleSpec

경로 매트릭스를 계산할 때 고려할 차량 높이, 무게, 최대 속도, 화물 유형 등과 같은 차량 특성을 지정합니다. 이를 통해 낮은 교량 통관, 도로 제한, 어려운 오른쪽 회전을 방지하여 차량 사양에 따라 최적화된 경로를 제공할 수 있습니다. 차량 특성은 vehicleSpec 속성 내에 지정됩니다.

VehicleLoadTypeEnum

위험 물질로 분류되고 일부 도로에서 제한될 수 있는 화물 유형입니다. 사용 가능한 vehicleLoadType 값은 미국 Hazmat 클래스 1~9와 다른 국가에서 사용할 일반 분류입니다. USHazmat로 시작하는 값은 미국 라우팅을 위한 값이며 다른 모든 국가에서는 otherHazmat을 사용해야 합니다. vehicleLoadType은 요청에서 여러 값을 지원합니다.