Guía para desarrolladores del SDK de REST de Python (versión preliminar)
El SDK de Python de Azure Maps se puede integrar con las aplicaciones y bibliotecas de Python para crear aplicaciones relacionadas con mapas y con la ubicación. El SDK de Python de Azure Maps contiene API de búsqueda, enrutamiento, representación y geolocalización. Estas API admiten operaciones como la búsqueda de una dirección, el enrutamiento entre diferentes coordenadas y la obtención de la ubicación geográfica de una dirección IP específica.
- Una cuenta de Azure Maps.
- Una clave de suscripción u otra forma de autenticación con Azure Maps.
- Python 3.8 o versiones posteriores. Se recomienda usar la versión más reciente. Para más información, consulte La Directiva de compatibilidad con versiones del SDK de Azure para Python.
Sugerencia
Puede crear una cuenta de Azure Maps mediante programación. A continuación se muestra un ejemplo mediante la CLI de Azure:
az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"
En el ejemplo siguiente se muestra cómo crear un programa de consola denominado demo
con Python:
mkdir mapsDemo
cd mapsDemo
New-Item demo.py
Cada servicio de Azure Maps está incluido en su propio paquete. Al usar el SDK de Python de Azure Maps, puede instalar solo los paquetes de los servicios que necesita.
Aquí se instala el paquete Azure Maps Search. Dado que todavía está en versión preliminar pública, debe agregar la marca --pre
:
pip install azure-maps-search --pre
Azure Maps SDK de Python admite python versión 3.8 o posterior. Para más información sobre las versiones futuras de Python, consulte Directiva de compatibilidad con versiones del SDK de Azure para Python.
Nombre del servicio | Paquete PyPi | Ejemplos |
---|---|---|
Búsqueda | azure-maps-search | ejemplos de búsqueda |
Route | azure-maps-route | Ejemplos de rutas |
Representar | azure-maps-render | Ejemplo de representación |
Geolocalización | azure-maps-geolocation | ejemplo de geolocalización |
Necesita un objeto credential
para la autenticación cuando cree el objeto MapsSearchClient
que se usa para acceder a las API de búsqueda de Azure Maps. Puede usar una credencial de Microsoft Entra o una clave de suscripción de Azure para autenticarse. Para obtener más información sobre la autenticación, consulte Autenticación con Azure Maps.
Sugerencia
El objeto MapsSearchClient
es la interfaz principal para los desarrolladores que usan la biblioteca de búsqueda de Azure Maps. Consulte Biblioteca cliente del paquete Azure Maps Search para más información sobre los métodos de búsqueda disponibles.
Puede autenticarse con Microsoft Entra ID mediante la paquete de identidad de Azure. Para usar el proveedor DefaultAzureCredential, debe instalar el paquete de cliente de identidad de Azure:
pip install azure-identity
Debe registrar la nueva aplicación Microsoft Entra y conceder acceso a Azure Maps mediante la asignación del rol necesario a la entidad de servicio. Para más información, consulte Hospedaje de un demonio en recursos que no son de Azure. Se devuelve el id. de aplicación (cliente), un id. de directorio (inquilino) y un secreto de cliente. Copie estos valores y guárdelos en lugar seguro. Los necesitará en los pasos siguientes.
A continuación, debe especificar la cuenta de Azure Maps que va a usar especificando el identificador de cliente de los mapas. El identificador de cliente de la cuenta de Azure Maps se puede encontrar en las secciones Autenticación de dicha cuenta. Para más información, consulte Visualización de los detalles de autenticación.
Establezca los valores del identificador de aplicación (cliente), el identificador de directorio (inquilino) y el secreto de cliente de la aplicación Microsoft Entra y el identificador de cliente del recurso de asignación como variables de entorno:
Variable de entorno | Descripción |
---|---|
AZURE_CLIENT_ID | Identificador de aplicación (cliente) de la aplicación registrada |
AZURE_CLIENT_SECRET | Valor del secreto de cliente de la aplicación registrada |
AZURE_TENANT_ID | Identificador de directorio (inquilino) de la aplicación registrada |
MAPS_CLIENT_ID | Identificador de cliente de la cuenta de Azure Maps |
Ahora puede crear variables de entorno en PowerShell para almacenar estos valores:
$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"
Después de configurar las variables de entorno, puede usarlas en el programa para crear instancias del cliente AzureMapsSearch
. Cree un archivo llamado demo.py y agregue el siguiente código:
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
Las demás variables de entorno creadas en el fragmento de código anterior, aunque no se usan en el ejemplo de código, son necesarias para DefaultAzureCredential()
. Si no establece correctamente estas variables de entorno, con las mismas convenciones de nomenclatura, obtendrá errores en tiempo de ejecución. Por ejemplo, si AZURE_CLIENT_ID
falta o no es válido, obtendrá un error InvalidAuthenticationTokenTenant
.
Puede autenticarse con la clave de suscripción de Azure Maps. Encontrará la clave de suscripción en la sección Autenticación de la cuenta de Azure Maps, como se muestra en la captura de pantalla siguiente:
Ahora puede crear variables de entorno en PowerShell para almacenar la clave de suscripción:
$Env:SUBSCRIPTION_KEY="your subscription key"
Una vez que se haya creado la variable de entorno, puede acceder a ella en el código. Cree un archivo llamado demo.py y agregue el siguiente código:
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)
)
El siguiente fragmento de código muestra cómo obtener coordenadas de longitud y latitud para una dirección determinada en una aplicación de consola sencilla. En este ejemplo se usan credenciales de clave de suscripción para autenticar MapsSearchClient. En 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()
Este código de ejemplo crea instancias de AzureKeyCredential
con la clave de suscripción de Azure Maps y, luego, la usa para crear instancias del objeto MapsSearchClient
. Los métodos proporcionados por MapsSearchClient
reenvían la solicitud a los puntos de conexión REST de Azure Maps. Al final, el programa recorre en iteración los resultados e imprime las coordenadas de cada resultado.
En este ejemplo se muestra cómo realizar la dirección de búsqueda por lotes:
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()
Realizar una búsqueda de dirección inversa para traducir la ubicación de coordenadas a la dirección postal
Puede traducir las coordenadas en direcciones legibles para cualquier persona. Este proceso también se denomina geocodificación inversa. Esto se usa a menudo para las aplicaciones que consumen fuentes GPS y desean detectar direcciones en puntos de coordenadas específicos.
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()
En este ejemplo se muestra cómo realizar la búsqueda inversa mediante coordenadas dadas por lotes.
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()
En este ejemplo se muestra cómo buscar polígonos.
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()
Para usar el SDK de Búsqueda V1 y Representar V1, consulte la página del paquete del SDK de Búsqueda V1 y el paquete del SDK de Representar V1 para obtener más información.
La biblioteca cliente del paquete Azure Maps Search en la documentación de la versión preliminar del kit de desarrollo de software de Azure para Python.