Search - Post Search Address Batch

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

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

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

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

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

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

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

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

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

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

POST https://atlas.microsoft.com/search/address/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/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=400 Broad St, Seattle, WA 98109&limit=3"},
        {"query": "?query=One, Microsoft Way, Redmond, WA 98052&limit=3"},
        {"query": "?query=350 5th Ave, New York, NY 10118&limit=1"},
        {"query": "?query=Pike Pl, Seattle, WA 98101&lat=47.610970&lon=-122.342469&radius=1000"},
        {"query": "?query=Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France&limit=1"}
    ]
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "query": "one microsoft way redmond wa 98052"
                },
                "results": [
                    {
                        "position": {
                            "lat": 47.63989,
                            "lon": -122.12509
                        }
                    }
                ]
            }
        },
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "query": "pike pl seattle wa 98101"
                },
                "results": [
                    {
                        "position": {
                            "lat": 47.60963,
                            "lon": -122.34215
                        }
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

POST https://atlas.microsoft.com/search/address/batch/json?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 можно использовать, чтобы разрешить приложениям управлять доступом более безопасным способом, чем общий ключ.

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

Тип: apiKey
В: header

Примеры

An Address Geocoding Batch API call containing 5 Address Geocoding API queries

POST https://atlas.microsoft.com/search/address/batch/json?api-version=1.0

{
  "batchItems": [
    {
      "query": "?query=400 Broad St, Seattle, WA 98109&limit=3"
    },
    {
      "query": "?query=One, Microsoft Way, Redmond, WA 98052&limit=3"
    },
    {
      "query": "?query=350 5th Ave, New York, NY 10118&limit=1"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 3,
    "totalRequests": 3
  },
  "batchItems": [
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "400 broad st seattle wa 98109",
          "queryType": "NON_NEAR",
          "queryTime": 127,
          "numResults": 3,
          "offset": 0,
          "totalResults": 9,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Point Address",
            "id": "US/PAD/p0/20843845",
            "score": 11.966,
            "address": {
              "streetNumber": "400",
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, South Lake Union, Lower Queen Anne",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "400 Broad Street, Seattle, WA 98109",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.62039,
              "lon": -122.34928
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.62129,
                "lon": -122.35061
              },
              "btmRightPoint": {
                "lat": 47.61949,
                "lon": -122.34795
              }
            },
            "entryPoints": [
              {
                "type": "main",
                "position": {
                  "lat": 47.61982,
                  "lon": -122.34886
                }
              }
            ]
          },
          {
            "type": "Street",
            "id": "US/STR/p0/388442",
            "score": 10.225,
            "address": {
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, South Lake Union",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109",
              "extendedPostalCode": "981094612",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Broad Street, Seattle, WA 98109",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.62001,
              "lon": -122.34843
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.61965,
                "lon": -122.34761
              },
              "btmRightPoint": {
                "lat": 47.62066,
                "lon": -122.349
              }
            }
          },
          {
            "type": "Street",
            "id": "US/STR/p0/388680",
            "score": 10.225,
            "address": {
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, Belltown",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109,98121",
              "extendedPostalCode": "981094991,981211117,981211237,981213206",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Broad Street, Seattle, WA",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.61691,
              "lon": -122.35251
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.61502,
                "lon": -122.35041
              },
              "btmRightPoint": {
                "lat": 47.61857,
                "lon": -122.35484
              }
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "one microsoft way redmond wa 98052",
          "queryType": "NON_NEAR",
          "queryTime": 169,
          "numResults": 2,
          "offset": 0,
          "totalResults": 3292,
          "fuzzyLevel": 2
        },
        "results": [
          {
            "type": "Street",
            "id": "US/STR/p0/1692663",
            "score": 10.225,
            "address": {
              "streetName": "Microsoft Way",
              "municipality": "Redmond",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "countrySubdivisionCode": "WA",
              "postalCode": "98052",
              "extendedPostalCode": "980526399,980528300",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Microsoft Way, Redmond, WA 98052",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.63989,
              "lon": -122.12509
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.63748,
                "lon": -122.12309
              },
              "btmRightPoint": {
                "lat": 47.64223,
                "lon": -122.13061
              }
            }
          },
          {
            "type": "Cross Street",
            "id": "US/XSTR/p1/4779971",
            "score": 8.506,
            "address": {
              "streetName": "Microsoft Way & 157th Avenue Northeast, Microsoft Way",
              "municipality": "Redmond",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "countrySubdivisionCode": "WA",
              "postalCode": "98052",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Microsoft Way & 157th Avenue Northeast, Redmond, WA 98052",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.63962,
              "lon": -122.13061
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.64052,
                "lon": -122.13194
              },
              "btmRightPoint": {
                "lat": 47.63872,
                "lon": -122.12928
              }
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "350 5th ave new york ny 10118",
          "queryType": "NON_NEAR",
          "queryTime": 233,
          "numResults": 1,
          "offset": 0,
          "totalResults": 8032,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Point Address",
            "id": "US/PAD/p0/48052000",
            "score": 14.334,
            "address": {
              "streetNumber": "350",
              "streetName": "5th Avenue",
              "municipalitySubdivision": "New York, Midtown South",
              "municipality": "New York, Manhattan",
              "countrySecondarySubdivision": "New York",
              "countryTertiarySubdivision": "Manhattan",
              "countrySubdivisionCode": "NY",
              "postalCode": "10118",
              "extendedPostalCode": "1011800",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "350 5th Avenue, NYC, NY 10118",
              "countrySubdivisionName": "New York"
            },
            "position": {
              "lat": 40.74817,
              "lon": -73.985
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 40.74907,
                "lon": -73.98619
              },
              "btmRightPoint": {
                "lat": 40.74727,
                "lon": -73.98381
              }
            },
            "entryPoints": [
              {
                "type": "main",
                "position": {
                  "lat": 40.74808,
                  "lon": -73.98482
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Operation-Location: URL to download the results of the long-running batch request.

Определения

Address

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

AddressRanges

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

BatchRequest

Этот тип представляет текст запроса для пакетной службы.

BatchRequestItem

Объект пакетного запроса

BoundingBox

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

BoundingBoxCompassNotation

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

Brand

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

Classification

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

ClassificationName

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

DataSources

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

Entity

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

EntryPoint

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

EntryPointType

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

ErrorAdditionalInfo

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

ErrorDetail

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

ErrorResponse

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

GeographicEntityType

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

Geometry

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

JsonFormat

Требуемый формат ответа. Поддерживается только формат json.

LatLongPairAbbreviated

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

MatchType

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

OperatingHours

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

OperatingHoursTime

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

OperatingHoursTimeRange

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

PointOfInterest

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

PointOfInterestCategorySet

Категория POI

QueryType

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

Response

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

SearchAddressBatchItem

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

SearchAddressBatchProcessResult

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

SearchAddressResultItem

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

SearchAddressResultType

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

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

SearchSummary

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

Summary

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