Przewodnik dla deweloperów zestawu SDK REST języka Python (wersja zapoznawcza)

Zestaw SDK języka Python usługi Azure Maps można zintegrować z aplikacjami i bibliotekami języka Python w celu tworzenia aplikacji powiązanych z mapą i obsługujących lokalizację. Zestaw SDK języka Python usługi Azure Maps zawiera interfejsy API wyszukiwania, tras, renderowania i geolokalizacji. Te interfejsy API obsługują operacje, takie jak wyszukiwanie adresów, wyznaczanie tras między różnymi współrzędnymi oraz ustalanie geolokalizacji konkretnego adresu IP.

Wymagania wstępne

• Konto usługi Azure Maps.
• Klucz subskrypcji lub inna forma uwierzytelniania za pomocą usługi Azure Maps.
• Python w wersji 3.8 lub nowszej. Zaleca się korzystanie z najnowszej wersji. Aby uzyskać więcej informacji, zobacz Zasady obsługi wersji zestawu Azure SDK dla języka Python.

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

Tworzenie projektu w języku Python

W poniższym przykładzie pokazano, jak utworzyć program konsoli o nazwie przy użyciu demo języka Python:

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py 

Instalowanie wymaganych pakietów języka Python

Każda usługa w usłudze Azure Maps jest zawarta we własnym pakiecie. Korzystając z zestawu SDK języka Python usługi Azure Maps, możesz zainstalować tylko pakiety potrzebnych usług.

W tym miejscu instalujemy pakiet usługi Azure Maps Search. Ponieważ jest ona nadal dostępna w publicznej wersji zapoznawczej, musisz dodać flagę --pre :

pip install azure-maps-search --pre 

Usługi Azure Maps

Zestaw SDK języka Python usługi Azure Maps obsługuje język Python w wersji 3.8 lub nowszej. Aby uzyskać więcej informacji na temat przyszłych wersji języka Python, zobacz Zasady obsługi wersji zestawu Azure SDK dla języka Python.

Utworzyć i uwierzytelnić klienta MapsSearchClient

Potrzebujesz obiektu credential na potrzeby uwierzytelniania podczas tworzenia obiektu MapsSearchClient, używanego do uzyskiwania dostępu do interfejsów API wyszukiwania usługi Azure Maps. Do uwierzytelniania można użyć poświadczeń usługi Microsoft Entra lub klucza subskrypcji platformy Azure. Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Authentication with Azure Maps (Uwierzytelnianie za pomocą usługi Azure Maps).

Używanie poświadczeń entra firmy Microsoft

Możesz uwierzytelniać się za pomocą Microsoft Entra ID przy użyciu pakietu Azure Identity. Aby użyć dostawcy DefaultAzureCredential , należy zainstalować pakiet klienta tożsamości platformy Azure:

pip install azure-identity 

Musisz zarejestrować nową aplikację Firmy Microsoft Entra i udzielić dostępu do usługi Azure Maps, przypisując wymaganą rolę do jednostki usługi. Aby uzyskać więcej informacji, zobacz Hostowanie demona w zasobach spoza platformy Azure. Zwracany jest identyfikator aplikacji (klienta), identyfikator katalogu (dzierżawy) i klucz tajny klienta. Skopiuj te wartości i zapisz je w bezpiecznym miejscu. Są one potrzebne w poniższych krokach.

Następnie należy określić konto usługi Azure Maps, którego chcesz użyć, określając identyfikator klienta mapy. Identyfikator klienta konta usługi Azure Maps można znaleźć w sekcjach Uwierzytelnianie konta usługi Azure Maps. Aby uzyskać więcej informacji, zobacz Wyświetlanie szczegółów uwierzytelniania.

Ustaw wartości identyfikatora aplikacji (klienta), identyfikatora katalogu (dzierżawy) i klucza tajnego klienta aplikacji Microsoft Entra oraz identyfikatora klienta zasobu map jako zmienne środowiskowe:

Teraz możesz utworzyć zmienne środowiskowe w programie PowerShell, aby przechowywać następujące wartości:

$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"

Po ustawieniu zmiennych środowiskowych możesz użyć ich w swoim programie, aby utworzyć instancję klienta AzureMapsSearch. Utwórz plik o nazwie demo.py i dodaj następujący kod:

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
)

Korzystanie z poświadczenia klucza subskrypcji

Możesz uwierzytelnić się przy użyciu klucza subskrypcji usługi Azure Maps. Klucz subskrypcji można znaleźć w sekcji Uwierzytelnianie na koncie usługi Azure Maps, jak pokazano na poniższym zrzucie ekranu:

Teraz możesz utworzyć zmienne środowiskowe w programie PowerShell, aby przechowywać klucz subskrypcji:

$Env:SUBSCRIPTION_KEY="your subscription key"

Po utworzeniu zmiennej środowiskowej możesz uzyskać do niej dostęp w kodzie. Utwórz plik o nazwie demo.py i dodaj następujący kod:

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)
)

Geokodowanie adresu

Poniższy fragment kodu pokazuje, jak w prostej aplikacji konsolowej uzyskać współrzędne długości i szerokości geograficznej dla danego adresu. W tym przykładzie użyto poświadczeń opartych na kluczu subskrypcji do uwierzytelniania klienta MapsSearchClient. W pliku 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()

Ten przykładowy kod tworzy instancję AzureKeyCredential za pomocą klucza subskrypcji usługi Azure Maps, a następnie używa go do utworzenia instancji obiektu MapsSearchClient. Metody udostępnione przez MapsSearchClient przekazują żądanie do punktów końcowych REST usługi Azure Maps. W końcu program iteruje wyniki i drukuje współrzędne dla każdego wyniku.

Adresy geokodów wsadowych

Ten przykład pokazuje, jak wykonać wsadowe wyszukiwanie adresów:

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()

Wykonaj odwrotne wyszukiwanie adresu, aby przekształcić współrzędne lokalizacji na adres uliczny

Współrzędne można przetłumaczyć na czytelne dla człowieka adresy uliczne. Ten proces jest również nazywany odwrotnym geokodowaniem. Jest to często używane w aplikacjach, które zużywają kanały GPS i chcą odnajdywać adresy w określonych punktach współrzędnych.

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()

Żądanie wsadowe dotyczące odwrotnego geokodowania

W tym przykładzie pokazano, jak wykonać wyszukiwanie wsteczne na podstawie podanych współrzędnych wsadowo.

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()

Pobierz wielokąty dla danej lokalizacji

W tym przykładzie pokazano, jak wyszukiwać wielokąty.

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()

Użyj SDK v1 do wyszukiwania

Aby użyć SDK Search v1, zobacz stronę pakietu Search v1 SDK.

Dodatkowe informacje

Biblioteka klienta pakietu Azure Maps Search w dokumentacji zestawu Azure SDK dla języka Python w wersji zapoznawczej.