Search - Get Search Address Reverse Batch

Используйте для отправки пакета запросов в API обратного адреса Поиск в одном асинхронном запросе.

API Get Search Address Reverse Batch — это HTTP-запросGET, который отправляет пакеты запросов Поиск API обратного адреса в одном асинхронном вызове API. Вы можете вызвать Get Search Address Reverse Batch API для выполнения асинхронно (асинхронно) или синхронно (sync). Асинхронный API позволяет вызывающей службе пакетировать до 10 000 запросов и синхронизировать API до 100 запросов.

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

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

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

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

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

• Он позволяет получить результаты в отдельном вызове (возможно несколько скачиваний).
• Асинхронный API оптимизирован для обеспечения надежности и не ожидается, что время ожидания истекло.
• Количество пакетных элементов для этого API ограничено 10 000 .

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

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

1. Клиент отправляет запрос обратной пакетной службы POST Поиск address в Azure Maps.

POST https://atlas.microsoft.com/search/address/reverse/batch/json?api-version=1.0&subscription-key={subscription-key}

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

   HTTP 202 Accepted — пакетный запрос принят.

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

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

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

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

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

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

{
    "batchItems": [
        {"query": "?query=48.858561,2.294911"},
        {"query": "?query=47.639765,-122.127896&radius=5000&limit=2"},
        {"query": "?query=47.621028,-122.348170"},
        {"query": "?query=43.722990,10.396695"},
        {"query": "?query=40.750958,-73.982336"}
    ]
}

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

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

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

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

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

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

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

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

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

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

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

Возвращаемое содержимое данных аналогично асинхронным и синхронным запросам. Если при скачивании результатов асинхронного пакетного запроса обработка пакета завершена, текст ответа содержит пакетный ответ. Этот пакетный ответ содержит компонент , указывающий summarytotalRequests , который был частью исходного пакетного запроса, и successfulRequestsт. е. запросы, которые были успешно выполнены. Пакетный ответ также содержит batchItems массив, содержащий ответ для каждого запроса в пакетном запросе. Будет batchItems содержать результаты в том же порядке, в котором исходные запросы были отправлены в пакетном запросе. Каждый элемент в batchItems содержит statusCode поля и response . Каждое response в batchItems относится к одному из следующих типов:

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

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

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

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "queryTime": 11
                },
                "addresses": [
                    {
                        "address": {
                            "country": "France",
                            "freeformAddress": "Avenue Anatole France, 75007 Paris"
                        },
                        "position": "48.858490,2.294820"
                    }
                ]
            }
        },
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "queryTime": 1
                },
                "addresses": [
                    {
                        "address": {
                            "country": "United States of America",
                            "freeformAddress": "157th Pl NE, Redmond WA 98052"
                        },
                        "position": "47.640470,-122.129430"
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

GET https://atlas.microsoft.com/search/address/reverse/batch/{format}?api-version=1.0

Параметры URI

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

Ответы

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

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 Maps в портал Azure или с помощью PowerShell, CLI, пакетов AZURE SDK или REST API.

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

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

Тип: apiKey
В: query

SAS Token

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

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

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

Тип: apiKey
В: header

Примеры

A Reverse Geocoding Batch API GET call containing 5 Reverse Geocoding API queries

GET https://atlas.microsoft.com/search/address/reverse/batch/11111111-2222-3333-4444-555555555555?api-version=1.0

{
  "summary": {
    "successfulRequests": 3,
    "totalRequests": 3
  },
  "batchItems": [
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 8,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "streetNumber": "7",
              "routeNumbers": [],
              "streetName": "Avenue Anatole France",
              "streetNameAndNumber": "7 Avenue Anatole France",
              "countryCode": "FR",
              "countrySubdivisionCode": "Île-de-France",
              "countrySecondarySubdivision": "Paris",
              "municipality": "Paris",
              "postalCode": "75007",
              "municipalitySubdivision": "7ème Arrondissement",
              "country": "France",
              "countryCodeISO3": "FRA",
              "freeformAddress": "7 Avenue Anatole France, Paris, 75007",
              "boundingBox": {
                "northEast": "48.858321,2.295167",
                "southWest": "48.858136,2.295027",
                "entity": "position"
              }
            },
            "position": "48.858231,2.295089"
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 8,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "routeNumbers": [],
              "countryCode": "US",
              "countrySubdivisionCode": "WA",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "municipality": "Redmond",
              "postalCode": "98052",
              "country": "United States",
              "countryCodeISO3": "USA",
              "freeformAddress": "Redmond, WA 98052",
              "boundingBox": {
                "northEast": "47.639765,-122.128661",
                "southWest": "47.639502,-122.129456",
                "entity": "position"
              },
              "countrySubdivisionName": "Washington"
            },
            "position": "47.639687,-122.128677"
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 19,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "streetNumber": "410",
              "routeNumbers": [],
              "streetName": "Thomas Street",
              "streetNameAndNumber": "410 Thomas Street",
              "countryCode": "US",
              "countrySubdivisionCode": "WA",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "municipality": "Seattle",
              "postalCode": "98109",
              "municipalitySubdivision": "Seattle, Lower Queen Anne",
              "country": "United States",
              "countryCodeISO3": "USA",
              "freeformAddress": "410 Thomas Street, Seattle, WA 98109",
              "boundingBox": {
                "northEast": "47.620954,-122.347601",
                "southWest": "47.620944,-122.348498",
                "entity": "position"
              },
              "extendedPostalCode": "981094621",
              "countrySubdivisionName": "Washington"
            },
            "position": "47.620945,-122.348175"
          }
        ]
      }
    }
  ]
}

Определения

Address

Адрес результата

AddressRanges

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

BoundingBox

Окно просмотра, которое охватывает результат, представленный левой верхней и нижней правой координатами окна просмотра.

BoundingBoxCompassNotation

Ограничивающий прямоугольник расположения.

Brand

Торговая марка, связанная с poi

Classification

Классификация возвращаемого poI

ClassificationName

Имя классификации

DataSources

Необязательный раздел. Идентификаторы ссылок для использования с API Get Поиск Polygon.

Entity

Источник типа сущности ограничивающего прямоугольника. Для обратного геокодирования это всегда равно положению.

EntryPoint

Точка входа для возвращаемого poI.

EntryPointType

Тип точки входа. Значение может быть main или дополнительным.

ErrorAdditionalInfo

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

ErrorDetail

Сведения об ошибке.

ErrorResponse

Сообщение об ошибке

GeographicEntityType

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

Geometry

Сведения о геометрической форме результата. Присутствует, только если тип == Geography.

LatLongPairAbbreviated

Расположение, представленное в виде широты и долготы с использованием коротких имен "lat" & "lon".

MatchType

Типы совпадений для операции обратного поиска по адресу.

OperatingHours

Часы работы для POI (достопримечательностей).

OperatingHoursTime

Представляет дату и время

OperatingHoursTimeRange

Открытый диапазон времени для дня

PointOfInterest

Сведения о возвращенных poI, включая такие сведения, как имя, телефон, URL-адрес и классификации.

PointOfInterestCategorySet

Категория POI

QueryType

Тип возвращаемого запроса: NEARBY или NON_NEAR.

Response

Результат запроса. SearchAddressResult, если запрос выполнен успешно, в противном случае — ErrorResponse.

ReverseSearchAddressBatchItem

Элемент, возвращенный вызовом обратной пакетной службы Поиск address.

ReverseSearchAddressBatchProcessResult

Этот объект возвращается из успешного вызова обратной пакетной службы Поиск address.

SearchAddressResultItem

Результирующий объект для ответа API Поиск.

SearchAddressResultType

Одно из двух значений:

• POI
• Улица
• Географический регион
• Точечный адрес
• Диапазон адресов
• Перекресток

SearchSummary

Объект Summary для ответа API Поиск.

Summary

Сводка результатов пакетного запроса