Поделиться через

клиентская библиотека пакета поиска Azure Maps для Python версии 1.0.0b2

  • Статья

Этот пакет содержит пакет SDK python для служб Azure Maps для поиска. Дополнительные сведения о службах Azure Maps см. здесь.

Исходный код | Справочная документация по | API Документация по продукту

Заявление об отказе

Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

Предварительные требования

Если вы используете Azure CLI, замените <resource-group-name> и <account-name> по своему выбору и выберите соответствующую ценовую категорию в зависимости от ваших потребностей с помощью <sku-name> параметра . Дополнительные сведения см. на этой странице.

az maps account create --resource-group <resource-group-name> --account-name <account-name> --sku <sku-name>

Установка пакета

Установите пакет SDK для поиска Azure Maps служб.

pip install azure-maps-search

Создание и проверка подлинности MapsSearchClient

Чтобы создать объект клиента для доступа к API поиска Azure Maps, потребуется объект учетных данных. Azure Maps клиент поиска также поддерживает два способа проверки подлинности.

1. Проверка подлинности с помощью учетных данных ключа подписки

Вы можете пройти проверку подлинности с помощью ключа подписки Azure Maps. После создания ключа подписки Azure Maps задайте значение ключа в качестве переменной среды: AZURE_SUBSCRIPTION_KEY. Затем передайте в AZURE_SUBSCRIPTION_KEY качестве credential параметра в экземпляр AzureKeyCredential.

from azure.core.credentials import AzureKeyCredential
from azure.maps.search import MapsSearchClient

credential = AzureKeyCredential(os.environ.get("AZURE_SUBSCRIPTION_KEY"))

search_client = MapsSearchClient(
    credential=credential,
)

2. Проверка подлинности с помощью учетных данных Azure Active Directory

Вы можете пройти проверку подлинности с помощью учетных данных маркера Azure Active Directory (AAD) с помощью библиотеки удостоверений Azure. Для проверки подлинности с помощью AAD требуется некоторая начальная настройка:

После настройки можно выбрать тип учетных данных для azure.identity использования. Например, для проверки подлинности клиента можно использовать DefaultAzureCredential :

Затем задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения AAD в качестве переменных среды: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Кроме того, необходимо указать Azure Maps ресурс, который вы планируете использовать, указав clientId в параметрах клиента . Идентификатор клиента ресурса Azure Maps можно найти в разделах Проверка подлинности ресурса Azure Maps. Сведения о том, как найти его, см. в документации .

from azure.maps.search import MapsSearchClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
search_client = MapsSearchClient(credential=credential)

Основные понятия

Клиентская библиотека поиска Azure Maps для Python позволяет взаимодействовать с каждым из компонентов с помощью выделенного клиентского объекта.

Синхронизация клиентов

MapsSearchClient— это основной клиент для разработчиков, использующих клиентную библиотеку поиска Azure Maps для Python. После инициализации MapsSearchClient класса можно изучить методы этого клиентского объекта, чтобы понять различные функции Azure Maps служба , к которым можно получить доступ.

Асинхронные клиенты

Эта библиотека включает полный асинхронный API, поддерживаемый в Python 3.5 и более поздних версий. Чтобы использовать его, необходимо сначала установить асинхронный транспорт, например aiohttp. Дополнительные сведения см. в документации по azure-core .

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

Примеры

В следующих разделах представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач поиска Azure Maps, в том числе:

Запрос координат широты и долготы для адреса

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

from azure.maps.search import MapsSearchClient

search_result = client.search_address("400 Broad, Seattle");

Поиск адреса или точки интереса

Для поиска адреса или точки интереса можно использовать нечеткий поиск. В следующих примерах показано, как выполнять поиск pizza в области определенной страны (Franceв этом примере).

from azure.maps.search import MapsSearchClient

fuzzy_search_result = client.fuzzy_search(query: "pizza", country_filter: "fr" );

result_address = fuzzy_search_result.results[0].address

Поиск по обратным адресам для преобразования координатного расположения в адрес улицы

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

from azure.maps.search import MapsSearchClient

coordinates=(47.60323, -122.33028)

reverse_search_result = client.reverse_search_address(coordinates=coordinates);

result_summary = reverse_search_result.summary

Преобразование координат расположения в понятное для человека перекресток

Перевод координат в понятное человеку название пересекающей улицы с помощью API обратного поиска пересекающей улицы. Чаще всего это необходимо в приложениях для отслеживания, которые получают веб-канал GPS с устройства или ресурса и которым требуется определить, что располагается по данным координатам.

from azure.maps.search import MapsSearchClient

coordinates=(47.60323, -122.33028)

reverse_search_result = client.reverse_search_cross_street_address(coordinates=coordinates);

result_address = reverse_search_result.results[0].address

Получение асинхронного нечеткого поиска с параметрами и batchid

В этом примере показано, как выполнять нечеткий поиск по расположению и lat/lon с помощью асинхронного пакетного метода. Эта функция принимает и search_queries и batch_id возвращает AsyncLRO объект . Здесь batch_id можно использовать для получения объекта LRO позже, который за последние 14 дней.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

async with maps_search_client:
    result = await maps_search_client.begin_fuzzy_search_batch(
        search_queries=[
            "350 5th Ave, New York, NY 10118&limit=1",
            "400 Broad St, Seattle, WA 98109&limit=6"
        ]
    )

batch_id = result.batch_id

Метод begin_fuzzy_search_batch() также принимает в batch_id качестве параметра . Здесь batch_id можно использовать для получения объекта LRO позже, который за последние 14 дней.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

async with maps_search_client:
    result = await maps_search_client.begin_fuzzy_search_batch(
        batch_id=batch_id
    )

result = result.response

Не удалось получить пакетную синхронизацию нечеткого поиска

В этом примере показано, как проверить наличие сбоев при поиске fuzzy_search_batch.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

result = maps_search_client.fuzzy_search_batch(
    search_queries=[
        "350 5th Ave, New York, NY 10118&limit=1",
        "400 Broad St, Seattle, WA 98109&lim"
    ]
)
for item in result.items:
    count = 0
    if item.response.error is not None:
        count = count+1
        print(f"Error: {item.response.error.message}")
print(f"There are total of {count} search queries failed.")

Поиск внутри geometry

В этом примере показано, как выполнить поиск внутри геометрии по заданному целевому объекту, pizza например и нескольким разным геометрическим объектам в качестве входных данных с объектом GeoJson.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

geo_json_obj1 = {
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [[
                    [-122.143035,47.653536],
                    [-122.187164,47.617556],
                    [-122.114981,47.570599],
                    [-122.132756,47.654009],
                    [-122.143035,47.653536]
                    ]]
            },
            "properties": {}
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [-122.126986,47.639754]
            },
            "properties": {
                "subType": "Circle",
                "radius": 100
            }
        }
    ]
}
result1 = maps_search_client.search_inside_geometry(
    query="pizza",
    geometry=geo_json_obj1
)
print("Search inside geometry with standard GeoJson object as input, FeatureCollection:")
print(result1)

В этом примере показано, как работать с другими существующими пакетами, shapely например выполнять поиск внутри геометрии по заданному целевому объекту, pizzaнапример .

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

from shapely.geometry import Polygon

geo_interface_obj = Polygon([
    [-122.43576049804686, 37.7524152343544],
    [-122.43301391601562, 37.70660472542312],
    [-122.36434936523438, 37.712059855877314],
    [-122.43576049804686, 37.7524152343544]
])

result3 = maps_search_client.search_inside_geometry(
    query="pizza",
    geometry=geo_interface_obj
)
print("Search inside geometry with Polygon from third party library `shapely` with geo_interface as result 3:")
print(result2)

Устранение неполадок

Общие сведения

Клиенты поиска карт вызывают исключения, определенные в Azure Core.

Этот список можно использовать для справки для перехвата вызванных исключений. Чтобы получить конкретный код ошибки исключения, используйте error_code атрибут , т. е exception.error_code. .

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и неотредактированные заголовки, можно включить на клиенте с помощью аргумента logging_enable :

import sys
import logging
from azure.maps.search import MapsSearchClient

# Create a logger for the 'azure.maps.search' SDK
logger = logging.getLogger('azure.maps.search')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

Аналогичным образом с помощью параметра logging_enable можно включить подробное журналирование для отдельной операции (даже если этот режим не включен в клиенте):

service_client.get_service_stats(logging_enable=True)

Дополнительно

По-прежнему возникают проблемы? Если вы столкнулись с ошибками или у вас есть предложения, сообщите о проблеме в разделе Проблемы проекта.

Дальнейшие действия

Больше примеров кода

Начните работу с нашими примерами поиска карт (примеры асинхронных версий).

В репозитории GitHub пакета SDK для Пакета SDK для Python доступно несколько примеров для поиска Azure Maps. В этих примерах приведен пример кода для дополнительных сценариев, часто встречающихся при работе с поиском карт.

set AZURE_SUBSCRIPTION_KEY="<RealSubscriptionKey>"

pip install azure-maps-search --pre

python samples/sample_authentication.py
python sample/sample_fuzzy_search.py
python samples/sample_get_point_of_interest_categories.py
python samples/sample_reverse_search_address.py
python samples/sample_reverse_search_cross_street_address.py
python samples/sample_search_nearby_point_of_interest.py
python samples/sample_search_point_of_interest_category.py
python samples/sample_search_point_of_interest.py
python samples/sample_search_structured_address.py

Примечания. --pre Флаг можно добавить при необходимости, он должен включать предварительные версии и версии разработки для pip install. По умолчанию pip находит только стабильные версии.

Дополнительные сведения см. в разделе Общие сведения о примерах.

Дополнительная документация

Более подробную документацию по поиску Azure Maps см. в документации по поиску Azure Maps на docs.microsoft.com.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.