Ontwikkelaarshandleiding voor Python REST SDK (preview)

Artikel
08/16/2024

De Python SDK van Azure Maps kan worden geïntegreerd met Python-toepassingen en -bibliotheken om kaartgerelateerde en locatiebewuste toepassingen te bouwen. De Python SDK van Azure Maps bevat API's voor zoeken, route, renderen en geolocatie. Deze API's ondersteunen bewerkingen zoals het zoeken naar een adres, routering tussen verschillende coördinaten, het verkrijgen van de geografische locatie van een specifiek IP-adres.

Vereisten

Azure Maps-account.
Abonnementssleutel of een andere vorm van verificatie met Azure Maps.
Python op 3.8 of hoger. Het is raadzaam om de nieuwste versie te gebruiken. Zie ondersteuningsbeleid voor Azure SDK voor Python-versies voor meer informatie.

Tip

U kunt programmatisch een Azure Maps-account maken. Hier volgt een voorbeeld met behulp van de Azure CLI:

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

Een Python-project maken

In het volgende voorbeeld ziet u hoe u een consoleprogramma maakt met de naam demo Python:

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py

Benodigde Python-pakketten installeren

Elke service in Azure Maps bevindt zich in een eigen pakket. Wanneer u de Python SDK van Azure Maps gebruikt, kunt u alleen de pakketten van de services installeren die u nodig hebt.

Hier installeren we het Azure Maps Search-pakket. Omdat deze nog steeds in openbare preview is, moet u de --pre vlag toevoegen:

pip install azure-maps-search --pre

Azure Maps Services

Azure Maps Python SDK ondersteunt Python versie 3.8 of hoger. Zie het ondersteuningsbeleid voor Azure SDK voor Python-versies voor meer informatie over toekomstige Python-versies.

Servicenaam	PyPi-pakket	Monsters
Zoeken	azure-maps-search	zoekvoorbeelden
Route	azure-maps-route	routevoorbeelden
Weergeven	azure-maps-render	voorbeeld weergeven
Geolocatie	azure-maps-geolocation	voorbeeld van geolocatie

Een MapsSearchClient maken en verifiëren

U hebt een credential object voor verificatie nodig bij het maken van het MapsSearchClient object dat wordt gebruikt voor toegang tot de Azure Maps-zoek-API's. U kunt een Microsoft Entra-referentie of een Azure-abonnementssleutel gebruiken om te verifiëren. Zie Verificatie met Azure Maps voor meer informatie over verificatie.

Tip

DitMapsSearchClient is de primaire interface voor ontwikkelaars die de Azure Maps-zoekbibliotheek gebruiken. Zie de clientbibliotheek van het Azure Maps Search-pakket voor meer informatie over de beschikbare zoekmethoden.

Een Microsoft Entra-referentie gebruiken

U kunt zich verifiëren met Microsoft Entra ID met behulp van het Azure Identity-pakket. Als u de DefaultAzureCredential-provider wilt gebruiken, moet u het Azure Identity-clientpakket installeren:

pip install azure-identity

U moet de nieuwe Microsoft Entra-toepassing registreren en toegang verlenen tot Azure Maps door de vereiste rol toe te wijzen aan uw service-principal. Zie Een daemon hosten voor niet-Azure-resources voor meer informatie. De toepassings-id (client), een map-id (tenant) en een clientgeheim worden geretourneerd. Kopieer deze waarden en sla ze op een veilige plaats op. U hebt ze nodig in de volgende stappen.

Vervolgens moet u het Azure Maps-account opgeven dat u wilt gebruiken door de client-id van de kaarten op te geven. De client-id van het Azure Maps-account vindt u in de secties Verificatie van het Azure Maps-account. Zie Verificatiedetails weergeven voor meer informatie.

Stel de waarden in van de toepassings-id (client),map-id (tenant) en het clientgeheim van uw Microsoft Entra-toepassing en de client-id van de toewijzingsresource als omgevingsvariabelen:

Omgevingsvariabele	Beschrijving
AZURE_CLIENT_ID	Toepassings-id (client) in uw geregistreerde toepassing
AZURE_CLIENT_SECRET	De waarde van het clientgeheim in uw geregistreerde toepassing
AZURE_TENANT_ID	Map-id (tenant) in uw geregistreerde toepassing
MAPS_CLIENT_ID	De client-id in uw Azure Map-account

U kunt nu omgevingsvariabelen maken in PowerShell om deze waarden op te slaan:

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

Nadat u de omgevingsvariabelen hebt ingesteld, kunt u deze in uw programma gebruiken om de AzureMapsSearch client te instantiëren. Maak een bestand met de naam demo.py en voeg de volgende code toe:

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
)

Belangrijk

De andere omgevingsvariabelen die zijn gemaakt in het vorige codefragment, terwijl ze niet worden gebruikt in het codevoorbeeld, zijn vereist voor DefaultAzureCredential(). Als u deze omgevingsvariabelen niet correct instelt met dezelfde naamconventies, krijgt u runtimefouten. Als uw AZURE_CLIENT_ID bestand bijvoorbeeld ontbreekt of ongeldig is, krijgt u een InvalidAuthenticationTokenTenant foutmelding.

Een abonnementssleutelreferentie gebruiken

U kunt verifiëren met uw Azure Maps-abonnementssleutel. Uw abonnementssleutel vindt u in de sectie Verificatie in het Azure Maps-account, zoals wordt weergegeven in de volgende schermopname:

U kunt nu omgevingsvariabelen maken in PowerShell om de abonnementssleutel op te slaan:

$Env:SUBSCRIPTION_KEY="your subscription key"

Zodra uw omgevingsvariabele is gemaakt, kunt u deze openen in uw code. Maak een bestand met de naam demo.py en voeg de volgende code toe:

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

Een adres geocoderen

In het volgende codefragment ziet u hoe u in een eenvoudige consoletoepassing lengte- en breedtegraadcoördinaten voor een bepaald adres kunt verkrijgen. In dit voorbeeld worden abonnementssleutelreferenties gebruikt om MapsSearchClient te verifiëren. 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()

Met deze voorbeeldcode wordt een instantie gemaakt AzureKeyCredential met de Azure Maps-abonnementssleutel en vervolgens gebruikt om het MapsSearchClient object te instantiëren. De methoden die worden geboden door MapsSearchClient de aanvraag door te sturen naar de Azure Maps REST-eindpunten. Uiteindelijk doorloopt het programma de resultaten en drukt het de coördinaten voor elk resultaat af.

Batch-geocodeadressen

In dit voorbeeld ziet u hoe u een batchzoekadres uitvoert:

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

Een omgekeerde adreszoekopdracht maken om de locatie van het coördinaat te vertalen naar adres

U kunt coördinaten omzetten in door mensen leesbare straatadressen. Dit proces wordt ook wel omgekeerde geocodering genoemd. Dit wordt vaak gebruikt voor toepassingen die GPS-feeds verbruiken en adressen op specifieke coördinatenpunten willen detecteren.

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-aanvraag voor omgekeerde geocodering

In dit voorbeeld ziet u hoe u reverse search uitvoert op basis van bepaalde coördinaten in batch.

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

Veelhoeken voor een bepaalde locatie ophalen

In dit voorbeeld ziet u hoe u veelhoeken kunt doorzoeken.

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

V1 SDK's gebruiken voor zoeken en weergeven

Als u Search V1 en Render V1 SDK wilt gebruiken, raadpleegt u de pagina met het Search V1 SDK-pakket en het Render V1 SDK-pakket voor meer informatie.

Aanvullende informatie

De Azure Maps Search-pakketclientbibliotheek in de Documentatie voor Azure SDK voor Python Preview .

Delen via