Route - Post Route Matrix Async

API Route Matrix Async — это запрос HTTP POST, который позволяет вычислять матрицу сводок маршрутов для набора маршрутов, определенных источниками и целевыми расположениями, с помощью асинхронного (асинхронного) запроса. Для каждого заданного источника служба вычисляет стоимость маршрутизации из этого источника в каждое заданное место назначения. Набор источников и набор назначений можно рассматривать как заголовки столбцов и строк таблицы, а каждая ячейка в таблице содержит затраты на маршрутизацию от источника к месту назначения для этой ячейки. Матрицы маршрутов можно вычислить для вождения, ходьбы и грузовиков маршрутов.

Матрицы маршрутов используются в нескольких разных типах приложений, чаще всего для решения проблемы с менеджером по маршрутизации транспортных средств (TSP) и проблемы маршрутизации транспортных средств (VRP). Для каждой пары назначения источника в матрице возвращаются время путешествия и расстояние. Вы можете использовать вычисляемые затраты, чтобы определить подробные маршруты для вычисления с помощью API маршрутов.

Максимальный размер матрицы для асинхронного запроса составляет 50000 (число источников, умноженное на число назначений).

Отправка асинхронного запроса матрицы маршрутов

Асинхронный API подходит для обработки больших объемов относительно сложных запросов маршрутизации. При выполнении запроса с помощью асинхронного запроса служба возвращает код ответа 202 по URL-адресу в поле operation-Location заголовка ответа с конечной точкой географической точки Azure Maps "{geography}.atlas.microsoft.com. Этот 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. Клиент отправляет запрос Route Matrix POST в Azure Maps

2. Сервер ответит на одно из следующих действий:

   HTTP 202 Accepted — запрос матрицы маршрутов был принят.

   HTTP Error . Произошла ошибка при обработке запроса "Матрица маршрутов". Это может быть либо 400 недопустимый запрос, либо любой другой код состояния ошибки.

3. Если запрос matrix Route был принят успешно, заголовок operation-location в ответе содержит URL-адрес, чтобы получить состояние запроса. Этот универсальный код ресурса (URI) состояния выглядит следующим образом:

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

4. Клиент выдает запрос GET на результатUrl, полученный на шаге 3, чтобы получить результаты

  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 его можно использовать для управления доступом к REST API Azure Maps. Управление доступом на основе ролей Azure используется для назначения доступа к одной или нескольким учетным записям ресурсов Azure Maps или вложенным ресурсам. Доступ к любому пользователю, группе или субъекту-службе можно предоставить через встроенную роль или пользовательскую роль, состоящую из одного или нескольких разрешений для REST API Azure Maps.

Для реализации сценариев рекомендуется просматривать концепции проверки подлинности . В целом, это определение безопасности предоставляет решение для моделирования приложений через объекты, способные управлять доступом в определенных API и областях.

Тип: oauth2
Flow: implicit
URL-адрес авторизации: https://login.microsoftonline.com/common/oauth2/authorize

Области

subscription-key

Это общий ключ, подготовленный при создании ресурса Azure Maps через плоскость управления Azure с помощью портала Azure, PowerShell, CLI, пакетов SDK Azure или REST API.

С помощью этого ключа любой приложению разрешен доступ ко всем REST API. Другими словами, они в настоящее время могут рассматриваться как главные ключи учетной записи, для которой они выданы.

Для общедоступных приложений мы рекомендуем использовать доступ к REST API Azure Maps на сервере, где этот ключ можно безопасно хранить.

Тип: apiKey
В: header

SAS Token

Это маркер подписанного URL-адреса создается из операции SAS списка на ресурсе Azure Maps через плоскость управления Azure с помощью портала Azure, PowerShell, CLI, пакетов SDK Azure или REST API.

С помощью этого маркера любой приложению разрешен доступ с помощью управления доступом на основе ролей Azure и точного управления сроком действия, скоростью и регионами, используемыми для конкретного маркера. Другими словами, маркер SAS можно использовать для разрешения приложений управлять доступом более защищенным способом, чем общий ключ.

Для общедоступных приложений мы рекомендуем настроить определенный список разрешенных источников в ресурсе учетной записи карты карты, чтобы ограничить злоупотребление отрисовкой и регулярно обновлять маркер SAS.

Тип: apiKey
В: 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

Распространенный ответ об ошибке для API Azure Maps для возврата сведений об ошибке для неудачных операций.

MapsInnerError

Объект, содержащий более конкретные сведения, чем текущий объект об ошибке.

RouteMatrixAsyncOptimizeRouteEnum

Задает параметр, используемый для оптимизации маршрута. Если это не определено, значение по умолчанию — "самый быстрый", который возвращает маршрут, чтобы свести к минимуму время путешествия.

Пример: "optimizeRoute":"shortest"

RouteMatrixAsyncRequest

Используйте для получения матрицы маршрутов, показывающую время и расстояние для всех возможных пар в списке источников и назначения. GeoJSON объект компонента и дополнительные свойства. Дополнительные сведения см. в RFC 7946.

RouteMatrixAvoidEnum

Указывает ограничения, которые следует учитывать при определении маршрута. Избегайте поддержки нескольких значений в запросе и поддерживается только для вождения и грузовика travelMode.

RouteMatrixTrafficEnum

Указывает, как трафик считается для вычислительных маршрутов.

Значение по умолчанию: historical

RouteMatrixTravelModeEnum

Указывает профиль путешествия, который следует учитывать при вычислении матрицы. Если значение по умолчанию не указано, значение по умолчанию — "вождение".

Пример: "travelMode":"driving"

RouteMatrixTypeEnum

Указывает исходный тип MultiPoint и тип назначения MultiPoint для входной матрицы.

RouteMatrixVehicleSpec

Указывает атрибуты транспортного средства, такие как высота транспортного средства, вес, максимальная скорость, тип груза и т. д., которые следует учитывать при вычислении матрицы маршрутов. Это помогает избежать низкой очистки моста, ограничений дорожного движения, трудных поворотов, чтобы обеспечить оптимизированный маршрут на основе спецификаций транспортного средства. Атрибуты транспортного средства указываются в свойстве VehicleSpec.

VehicleLoadTypeEnum

Типы грузов, которые могут быть классифицированы как опасные материалы и ограничены некоторыми дорогами. Доступные значения vehicleLoadType — это классы US Hazmat 1–9, а также универсальные классификации для использования в других странах. Значения, начиная с USHazmat, предназначены для маршрутизации в США, а другие Хазматы должны использоваться для всех других стран. vehicleLoadType поддерживает несколько значений в запросе.