Share via

Azure Maps Suchpaketclientbibliothek für Python – Version 1.0.0b2

  • Artikel

Dieses Paket enthält ein Python SDK für Azure Maps Services for Search. Weitere Informationen zu Azure Maps Services finden Sie hier.

Quellcode | API-Referenzdokumentation | Produktdokumentation

Haftungsausschluss

Die Unterstützung von Python-Paketen für Das Azure SDK für Python 2.7 wurde am 01. Januar 2022 eingestellt. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Voraussetzungen

Wenn Sie die Azure CLI verwenden, ersetzen <resource-group-name> Sie und <account-name> von Ihrer Wahl, und wählen Sie einen geeigneten Tarif basierend auf Ihren Anforderungen über den <sku-name> Parameter aus. Weitere Informationen finden Sie auf dieser Seite.

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

Installieren des Pakets

Installieren Sie das Azure Maps Service Search SDK.

pip install azure-maps-search

Erstellen und Authentifizieren des MapsSearchClient

Um ein Clientobjekt für den Zugriff auf die Azure Maps-Such-API zu erstellen, benötigen Sie ein Anmeldeinformationsobjekt. Azure Maps Search-Client unterstützt auch zwei Möglichkeiten zur Authentifizierung.

1. Authentifizieren mit Abonnementschlüsselanmeldeinformationen

Sie können sich mit Ihrem Azure Maps-Abonnementschlüssel authentifizieren. Nachdem der Azure Maps Abonnementschlüssel erstellt wurde, legen Sie den Wert des Schlüssels als Umgebungsvariable fest: AZURE_SUBSCRIPTION_KEY. Übergeben Sie dann einen AZURE_SUBSCRIPTION_KEY als credential Parameter an eine Instanz von 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. Authentifizieren mit Azure Active Directory-Anmeldeinformationen

Sie können sich mit Azure Active Directory-Tokenanmeldeinformationen (AAD) mithilfe der Azure Identity-Bibliothek authentifizieren. Die Authentifizierung mithilfe von AAD erfordert eine anfängliche Einrichtung:

Nach der Einrichtung können Sie auswählen, von azure.identity welchem Typ von Anmeldeinformationen sie verwendet werden sollen. Als Beispiel kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren:

Legen Sie als Nächstes die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Sie müssen auch die Azure Maps Ressource angeben, die Sie verwenden möchten, indem Sie in den Clientoptionen angebenclientId. Die Azure Maps-Ressourcenclient-ID finden Sie in den Abschnitten Authentifizierung in der Azure Maps-Ressource. Informationen zum Finden finden Sie in der Dokumentation .

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

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

Wichtige Begriffe

Die Azure Maps Search-Clientbibliothek für Python ermöglicht Ihnen die Interaktion mit den einzelnen Komponenten über die Verwendung eines dedizierten Clientobjekts.

Clients synchronisieren

MapsSearchClientist der primäre Client für Entwickler, die die Azure Maps Search-Clientbibliothek für Python verwenden. Nachdem Sie eine MapsSearchClient Klasse initialisiert haben, können Sie die Methoden für dieses Clientobjekt untersuchen, um die verschiedenen Features der Azure Maps Suchdienst zu verstehen, auf die Sie zugreifen können.

Asynchrone Clients

Diese Bibliothek enthält eine vollständige asynchrone API, die unter Python 3.5 und höher unterstützt wird. Um ihn verwenden zu können, müssen Sie zuerst einen asynchronen Transport installieren, z. B. aiohttp. Weitere Informationen finden Sie in der Dokumentation zu azure-core .

Asynchrone Clients und Anmeldeinformationen sollten geschlossen werden, wenn sie nicht mehr benötigt werden. Diese Objekte sind asynchrone Kontext-Manager und definieren asynchrone close Methoden.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Azure Maps Suchaufgaben behandeln, einschließlich:

Anfordern von Breiten- und Längengradkoordinaten für eine Adresse

Sie können einen authentifizierten Client verwenden, um eine Adresse in Breiten- und Längengradkoordinaten zu konvertieren. Dieser Vorgang wird auch als Geocodierung bezeichnet. Zusätzlich zu den Koordinaten werden in der Antwort auch detaillierte Adressinformationen zurückgegeben, darunter beispielsweise Straße, Postleitzahl, Gemeinde und Land/Region.

from azure.maps.search import MapsSearchClient

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

Suchen nach einer Adresse oder einem Point of Interest

Sie können die Fuzzy-Suche verwenden, um eine Adresse oder einen Point of Interest (POI) zu suchen. In den folgenden Beispielen wird veranschaulicht, wie sie über den Bereich eines bestimmten Landes (Francein diesem Beispiel) suchenpizza.

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

Durchführen einer Reverse-Adresssuche, um den Koordinatenstandort in die Straßenadresse zu übersetzen

Sie können Koordinaten in lesbare Straßenadressen übersetzen. Dieser Prozess wird auch als reverse Geocodierung bezeichnet. Dies wird häufig für Anwendungen verwendet, die GPS-Feeds nutzen und Adressen an bestimmten Koordinatenpunkten ermitteln möchten.

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

Übersetzen der Koordinatenposition in eine menschlich verständliche Kreuzstraße

Übersetzen der Koordinaten in ein von Menschen lesbares Format nach Querstraßen mithilfe der API für die inverse Adresssuche nach Querstraßen Diese Funktion wird meistens in Trackinganwendungen benötigt, die einen GPS-Feed von einem Gerät oder einer Ressource empfangen und Adressen an bestimmten Koordinatenpunkten ermitteln sollen.

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

Abrufen eines Batches für die asynchrone Fuzzysuche mit param und batchid

In diesem Beispiel wird veranschaulicht, wie Sie eine Fuzzysuche nach Standort und lat/lon mit der asynchronen Batchmethode ausführen. Diese Funktion akzeptiert und search_queriesbatch_id gibt ein AsyncLRO -Objekt zurück. Das batch_id hier kann verwendet werden, um das LRO-Objekt später abzurufen, das 14 Tage dauert.

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

Die -Methode begin_fuzzy_search_batch() akzeptiert batch_id auch als Parameter. Das batch_id hier kann verwendet werden, um das LRO-Objekt später abzurufen, das 14 Tage dauert.

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

Fehler beim Abrufen der Batchsynchronisierung für die Fuzzysuche

In diesem Beispiel wird veranschaulicht, wie Sie überprüfen, ob bei der Suche nach fuzzy_search_batch Fehler auftreten.

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

Suchen in Geometry

In diesem Beispiel wird veranschaulicht, wie Sie eine Suche innerhalb der Geometrie durch ein bestimmtes Ziel ausführen, z. B pizza . und mehrere verschiedene Geometrien als Eingabe mit dem GeoJson-Objekt.

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)

In diesem Beispiel wird veranschaulicht, wie Sie mit anderen vorhandenen Paketen arbeiten, z shapely . B. zum Ausführen einer Suche in der Geometrie durch ein bestimmtes Ziel, z. B 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)

Problembehandlung

Allgemein

Maps Search-Clients lösen ausnahmen aus, die in Azure Core definiert sind.

Diese Liste kann als Verweis verwendet werden, um ausgelöste Ausnahmen abzufangen. Um den spezifischen Fehlercode der Ausnahme abzurufen, verwenden Sie das error_code -Attribut, d. h exception.error_code. .

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem logging_enable Argument aktiviert werden:

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)

Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:

service_client.get_service_stats(logging_enable=True)

Zusätzliche Informationen

Treten weiterhin Probleme auf? Wenn Fehler auftreten oder Vorschläge vorliegen, melden Sie ein Problem im Abschnitt Probleme des Projekts.

Nächste Schritte

Weiterer Beispielcode

Erste Schritte mit unseren Beispielen für die Kartensuche (Beispiele für die Asynchrone Version).

Mehrere Azure Maps Python SDK-Beispiele für die Suche stehen Ihnen im GitHub-Repository des SDK zur Verfügung. Diese Beispiele enthalten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit der Kartensuche auftreten.

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

Hinweise: --pre Das Flag kann optional hinzugefügt werden, es enthält Vorab- und Entwicklungsversionen für pip install. Standardmäßig pip werden nur stabile Versionen gefunden.

Weitere Details finden Sie unter Einführung zu Beispielen.

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zur Azure Maps Suche finden Sie in der Dokumentation zur Azure Maps-Suche auf docs.microsoft.com.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.