Route - Get Route Matrix

Ссылка

Служба:: Maps

Версия API:: 1.0

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

API Get Route Matrix — это запрос HTTP GET, который вычисляет время и расстояние для всех возможных пар в списке источников и назначений. В отличие от API получения маршрутов, который предоставляет подробные инструкции по маршруту, этот API фокусируется на эффективности, предоставляя затраты (время и расстояние) маршрутизации от каждого источника к каждому месту назначения. Дополнительные сведения см. в рекомендации по службе маршрутов Azure Maps.

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

Для каждого маршрута возвращаются время путешествия и расстояния. Вы можете использовать вычисляемые затраты, чтобы определить подробные маршруты для вычисления с помощью 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 подходит для обработки больших объемов относительно сложных запросов маршрутизации. При выполнении запроса с помощью асинхронного запроса служба возвращает код ответа 202 по URL-адресу перенаправления в поле "Расположение" заголовка ответа. Этот URL-адрес следует периодически проверять до тех пор, пока не будут доступны данные ответа или сведения об ошибках. Если параметр waitForResults в запросе имеет значение true, пользователь получит ответ 200, если запрос завершен в течение 120 секунд.

Максимальный размер матрицы для этого API составляет 700 (число источников, умноженное на число назначений). Учитывая это ограничение, примеры возможных измерений матрицы: 50x10, 10x10, 28x25. 10x70 (он не должен быть квадратным).

Асинхронные ответы хранятся в течение 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 недопустимый запрос, либо любой другой код состояния ошибки.
Если запрос matrix Route был принят успешно, заголовок location в ответе содержит URL-адрес для скачивания результатов запроса. Этот универсальный код ресурса (URI) состояния выглядит следующим образом:

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

Клиент выдает запрос GET по URL-адресу скачивания, полученному на шаге 3, чтобы скачать результаты

Скачивание результатов синхронизации

При выполнении запроса GET для API синхронизации матрицы маршрутов служба возвращает код ответа 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 — запрос матрицы успешно обработан. Текст ответа содержит все результаты.

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

Параметры URI

Имя	В	Обязательно	Тип	Описание
format	path	True	string	Идентификатор матрицы, полученный после успешного принятия запроса "Матрица маршрута".
api-version	query	True	string	Номер версии API Azure Maps.

Заголовок запроса

Имя	Обязательно	Тип	Описание
x-ms-client-id		string	Указывает, какая учетная запись предназначена для использования в сочетании с моделью безопасности идентификатора Microsoft Entra. Он представляет уникальный идентификатор учетной записи Azure Maps и может быть получен из API учетной записи уровня управления Azure Maps. Сведения о том, как использовать безопасность идентификатора Microsoft Entra в Azure Maps, см. в следующих статьях .

Ответы

Имя	Тип	Описание
200 OK	RouteMatrixResult	Запрос матрицы успешно обработан. Текст ответа содержит все результаты.
202 Accepted		Поддерживается только для асинхронного запроса. Запрос принят: запрос был принят для обработки. Используйте URL-адрес в заголовке расположения, чтобы повторить попытку или получить доступ к результатам. Заголовки Location: string
Other Status Codes	ErrorResponse	Произошла непредвиденная ошибка.

Имя

Тип

Описание

200 OK

RouteMatrixResult

Запрос матрицы успешно обработан. Текст ответа содержит все результаты.

202 Accepted

Поддерживается только для асинхронного запроса. Запрос принят: запрос был принят для обработки. Используйте URL-адрес в заголовке расположения, чтобы повторить попытку или получить доступ к результатам.

Заголовки

Location: string

Other Status Codes

ErrorResponse

Произошла непредвиденная ошибка.

Безопасность

AADToken

Это потоки Microsoft Entra OAuth 2.0. При паре с доступом на основе ролей Azure его можно использовать для управления доступом к REST API Azure Maps. Управление доступом на основе ролей Azure используется для назначения доступа к одной или нескольким учетным записям ресурсов Azure Maps или вложенным ресурсам. Доступ к любому пользователю, группе или субъекту-службе можно предоставить через встроенную роль или пользовательскую роль, состоящую из одного или нескольких разрешений для REST API Azure Maps.

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

Примечания

Для этого определения безопасности требуется использовать заголовок x-ms-client-id, чтобы указать, к какой ресурсу Azure Maps приложение запрашивает доступ. Это можно получить изAPI управления картами .

Authorization URL зависит от экземпляра общедоступного облака Azure. В национальных облаках есть уникальные URL-адреса авторизации и конфигурации идентификатора Microsoft Entra. * Управление доступом на основе ролей Azure настраивается с плоскости управления Azure с помощью портала Azure, PowerShell, CLI, пакетов SDK Azure или REST API. * Использование веб-пакета SDK Azure Maps позволяет настроить приложение на основе конфигурации для нескольких вариантов использования.

Дополнительные сведения о платформе удостоверений Майкрософт см. в обзоре платформы удостоверений Майкрософт.

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

Области

Имя	Описание
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

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

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

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

Тип: apiKey
В: query

SAS Token

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

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

Для общедоступных приложений мы рекомендуем настроить определенный список разрешенных источников в ресурсе учетной записи карты карты, чтобы ограничить злоупотребление отрисовкой и регулярно обновлять маркер 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	Объект результата матрицы
RouteMatrixResult	Этот объект возвращается из успешного вызова Route Matrix. Например, если предоставляются 2 источника и 3 назначения, в каждом из них будет 2 массива с 3 элементами. Содержимое каждого элемента зависит от параметров, предоставленных в запросе.
RouteMatrixResultResponse	Объект ответа текущей ячейки в входной матрице.
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 имеет значение electric и constantSpeedConsumptionInkWhPerHundredkm, указывается. Значение батареиConsumptionInkWh включает в себя восстановление электрической энергии и, следовательно, может быть отрицательным (что указывает на получение энергии). Если заданы значения maxChargeInkWh и currentChargeInkWh, восстановление будет ограничено, чтобы уровень заряда батареи никогда не превышал maxChargeInkWh. Если в расчете потребления не указано значение maxChargeInkWh или currentChargeInkWh, в вычислении потребления предполагается без ограничений восстановления.
departureTime	string	Предполагаемое время вылета маршрута или ноги. Время в формате UTC.
fuelConsumptionInLiters	number	Предполагаемое потребление топлива в литрах с помощью модели потребления топлива. Включается, если для транспортных средств задано значение сжигания и константыSpeedConsumptionInLitersPerHundredkm указано. Значение будет не отрицательным.
historicTrafficTravelTimeInSeconds	integer	Предполагаемое время поездки, вычисляемое с использованием данных исторического трафика, зависящих от времени. Включается только в том случае, если computeTravelTimeFor = все используется в запросе.
lengthInMeters	integer	Свойство Length In Meters
liveTrafficIncidentsTravelTimeInSeconds	integer	Предполагаемое время перемещения, вычисляемое с использованием данных скорости в режиме реального времени. Включается только в том случае, если computeTravelTimeFor = все используется в запросе.
noTrafficTravelTimeInSeconds	integer	Предполагаемое время движения, вычисляемое как если бы не было задержек в маршруте из-за условий дорожного движения (например, перегрузка). Включается только в том случае, если computeTravelTimeFor = все используется в запросе.
trafficDelayInSeconds	integer	Предполагаемая задержка в секундах, вызванная инцидентами в режиме реального времени в соответствии с данными о дорожном движении. Для маршрутов, запланированных с временем отъезда в будущем, задержки всегда 0. Чтобы вернуть дополнительное время путешествия с использованием различных типов сведений о трафике, необходимо добавить параметр computeTravelTimeFor=all.
travelTimeInSeconds	integer	Предполагаемое время перемещения в секундах, которое включает задержку из-за трафика в режиме реального времени. Обратите внимание, что даже если трафик=false travelTimeInSeconds по-прежнему включает задержку из-за трафика. Если в будущем Значение "Отступ" находится в будущем, время поездки вычисляется с использованием данных о времени, зависящих от времени, с учетом исторических данных трафика.

RouteMatrix

Объект результата матрицы

Имя	Тип	Описание
response	RouteMatrixResultResponse	Объект ответа текущей ячейки в входной матрице.
statusCode	integer	Свойство StatusCode для текущей ячейки в входной матрице.

RouteMatrixResult

Этот объект возвращается из успешного вызова Route Matrix. Например, если предоставляются 2 источника и 3 назначения, в каждом из них будет 2 массива с 3 элементами. Содержимое каждого элемента зависит от параметров, предоставленных в запросе.

Имя	Тип	Описание
formatVersion	string	Свойство Format Version
matrix	RouteMatrix[]	Результаты в виде 2-го массива сводок маршрутов.
summary	RouteMatrixSummary	Объект Summary

RouteMatrixResultResponse

Объект ответа текущей ячейки в входной матрице.

Имя	Тип	Описание
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

Дополнительные ресурсы