Route

Operations

Get Route Directions

Применимо к: ценовые категории S0 и S1.

Возвращает маршрут между источником и назначением, передавая вайпоинтс, если они указаны. Маршрут учитывает такие факторы, как текущий трафик и стандартные скорости передачи в запрошенный день недели и времени суток.

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

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

Get Route Range

API диапазона маршрутов (Исочроне)

Область применения: ценовая категория S1.

Эта служба вычисляет набор расположений, к которым можно получить доступ из исходной точки на основе указанного бюджета горючего, энергии, времени или расстояния. Граница многоугольника (или Исочроне) возвращается с ориентацией против часовой стрелки, а также с точным центром многоугольников, который был результатом исходной точки.

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

Post Route Directions

Применимо к: ценовые категории S0 и S1.

Возвращает маршрут между источником и назначением, передавая вайпоинтс, если они указаны. Маршрут учитывает такие факторы, как текущий трафик и стандартные скорости передачи в запрошенный день недели и времени суток.

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

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

Post Route Directions Batch

API пакетной обработки маршрутов

Область применения: ценовая категория S1.

API пакетной обработки маршрутов отправляет пакеты запросов в API направленных маршрутов , используя только один вызов API. API пакетной обработки маршрутов можно вызывать для асинхронного или синхронного запуска (синхронизации). Асинхронный API позволяет вызывающей стороне выполнять пакетную обработку до 700 запросов и API синхронизации до 100 запросов.

Отправка синхронного пакетного запроса

Для упрощенных пакетных запросов рекомендуется использовать синхронный API. Когда служба получает запрос, она будет отвечать сразу после вычисления элементов пакетной службы и не сможет получить результаты позже. Синхронный API возвратит ошибку времени ожидания (ответ 408), если запрос занимает больше 60 секунд. Число элементов пакета ограничено 100 для этого API.

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

Отправка асинхронного пакетного запроса

Асинхронный API подходит для обработки больших объемов относительно сложных запросов маршрутов.

  • Это позволяет получить результаты в отдельном вызове (возможно несколько Скачиваний).
  • Асинхронный API оптимизирован для обеспечения надежности и не должен выполняться в течение времени ожидания.
  • Число элементов пакета ограничено 700 для этого API.

При выполнении запроса с помощью асинхронного запроса служба по умолчанию возвращает код ответа 202 и URL-адрес перенаправления в поле Location заголовка ответа. Этот URL-адрес следует периодически проверять, пока не будут доступны данные ответа или сведения об ошибке. Асинхронные ответы хранятся в течение 14 дней. URL-адрес перенаправления возвращает ответ 404, если он использовался после истечения срока действия.

Обратите внимание, что асинхронный пакетный запрос является долго выполняющимся запросом. Ниже приведена типичная последовательность операций.

  1. Клиент отправляет пакетный запрос маршрутов POST к Azure Maps

  2. Сервер будет отвечать одним из следующих элементов:

    202 AcceptedЗапрос HTTP-Batch принят.

    HTTP Error — произошла ошибка при обработке запроса пакетной службы. Это может быть либо 400 Bad Request любой другой Error код состояния.

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

GET https://atlas.microsoft.com/batch/{batch-id}?api-version=1.0 Примечание. не забудьте добавить сведения о проверке подлинности (ключ подписки/azure_auth — см. раздел Безопасность) перед запуском URI состояния .
4. Клиент выдает GET запрос на URL-адрес скачивания , полученный на шаге 3, для скачивания результатов пакета.

Тело сообщения POST для пакетного запроса

Для отправки запросов с маршрутами будет использоваться запрос, в POST котором текст запроса будет содержать batchItems массив в json формате, а Content-Type для заголовка будет задано значение application/json . Ниже приведен пример текста запроса, содержащего три запроса маршрутов :

{
    "batchItems": [
        { "query": "?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false" },
        { "query": "?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest" },
        { "query": "?query=48.923159,-122.557362:32.621279,-116.840362" }
    ]
}

Запрос маршрутов в пакете — это просто частичный URL-адрес без протокола, базовый URL-адрес, путь, API-версия и ключ подписки. Он может принимать любой из поддерживаемых параметров URI направлений маршрута . Строковые значения в запросе с маршрутами должны быть правильно экранированы (например, символ должен быть экранирован с помощью символа \ ), а также должны быть правильно закодированы в URL-адресе.

Асинхронный API позволяет вызывающей стороне выполнять пакетную обработку до 700 запросов и API синхронизации до 100 запросов, а пакет должен содержать по крайней мере 1 запрос.

Скачать асинхронные результаты пакетной службы

Для загрузки асинхронных результатов пакетной службы будет выдан GET запрос на конечную точку скачивания пакета. Этот URL-адрес загрузки можно получить из Location заголовка успешного POST пакетного запроса и выглядит следующим образом:

https://atlas.microsoft.com/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

Ниже приведена типичная последовательность операций по скачиванию результатов пакета.

  1. Клиент отправляет GET запрос, используя URL-адрес скачивания.

  2. Сервер будет отвечать одним из следующих элементов:

    HTTP 202 Accepted -пакетный запрос принят, но еще обрабатывается. Повторите попытку через некоторое время.

    HTTP 200 OK -пакетный запрос успешно обработан. Текст ответа содержит все результаты пакета.

Модель пакетного ответа

Содержимое возвращаемых данных аналогично асинхронным и синхронным запросам. При скачивании результатов асинхронного пакетного запроса, если обработка пакета завершена, текст ответа содержит пакетный ответ. Этот пакетный ответ содержит summary компонент, который указывает totalRequests , что был частью исходного запроса пакета и successfulRequests т. е. запросов, которые были выполнены успешно. Пакетный ответ также содержит batchItems массив, который содержит ответ для каждого запроса в пакетном запросе. Объект batchItems будет содержать результаты в точно таком же порядке, в котором были отправлены исходные запросы в пакетном запросе. Каждый элемент в batchItems statusCode полях Contains и response . Каждый response в batchItems имеет один из следующих типов:

  • RouteDirectionsResponse — Если запрос успешно выполнен.

  • Error — Если запрос завершился ошибкой. codeВ этом случае ответ будет содержать и message .

Ниже приведен пример ответа пакетной службы с 1 успешным и 1 неудачным результатом:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}
Post Route Matrix

Область применения: ценовая категория S1.

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

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

Асинхронные ответы хранятся в течение 14 дней. URL-адрес перенаправления возвращает ответ 404, если он использовался после истечения срока действия.

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

Ниже приведена типичная последовательность асинхронных операций.

  1. Клиент отправляет запрос на запись матрицы маршрута в Azure Maps

  2. Сервер будет отвечать одним из следующих элементов:

    202 AcceptedЗапрос матрицы HTTP-Route принят.

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

  3. Если запрос на маршрут матрицы был успешно принят, заголовок Location в ответе содержит URL-адрес для скачивания результатов запроса. Этот URI состояния выглядит следующим образом:

  GET https://atlas.microsoft.com/route/matrix/{matrixId}?api-version=1.0?subscription-key={subscription-key}
  1. Клиент выдает запрос GET по URL-адресу скачивания, полученному на шаге 3, для скачивания результатов.

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

При выполнении запроса POST для API синхронизации матрицы Route служба возвращает код ответа 200 для успешного запроса и массива ответов. Текст ответа будет содержать данные, и вы не сможете получить результаты позже.

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

Когда запрос выдает 202 Accepted ответ, запрос обрабатывается с помощью нашего асинхронного конвейера. Вам будет предоставлен URL-адрес для проверки хода выполнения асинхронного запроса в заголовке расположения ответа. Этот URI состояния выглядит следующим образом:

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

URL-адрес, предоставленный в заголовке Location, будет возвращать следующие ответы при GET выдаче запроса.

202 AcceptedЗапрос HTTP-Matrix принят, но еще обрабатывается. Повторите попытку через некоторое время.

200 OKЗапрос HTTP-Matrix успешно обработан. Текст ответа содержит все результаты.