Guía para desarrolladores del SDK de REST de Python (versión preliminar)

Artículo
08/17/2024

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.

Requisitos previos

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"

Creación de un proyecto en Python

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

Instalación de los paquetes de Python necesarios

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

Servicios de Azure Maps

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

Creación y autenticación de un objeto MapsSearchClient

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.

Uso de la credencial de Microsoft Entra

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.

Uso de una credencial de clave de suscripción

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

Geocodificación de una dirección

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.

Direcciones de geocodificación por lotes

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

Solicitud por lotes para la geocodificación inversa

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

Obtención de polígonos para una ubicación determinada

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

Uso de SDK V1 para Búsqueda y Representar

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.

Información adicional

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.

Compartir a través de