Guida per gli sviluppatori di Python REST SDK (anteprima)

L'SDK Python Mappe di Azure può essere integrato con applicazioni e librerie Python per creare applicazioni correlate alla mappa e in grado di riconoscerne la posizione. Il Mappe di Azure Python SDK contiene le API per la ricerca, la route, il rendering e la georilevazione. Queste API supportano operazioni come la ricerca di un indirizzo, il routing tra coordinate diverse, ottenendo la posizione geografica di un indirizzo IP specifico.

Prerequisiti

Suggerimento

È possibile creare un account Mappe di Azure a livello di codice, di seguito è riportato un esempio usando l'interfaccia della riga di comando di Azure:

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

Creare un progetto Python

L'esempio seguente illustra come creare un programma console denominato demo con Python:

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py 

Installare i pacchetti Python necessari

Ogni servizio in Mappe di Azure è contenuto nel proprio pacchetto. Quando si usa Mappe di Azure Python SDK, è possibile installare solo i pacchetti dei servizi necessari.

Qui viene installato il pacchetto di ricerca Mappe di Azure. Poiché è ancora in anteprima pubblica, è necessario aggiungere il --pre flag :

pip install azure-maps-search --pre 

Servizi di Mappe di Azure

Mappe di Azure Python SDK supporta Python versione 3.8 o successiva. Per altre informazioni sulle versioni future di Python, vedere Criteri di supporto delle versioni di Azure SDK per Python.

Creare ed autenticare un oggetto MapsSearchClient

È necessario un credential oggetto per l'autenticazione durante la creazione dell'oggetto MapsSearchClient usato per accedere alle API di ricerca Mappe di Azure. È possibile usare una credenziale di Microsoft Entra o una chiave di sottoscrizione di Azure per l'autenticazione. Per altre informazioni sull'autenticazione, vedere Autenticazione con Mappe di Azure.

Suggerimento

MapsSearchClient è l'interfaccia principale per gli sviluppatori che usano la libreria di ricerca Mappe di Azure. Per altre informazioni sui metodi di ricerca disponibili, vedere Mappe di Azure libreria client dei pacchetti di ricerca.

Uso delle credenziali di Microsoft Entra

È possibile eseguire l'autenticazione con Microsoft Entra ID usando il pacchetto Di identità di Azure. Per usare il provider DefaultAzureCredential , è necessario installare il pacchetto client di Azure Identity:

pip install azure-identity 

È necessario registrare la nuova applicazione Microsoft Entra e concedere l'accesso a Mappe di Azure assegnando il ruolo necessario all'entità servizio. Per altre informazioni, vedere Ospitare un daemon in risorse non di Azure. Vengono restituiti l'ID applicazione (client), un ID directory (tenant) e un segreto client. Copiare questi valori e archiviarli in un luogo sicuro. Sono necessari nei passaggi seguenti.

Successivamente è necessario specificare l'account Mappe di Azure che si intende usare specificando l'ID client delle mappe. L'ID client dell'account Mappe di Azure è disponibile nelle sezioni Autenticazione dell'account Mappe di Azure. Per altre informazioni, vedere Visualizzare i dettagli di autenticazione.

Impostare i valori dell'ID applicazione (client), dell'ID directory (tenant), del segreto client dell'applicazione Microsoft Entra e dell'ID client della risorsa della mappa come variabili di ambiente:

Variabile di ambiente Descrizione
AZURE_CLIENT_ID ID applicazione (client) nell'applicazione registrata
AZURE_CLIENT_SECRET Valore del segreto client nell'applicazione registrata
AZURE_TENANT_ID ID directory (tenant) nell'applicazione registrata
MAPS_CLIENT_ID ID client nell'account Mappe di Azure

A questo punto è possibile creare variabili di ambiente in PowerShell per archiviare questi valori:

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

Dopo aver configurato le variabili di ambiente, è possibile usarle nel programma per creare un'istanza del AzureMapsSearch client. Creare un file denominato demo.py e aggiungere il codice seguente:

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
)

Importante

Le altre variabili di ambiente create nel frammento di codice precedente, mentre non vengono usate nell'esempio di codice, sono richieste da DefaultAzureCredential(). Se queste variabili di ambiente non vengono impostate correttamente, usando le stesse convenzioni di denominazione, si otterranno errori in fase di esecuzione. Ad esempio, se AZURE_CLIENT_ID è mancante o non è valido, verrà visualizzato un errore di InvalidAuthenticationTokenTenant.

Uso delle credenziali della chiave di sottoscrizione

È possibile eseguire l'autenticazione con la chiave di sottoscrizione di Mappe di Azure. La chiave di sottoscrizione è disponibile nella sezione Autenticazione nell'account Mappe di Azure, come illustrato nello screenshot seguente:

Screenshot che mostra la chiave di sottoscrizione di Mappe di Azure nel portale di Azure.

A questo punto è possibile creare variabili di ambiente in PowerShell per archiviare la chiave di sottoscrizione:

$Env:SUBSCRIPTION_KEY="your subscription key"

Dopo aver creato la variabile di ambiente, è possibile accedervi nel codice. Creare un file denominato demo.py e aggiungere il codice seguente:

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

Geocodificare un indirizzo

Il frammento di codice seguente illustra come, in una semplice applicazione console, ottenere coordinate di longitudine e latitudine per un determinato indirizzo. Questo esempio usa le credenziali della chiave di sottoscrizione per autenticare MapsSearchClient. 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()

Questo codice di esempio crea AzureKeyCredential un'istanza con la chiave di sottoscrizione Mappe di Azure, quindi la usa per creare un'istanza dell'oggettoMapsSearchClient. I metodi forniti da MapsSearchClient inoltrano la richiesta agli endpoint REST Mappe di Azure. Alla fine, il programma scorre i risultati e stampa le coordinate per ogni risultato.

Indirizzi di geocodifica batch

Questo esempio illustra come eseguire l'indirizzo di ricerca batch:

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

Effettuare una ricerca di indirizzi inversa per convertire la posizione delle coordinate in indirizzo

È possibile convertire le coordinate in indirizzi stradali leggibili. Questo processo è chiamato anche geocodifica inversa. Questo viene spesso usato per applicazioni che utilizzano feed GPS e vogliono individuare indirizzi in punti di coordinate specifici.

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

Richiesta batch per la geocodifica inversa

In questo esempio viene illustrato come eseguire la ricerca inversa in base alle coordinate 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()

Ottenere i poligoni per una determinata posizione

Questo esempio illustra come cercare i poligoni.

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

Uso degli SDK V1 per la ricerca e il rendering

Per usare Search V1 e Render V1 SDK, fare riferimento alla pagina Cerca pacchetto SDK V1 e rendering del pacchetto SDK V1 per altre informazioni.

Informazioni aggiuntive

Libreria client del pacchetto di ricerca Mappe di Azure nella documentazione dell'anteprima di Azure SDK per Python.