Příručka pro vývojáře v sadě Python REST SDK (Preview)

Sadu Azure Maps Python SDK je možné integrovat s aplikacemi a knihovnami Pythonu a vytvářet aplikace související s mapováním a zjišťováním polohy. Sada Azure Maps Python SDK obsahuje rozhraní API pro vyhledávání, trasu, vykreslení a geografickou polohu. Tato rozhraní API podporují operace, jako je hledání adresy, směrování mezi různými souřadnicemi a získání geografického umístění konkrétní IP adresy.

Požadavky

• Účet Azure Maps.
• Klíč předplatného nebo jiná forma ověřování pomocí Azure Maps.
• Python ve verzi 3.8 nebo novější Doporučujeme použít nejnovější verzi. Další informace najdete v tématu o zásadách podpory verzí sady Azure SDK pro Python.

Tip

Účet Azure Maps můžete vytvořit programově. Tady je příklad s využitím Azure CLI:

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

Vytvoření projektu Pythonu

Následující příklad ukazuje, jak vytvořit konzolový program s názvem demo Python:

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py 

Instalace potřebných balíčků Pythonu

Každá služba v Azure Maps je obsažena ve vlastním balíčku. Při použití sady Azure Maps Python SDK můžete nainstalovat jenom balíčky služeb, které potřebujete.

Tady nainstalujeme balíček Azure Maps Search. Vzhledem k tomu, že je stále ve verzi Public Preview, musíte přidat --pre příznak:

pip install azure-maps-search --pre 

Služby Azure Maps

Sada Azure Maps Python SDK podporuje Python verze 3.8 nebo novější. Další informace obudoucíchch

Název služby	Balíček PyPi	Vzorky
Vyhledat	azure-maps-search	ukázky hledání
Trasa	azure-maps-route	vzorky tras
Vykreslení	azure-maps-render	render sample
Geografická poloha	azure-maps-geolocation	Ukázka geografické polohy

Vytvoření a ověření MapsSearchClient

Při vytváření objektu použitého MapsSearchClient pro přístup k rozhraním API služby Azure Maps Search potřebujete credential objekt pro ověřování. K ověření můžete použít přihlašovací údaje Microsoft Entra nebo klíč předplatného Azure. Další informace o ověřování najdete v tématu Ověřování pomocí Azure Maps.

Tip

Jedná seMapsSearchClient o primární rozhraní pro vývojáře, kteří používají knihovnu Azure Maps Search. Další informace o dostupných metodách vyhledávání najdete v klientské knihovně balíčků Služby Azure Maps Search.

Použití přihlašovacích údajů Microsoft Entra

K ověření můžete použít Microsoft Entra ID pomocí balíčku Azure Identity. Pokud chcete použít zprostředkovatele DefaultAzureCredential , musíte nainstalovat balíček klienta Azure Identity:

pip install azure-identity 

Musíte zaregistrovat novou aplikaci Microsoft Entra a udělit přístup ke službě Azure Maps přiřazením požadované role k instančnímu objektu. Další informace najdete v tématu Hostování démona u prostředků mimo Azure. Vrátí se ID aplikace (klienta), ID adresáře (tenanta) a tajný klíč klienta. Zkopírujte tyto hodnoty a uložte je na bezpečném místě. Budete je potřebovat v následujících krocích.

Dále musíte zadat účet Azure Maps, který chcete použít, zadáním ID klienta mapy. ID klienta účtu Azure Maps najdete v částech Ověřování účtu Azure Maps. Další informace najdete v tématu Zobrazení podrobností o ověřování.

Nastavte hodnoty ID aplikace (klienta), ID adresáře (tenanta) a tajného klíče klienta vaší aplikace Microsoft Entra a ID klienta prostředku mapy jako proměnné prostředí:

Proměnná prostředí	Popis
AZURE_CLIENT_ID	ID aplikace (klienta) ve vaší registrované aplikaci
AZURE_CLIENT_SECRET	Hodnota tajného klíče klienta v registrované aplikaci
AZURE_TENANT_ID	ID adresáře (tenanta) ve vaší registrované aplikaci
MAPS_CLIENT_ID	ID klienta ve vašem účtu Azure Map

Teď můžete v PowerShellu vytvořit proměnné prostředí pro uložení těchto hodnot:

$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 nastavení proměnných prostředí je můžete v programu použít k vytvoření instance AzureMapsSearch klienta. Vytvořte soubor s názvem demo.py a přidejte následující kód:

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
)

Důležité

Ostatní proměnné prostředí vytvořené v předchozím fragmentu kódu, zatímco v ukázce kódu se nepoužívají, jsou vyžadovány DefaultAzureCredential(). Pokud tyto proměnné prostředí nenastavíte správně pomocí stejných zásad vytváření názvů, zobrazí se chyby za běhu. Pokud například chybí nebo AZURE_CLIENT_ID je neplatný, zobrazí se InvalidAuthenticationTokenTenant chyba.

Použití přihlašovacích údajů klíče předplatného

Můžete se ověřit pomocí klíče předplatného Azure Maps. Klíč předplatného najdete v části Ověřování v účtu Azure Maps, jak je znázorněno na následujícím snímku obrazovky:

Teď můžete v PowerShellu vytvořit proměnné prostředí pro uložení klíče předplatného:

$Env:SUBSCRIPTION_KEY="your subscription key"

Jakmile je proměnná prostředí vytvořená, můžete k ní přistupovat ve svém kódu. Vytvořte soubor s názvem demo.py a přidejte následující kód:

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

Geografické kódování adresy

Následující fragment kódu ukazuje, jak v jednoduché konzolové aplikaci získat souřadnice zeměpisné délky a zeměpisné šířky pro danou adresu. Tento příklad používá přihlašovací údaje klíče předplatného k ověření MapsSearchClient. V 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()

Tento ukázkový kód vytvoří AzureKeyCredential instanci s klíčem předplatného Azure Maps a pak ho použije k vytvoření instance objektu MapsSearchClient . Metody poskytované předáním MapsSearchClient požadavku koncovým bodům REST služby Azure Maps. Na konci program iteruje výsledky a vytiskne souřadnice pro každý výsledek.

Adresy geografického kódu služby Batch

Tato ukázka ukazuje, jak provést dávkovou adresu vyhledávání:

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

Nastavení zpětného vyhledávání adres k překladu umístění souřadnic na adresu ulice

Souřadnice můžete přeložit na adresy ulice čitelné člověkem. Tento proces se také označuje jako zpětné geokódování. To se často používá pro aplikace, které využívají GPS kanály a chtějí zjistit adresy na konkrétních souřadnicových bodech.

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

Batch request for reverse geocoding

Tato ukázka ukazuje, jak provést reverzní vyhledávání podle zadaných souřadnic v dávce.

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

Získání mnohoúhelníku pro dané umístění

Tato ukázka ukazuje, jak hledat mnohoúhelníky.

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

Použití sad SDK V1 pro vyhledávání a vykreslování

Pokud chcete použít sadu SDK pro vyhledávání v1 a vykreslení V1, další informace najdete na stránce balíčku Sady SDK pro vyhledávání v1 a balíčku Render V1 SDK.

Další informace

Klientská knihovna balíčků Azure Maps Search v dokumentaci k sadě Azure SDK for Python Preview .