Руководство разработчиков пакета SDK для Python (предварительная версия)

Пакет SDK для Python для Azure Maps можно интегрировать с приложениями и библиотеками Python для создания приложений, связанных с картами и расположениями. Пакет SDK для Python для Azure Maps содержит API для поиска, маршрутизации, отрисовки и географического расположения. Эти API поддерживают такие операции, как поиск адреса, маршрутизация между различными координатами, получение географического расположения определенного IP-адреса.

Необходимые компоненты

• Учетная запись Azure Maps.
• Ключ подписки или другая форма проверки подлинности с помощью Azure Maps.
• Python 3.8 или более поздней версии. Рекомендуется использовать последний выпуск. Дополнительные сведения см. в политике поддержки версий Azure SDK для Python.

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

Создание проекта Python

В следующем примере показано, как создать консольную программу с именем demo Python:

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py 

Установка необходимых пакетов Python

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

Здесь мы устанавливаем пакет поиска Azure Maps. Так как он по-прежнему находится в общедоступной предварительной версии, необходимо добавить --pre флаг:

pip install azure-maps-search --pre 

Службы Azure Maps

Пакет SDK для Python для Azure Maps поддерживает Python версии 3.8 или более поздней версии. Дополнительные сведения о будущих версиях Python см . в политике поддержки версий Azure SDK для Python.

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

При создании объекта, используемого MapsSearchClient для доступа к API поиска Azure Maps, требуется credential объект для проверки подлинности. Для проверки подлинности можно использовать учетные данные Microsoft Entra или ключ подписки Azure. Дополнительные сведения о проверке подлинности см. в статье "Проверка подлинности с помощью Azure Maps".

Использование учетных данных Microsoft Entra

Вы можете пройти проверку подлинности с помощью идентификатора Microsoft Entra с помощью пакета удостоверений Azure. Чтобы использовать поставщик DefaultAzureCredential , необходимо установить пакет клиента удостоверений Azure:

pip install azure-identity 

Необходимо зарегистрировать новое приложение Microsoft Entra и предоставить доступ к Azure Maps, назначив необходимую роль субъекту-службе. Дополнительные сведения см. в статье "Размещение управляющей программы" в ресурсах, отличных от Azure. Возвращаются идентификатор приложения (клиента), идентификатор каталога (клиента) и секрет клиента. Скопируйте эти значения и сохраните их в безопасном месте. Вам потребуется выполнить следующие действия.

Затем необходимо указать учетную запись Azure Maps, которую вы планируете использовать, указав идентификатор клиента карты. Идентификатор клиента учетной записи Azure Maps можно найти в разделах проверки подлинности учетной записи Azure Maps. Дополнительные сведения см. в разделе "Просмотр сведений о проверке подлинности".

Задайте значения идентификатора приложения (клиента), идентификатор каталога (клиента) и секрет клиента приложения Microsoft Entra и идентификатор клиента карты в качестве переменных среды:

Теперь можно создать переменные среды в PowerShell для хранения следующих значений:

$Env:AZURE_CLIENT_ID="Application (client) ID"
$Env:AZURE_CLIENT_SECRET="your client secret"
$Env:AZURE_TENANT_ID="your Directory (tenant) ID"
$Env:MAPS_CLIENT_ID="your Azure Maps client ID"

После настройки переменных среды их можно использовать в программе для создания экземпляра AzureMapsSearch клиента. Создайте файл с именем demo.py и добавьте следующий код:

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

credential = DefaultAzureCredential()
maps_client_id = os.getenv("MAPS_CLIENT_ID")
maps_search_client = MapsSearchClient(
    client_id=maps_client_id,
    credential=credential
)

Использование учетных данных ключа подписки

Вы можете пройти проверку подлинности с помощью ключа подписки Azure Maps. Ключ подписки можно найти в разделе "Проверка подлинности" в учетной записи Azure Maps, как показано на следующем снимке экрана:

Теперь можно создать переменные среды в PowerShell для хранения ключа подписки:

$Env:SUBSCRIPTION_KEY="your subscription key"

После создания переменной среды его можно получить в коде. Создайте файл с именем demo.py и добавьте следующий код:

import os

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

# Use Azure Maps subscription key authentication
subscription_key = os.getenv("SUBSCRIPTION_KEY")
maps_search_client = MapsSearchClient(
   credential=AzureKeyCredential(subscription_key)
)

Географический код адреса

В следующем фрагменте кода показано, как в простом консольном приложении получить координаты долготы и широты для заданного адреса. В этом примере используются учетные данные ключа подписки для проверки подлинности MapsSearchClient. В demo.py:

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def geocode():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_geocoding(query="15127 NE 24th Street, Redmond, WA 98052")
        if result.get('features', False):
            coordinates = result['features'][0]['geometry']['coordinates']
            longitude = coordinates[0]
            latitude = coordinates[1]

            print(longitude, latitude)
        else:
            print("No results")

    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    geocode()

Этот пример кода создает AzureKeyCredential экземпляр с ключом подписки Azure Maps, а затем использует его для создания экземпляра MapsSearchClient объекта. Методы, предоставляемые путем MapsSearchClient пересылки запроса в конечные точки REST Azure Maps. В конце концов программа выполняет итерацию результатов и выводит координаты для каждого результата.

Адреса геокода пакетной службы

В этом примере показано, как выполнить пакетный поиск по адресу:

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def geocode_batch():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_geocoding_batch({
          "batchItems": [
            {"query": "400 Broad St, Seattle, WA 98109"},
            {"query": "15127 NE 24th Street, Redmond, WA 98052"},
          ],
        },)

        if not result.get('batchItems', False):
            print("No batchItems in geocoding")
            return

        for item in result['batchItems']:
            if not item.get('features', False):
                print(f"No features in item: {item}")
                continue

            coordinates = item['features'][0]['geometry']['coordinates']
            longitude, latitude = coordinates
            print(longitude, latitude)

    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    geocode_batch()

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

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

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def reverse_geocode():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_reverse_geocoding(coordinates=[-122.138679, 47.630356])
        if result.get('features', False):
            props = result['features'][0].get('properties', {})
            if props and props.get('address', False):
                print(props['address'].get('formattedAddress', 'No formatted address found'))
            else:
                print("Address is None")
        else:
            print("No features available")
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")


if __name__ == '__main__':
   reverse_geocode()

Пакетный запрос обратного геокодирования

В этом примере показано, как выполнять обратный поиск по заданным координатам в пакете.

import os
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import HttpResponseError
from azure.maps.search import MapsSearchClient

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def reverse_geocode_batch():
    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_reverse_geocoding_batch({
              "batchItems": [
                {"coordinates": [-122.349309, 47.620498]},
                {"coordinates": [-122.138679, 47.630356]},
              ],
            },)

        if result.get('batchItems', False):
            for idx, item in enumerate(result['batchItems']):
                features = item['features']
                if features:
                    props = features[0].get('properties', {})
                    if props and props.get('address', False):
                        print(
                            props['address'].get('formattedAddress', f'No formatted address for item {idx + 1} found'))
                    else:
                        print(f"Address {idx + 1} is None")
                else:
                    print(f"No features available for item {idx + 1}")
        else:
            print("No batch items found")
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")


if __name__ == '__main__':
   reverse_geocode_batch()

Получение многоугольников для заданного расположения

В этом примере показано, как выполнять поиск многоугольников.

import os

from azure.core.exceptions import HttpResponseError
from azure.maps.search import Resolution
from azure.maps.search import BoundaryResultType


subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def get_polygon():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_polygon(
          coordinates=[-122.204141, 47.61256],
          result_type=BoundaryResultType.LOCALITY,
          resolution=Resolution.SMALL,
        )

        if not result.get('geometry', False):
            print("No geometry found")
            return

        print(result["geometry"])
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    get_polygon()

Использование пакетов SDK версии 1 для поиска и отрисовки

Чтобы использовать пакет SDK для поиска версии 1 и отрисовки версии 1, ознакомьтесь со страницей пакета ПАКЕТА SDK для поиска версии 1 и пакетом SDK для отрисовки версии 1.

Дополнительная информация:

Клиентская библиотека пакета поиска Azure Maps в документации по пакету SDK Azure для Python Preview .