Guida per gli sviluppatori di Python REST SDK (anteprima)
Articolo
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.
Python nella versione 3.8 o successiva. È consigliabile usare la versione più recente. Per altre informazioni, vedere Criteri di supporto della versione di Azure SDK per Python.
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:
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.
È 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:
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:
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.
Verranno fornite informazioni su come scrivere il codice necessario per interagire con Mappe di Azure, Sviluppare e testare un'app divertente con JavaScript e Visual Studio Code per trovare l'itinerario migliore per un camion, un'auto o una bicicletta. L'itinerario si snoderà dalla costa occidentale alla costa orientale degli Stati Uniti. È possibile osservare come l'itinerario cambi in base al veicolo. come l'itinerario sia diverso per i camion che trasportano materiali pericolosi. Si ha anche la possibili