Entwicklerhandbuch für das Python REST SDK (Vorschau)

Artikel
08/19/2024

Das Azure Maps Python SDK kann in Python-Anwendungen und -Bibliotheken integriert werden, um karten- und standortbezogene Anwendungen zu erstellen. Das Azure Maps Python SDK enthält APIs für Suche, Routen, Rendern und Geolocation. Diese APIs unterstützen Vorgänge wie die Adresssuche, das Routing zwischen verschiedenen Koordinaten und das Abrufen des geografischen Standorts einer bestimmten IP-Adresse.

Voraussetzungen

Azure Maps-Konto
Abonnementschlüssel oder eine andere Form der Authentifizierung bei Azure Maps.
Python 3.8 oder höher. Es wird empfohlen, das aktuelle Release zu verwenden. Weitere Informationen finden Sie in der Supportrichtlinie zu Python-Versionen für Azure SDKs.

Tipp

Sie können ein Azure Maps-Konto programmgesteuert erstellen. Hier sehen Sie ein Beispiel unter Verwendung der Azure CLI:

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

Erstellen eines Python-Projekts

Das folgende Beispiel zeigt, wie Sie ein Konsolenprogramm mit dem Namen demo mit Python erstellen:

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py

Installieren der benötigten Python-Pakete

Jeder Dienst in Azure Maps ist in einem eigenen Paket enthalten. Wenn Sie das Azure Maps Python SDK verwenden, können Sie nur die Pakete der von Ihnen benötigten Dienste installieren.

Hier installieren wir das Paket für den Azure Maps-Suchdienst. Da es sich noch in der öffentlichen Vorschau befindet, müssen Sie das --pre-Flag hinzufügen:

pip install azure-maps-search --pre

Azure Maps-Dienste

Das Azure Maps-Python-SDK unterstützt Python ab Version 3.8. Weitere Informationen zu zukünftigen Python-Versionen finden Sie in der Supportrichtlinie zu Python-Versionen für Azure SDKs.

Dienstname	PyPi-Paket	Beispiele
Suchen	azure-maps-search	Beispiele für Suchen
Route	azure-maps-route	Routenbeispiele
Rendern	azure-maps-render	Renderbeispiel
Geolocation	azure-maps-geolocation	Beispiel für Geolocation

Erstellen und Authentifizieren eines MapsSearchClient-Elements

Sie benötigen ein credential-Objekt für die Authentifizierung, wenn Sie das MapsSearchClient-Objekt erstellen, das für den Zugriff auf die Azure Maps-Such-APIs verwendet wird. Sie können für die Authentifizierung entweder Microsoft Entra-Anmeldeinformationen oder einen Azure-Abonnementschlüssel verwenden. Weitere Informationen zur Authentifizierung finden Sie unter Authentifizierung bei Azure Maps.

Tipp

DerMapsSearchClient ist die primäre Schnittstelle für Entwickler, die die Azure Maps-Suchbibliothek verwenden. Weitere Informationen zu den verfügbaren Suchmethoden finden Sie unter Clientbibliothek für das Azure Maps-Suchpaket.

Verwenden von Microsoft Entra-Anmeldeinformationen

Sie können sich mithilfe des Azure Identity-Pakets bei Microsoft Entra ID authentifizieren. Um den Anbieter DefaultAzureCredential zu verwenden, müssen Sie das Azure Identity-Clientpaket installieren:

pip install azure-identity

Sie müssen die neue Microsoft Entra-Anwendung registrieren und ihr Zugriff auf Azure Maps gewähren, indem Sie Ihrem Dienstprinzipal die erforderliche Rolle zuweisen. Weitere Informationen finden Sie unter Hosten eines Daemons für Nicht-Azure-Ressourcen. Zurückgegeben werden die Anwendungs-ID (Client), eine Verzeichnis-ID (Mandant) und ein geheimer Clientschlüssel. Kopieren Sie diese Werte, und speichern Sie sie an einem sicheren Ort. Sie benötigen diese in den folgenden Schritten.

Als Nächstes müssen Sie das zu verwendende Azure Maps-Konto festlegen, indem Sie die Azure Maps-Client-ID angeben. Die Client-ID des Azure Maps-Kontos finden Sie im Azure Maps-Konto in den Abschnitten unter „Authentifizierung“. Weitere Informationen finden Sie unter Anzeigen von Authentifizierungsdetails.

Legen Sie die Werte der Anwendungs-ID (Client-ID), der Verzeichnis-ID (Mandanten-ID) und des geheimen Clientschlüssels Ihrer Microsoft Entra-Anwendung sowie der Client-ID der Kartenressource als Umgebungsvariablen fest:

Umgebungsvariable	BESCHREIBUNG
AZURE_CLIENT_ID	Anwendungs-ID (Client-ID) in Ihrer registrierten Anwendung
AZURE_CLIENT_SECRET	Der Wert des geheimen Clientschlüssels in Ihrer registrierten Anwendung
AZURE_TENANT_ID	Verzeichnis-ID (Mandanten-ID) in Ihrer registrierten Anwendung
MAPS_CLIENT_ID	Die Client-ID in Ihrem Azure Map-Konto

Sie können nun Umgebungsvariablen in PowerShell erstellen, um diese Werte zu speichern:

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

Nachdem Sie die Umgebungsvariablen eingerichtet haben, können Sie sie in Ihrem Programm verwenden, um den AzureMapsSearch-Client zu instanziieren. Erstellen Sie eine Datei namens demo.py, und fügen Sie den folgenden Code hinzu:

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
)

Wichtig

Die anderen Umgebungsvariablen, die im vorherigen Codeschnipsel erstellt wurden, werden zwar im Codebeispiel nicht verwendet, sind aber für DefaultAzureCredential() erforderlich. Wenn Sie diese Umgebungsvariablen nicht richtig festlegen und dieselben Benennungskonventionen verwenden, treten Laufzeitfehler auf. Wenn AZURE_CLIENT_ID beispielsweise fehlt oder ungültig ist, erhalten Sie den Fehler InvalidAuthenticationTokenTenant.

Verwenden von Abonnementschlüssel-Anmeldeinformationen

Sie können sich mit Ihrem Azure Maps-Abonnementschlüssel authentifizieren. Ihren Abonnementschlüssel finden Sie im Abschnitt Authentifizierung im Azure Maps-Konto, wie im folgenden Screenshot gezeigt:

Sie können nun Umgebungsvariablen in PowerShell erstellen, um den Abonnementschlüssel zu speichern:

$Env:SUBSCRIPTION_KEY="your subscription key"

Nachdem Ihre Umgebungsvariable erstellt wurde, können Sie in Ihrem Code darauf zugreifen. Erstellen Sie eine Datei namens demo.py, und fügen Sie den folgenden Code hinzu:

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

Geocodieren einer Adresse

Der folgende Codeschnipsel veranschaulicht, wie in einer einfachen Konsolenanwendung Längen- und Breitengradkoordinaten für eine bestimmte Adresse abgerufen werden. In diesem Beispiel werden Anmeldeinformationen des Abonnementschlüssels verwendet, um MapsSearchClient zu authentifizieren. In 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()

Dieser Beispielcode instanziiert AzureKeyCredential mit dem Azure Maps-Abonnementschlüssel und verwendet diesen dann, um das MapsSearchClient-Objekt zu instanziieren. Die von MapsSearchClient bereitgestellten Methoden leiten die Anforderung an die Azure Maps-REST-Endpunkte weiter. Letztlich durchläuft das Programm die Ergebnisse und gibt die Koordinaten für jedes Ergebnis aus.

Batchgeocodieren von Adressen

Dieses Beispiel veranschaulicht, wie die Batchsuche nach Adressen funktioniert:

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

Ausführen einer inversen Adresssuche, um den Koordinatenort in eine Straßenadresse zu übersetzen

Sie können Koordinaten in für Menschen lesbare Straßenadressen übersetzen. Dieser Vorgang wird auch als umgekehrte Geocodierung bezeichnet. Dies wird häufig für Anwendungen verwendet, die einen GPS-Feed empfangen und Adressen an bestimmten Koordinatenpunkten ermitteln sollen.

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

Batchanforderung für umgekehrte Geocodierung

In diesem Beispiel wird veranschaulicht, wie die umgekehrte Suche nach bestimmten Koordinaten im Batch ausgeführt wird.

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

Abrufen von Polygonen für einen bestimmten Standort

In diesem Beispiel wird das Durchsuchen von Polygonen veranschaulicht.

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

Verwenden von V1-SDKs für Suchen und Rendern

Wenn Sie die V1-SDKs für Suchen und Rendern verwenden möchten, finden Sie weitere Informationen auf den Seiten für das Paket des V1-SDK für Suchen und das Paket des V1-SDK für Rendern.

Zusätzliche Informationen

Die Clientbibliothek für das Azure Maps-Suchpaket in der Dokumentation zum Azure-SDK für Python (Vorschauversion).

Freigeben über