Compartir a través de

biblioteca cliente de Azure Maps Search Package para Python: versión 1.0.0b2

  • Artículo

Este paquete contiene un SDK de Python para Azure Maps Services for Search. Obtenga más información sobre Azure Maps Services aquí.

Código | fuente Documentación | de referencia de APIDocumentación del producto

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure admiten Python 2.7 finalizó el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Requisitos previos

Si usa la CLI de Azure, reemplace <resource-group-name> y <account-name> elija y seleccione un plan de tarifa adecuado en función de sus necesidades a través del <sku-name> parámetro . Consulte esta página para obtener más detalles.

az maps account create --resource-group <resource-group-name> --account-name <account-name> --sku <sku-name>

Instalar el paquete

Instale el SDK de Azure Maps Service Search.

pip install azure-maps-search

Crear y autenticar MapsSearchClient

Para crear un objeto de cliente para acceder a Azure Maps Search API, necesitará un objeto de credencial. Azure Maps cliente search también admite dos maneras de autenticarse.

1. Autenticación con una credencial de clave de suscripción

Puede autenticarse con la clave de suscripción de Azure Maps. Una vez creada la Azure Maps clave de suscripción, establezca el valor de la clave como variable de entorno: AZURE_SUBSCRIPTION_KEY. A continuación, pase un AZURE_SUBSCRIPTION_KEY como credential parámetro a una instancia de AzureKeyCredential.

from azure.core.credentials import AzureKeyCredential
from azure.maps.search import MapsSearchClient

credential = AzureKeyCredential(os.environ.get("AZURE_SUBSCRIPTION_KEY"))

search_client = MapsSearchClient(
    credential=credential,
)

2. Autenticación con una credencial de Azure Active Directory

Puede autenticarse con la credencial del token de Azure Active Directory (AAD) mediante la biblioteca de identidades de Azure. La autenticación mediante AAD requiere una configuración inicial:

Después de la instalación, puede elegir qué tipo de credencialazure.identity usar. Por ejemplo, Se puede usar DefaultAzureCredential para autenticar el cliente:

A continuación, establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

También deberá especificar el recurso de Azure Maps que desea usar especificando en clientId las opciones de cliente. El identificador de cliente de recursos Azure Maps se puede encontrar en las secciones Autenticación del recurso Azure Maps. Consulte la documentación sobre cómo encontrarlo.

from azure.maps.search import MapsSearchClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
search_client = MapsSearchClient(credential=credential)

Conceptos clave

La biblioteca cliente de Azure Maps Search para Python permite interactuar con cada uno de los componentes mediante el uso de un objeto de cliente dedicado.

Sincronizar clientes

MapsSearchClientes el cliente principal para desarrolladores que usa la biblioteca cliente de Azure Maps Search para Python. Una vez inicializada una MapsSearchClient clase, puede explorar los métodos de este objeto de cliente para comprender las distintas características de la Azure Maps servicio Search a la que puede acceder.

Clientes asincrónicos

Esta biblioteca incluye una API asincrónica completa compatible con Python 3.5 y versiones posteriores. Para usarlo, primero debe instalar un transporte asincrónico, como aiohttp. Consulte la documentación de azure-core para más información.

Los clientes y credenciales asincrónicos deben cerrarse cuando ya no sean necesarios. Estos objetos son administradores de contexto asincrónicos y definen métodos asincrónicos close .

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas de búsqueda de Azure Maps más comunes, entre las que se incluyen:

Solicitar coordenadas de latitud y longitud para una dirección

Puede usar un cliente autenticado para convertir una dirección en coordenadas de latitud y longitud. Este proceso también se denomina geocodificación. Además de devolver las coordenadas, la respuesta también devolverá propiedades de dirección detalladas como la calle, el código postal, el municipio y la información de país o región.

from azure.maps.search import MapsSearchClient

search_result = client.search_address("400 Broad, Seattle");

Buscar una dirección o un punto de interés

Puede usar la búsqueda aproximada para buscar una dirección o un punto de interés (POI). En los ejemplos siguientes se muestra cómo buscar pizza en el ámbito de un país específico (Franceen este ejemplo).

from azure.maps.search import MapsSearchClient

fuzzy_search_result = client.fuzzy_search(query: "pizza", country_filter: "fr" );

result_address = fuzzy_search_result.results[0].address

Realizar una búsqueda de direcciones inversas para traducir la ubicación de coordenadas a la dirección postal

Puede traducir las coordenadas en direcciones postales legibles humanas. Este proceso también se denomina geocodificación inversa. Esto se usa a menudo para aplicaciones que consumen fuentes GPS y quieren detectar direcciones en puntos de coordenadas específicos.

from azure.maps.search import MapsSearchClient

coordinates=(47.60323, -122.33028)

reverse_search_result = client.reverse_search_address(coordinates=coordinates);

result_summary = reverse_search_result.summary

Traducción de la ubicación de coordenadas en una calle cruzada comprensible

Traducir la ubicación de coordenadas a una calle transversal que pueda entender cualquier persona mediante Search Address Reverse Cross Street API. Por lo general, esto es necesario en las aplicaciones de seguimiento que reciben una fuente GPS de un dispositivo o recurso y desea saber en qué dirección se encuentra en la coordenada.

from azure.maps.search import MapsSearchClient

coordinates=(47.60323, -122.33028)

reverse_search_result = client.reverse_search_cross_street_address(coordinates=coordinates);

result_address = reverse_search_result.results[0].address

Obtención de un lote de búsqueda aproximada asincrónico con param y batchid

En este ejemplo se muestra cómo realizar la búsqueda aproximada por ubicación y lat/lon con el método de lote asincrónico. Esta función acepta y search_queriesbatch_id devuelve un AsyncLRO objeto . Aquí batch_id se puede usar para recuperar el objeto LRO más adelante que duran 14 días.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

async with maps_search_client:
    result = await maps_search_client.begin_fuzzy_search_batch(
        search_queries=[
            "350 5th Ave, New York, NY 10118&limit=1",
            "400 Broad St, Seattle, WA 98109&limit=6"
        ]
    )

batch_id = result.batch_id

El método begin_fuzzy_search_batch() también acepta batch_id como parámetro . Aquí batch_id se puede usar para recuperar el objeto LRO más adelante que duran 14 días.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

async with maps_search_client:
    result = await maps_search_client.begin_fuzzy_search_batch(
        batch_id=batch_id
    )

result = result.response

No se puede obtener la sincronización por lotes de búsqueda aproximada

En este ejemplo se muestra cómo comprobar si hay errores en la búsqueda de fuzzy_search_batch.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

result = maps_search_client.fuzzy_search_batch(
    search_queries=[
        "350 5th Ave, New York, NY 10118&limit=1",
        "400 Broad St, Seattle, WA 98109&lim"
    ]
)
for item in result.items:
    count = 0
    if item.response.error is not None:
        count = count+1
        print(f"Error: {item.response.error.message}")
print(f"There are total of {count} search queries failed.")

Buscar dentro de Geometry

En este ejemplo se muestra cómo realizar la búsqueda dentro de la geometría mediante un destino dado, como pizza y varias geometrías diferentes como entrada con el objeto GeoJson.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

geo_json_obj1 = {
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [[
                    [-122.143035,47.653536],
                    [-122.187164,47.617556],
                    [-122.114981,47.570599],
                    [-122.132756,47.654009],
                    [-122.143035,47.653536]
                    ]]
            },
            "properties": {}
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [-122.126986,47.639754]
            },
            "properties": {
                "subType": "Circle",
                "radius": 100
            }
        }
    ]
}
result1 = maps_search_client.search_inside_geometry(
    query="pizza",
    geometry=geo_json_obj1
)
print("Search inside geometry with standard GeoJson object as input, FeatureCollection:")
print(result1)

En este ejemplo se muestra cómo trabajar con otros paquetes existentes, como shapely para realizar búsquedas dentro de la geometría mediante un destino determinado, como pizza.

maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))

from shapely.geometry import Polygon

geo_interface_obj = Polygon([
    [-122.43576049804686, 37.7524152343544],
    [-122.43301391601562, 37.70660472542312],
    [-122.36434936523438, 37.712059855877314],
    [-122.43576049804686, 37.7524152343544]
])

result3 = maps_search_client.search_inside_geometry(
    query="pizza",
    geometry=geo_interface_obj
)
print("Search inside geometry with Polygon from third party library `shapely` with geo_interface as result 3:")
print(result2)

Solución de problemas

General

Los clientes de Maps Search generan excepciones definidas en Azure Core.

Esta lista se puede usar como referencia para detectar excepciones producidas. Para obtener el código de error específico de la excepción, use el error_code atributo , es decir, exception.error_code.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel de DEPURACIÓN, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el logging_enable argumento :

import sys
import logging
from azure.maps.search import MapsSearchClient

# Create a logger for the 'azure.maps.search' SDK
logger = logging.getLogger('azure.maps.search')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

service_client.get_service_stats(logging_enable=True)

Adicional

¿Sigue experimentando problemas? Si encuentra algún error o tiene sugerencias, envíe un problema en la sección Problemas del proyecto.

Pasos siguientes

Más código de ejemplo

Introducción a nuestros ejemplos de Búsqueda de Mapas (ejemplos de versión asincrónica).

Hay varios ejemplos de SDK de Python de Azure Maps Search disponibles en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con la búsqueda de Mapas

set AZURE_SUBSCRIPTION_KEY="<RealSubscriptionKey>"

pip install azure-maps-search --pre

python samples/sample_authentication.py
python sample/sample_fuzzy_search.py
python samples/sample_get_point_of_interest_categories.py
python samples/sample_reverse_search_address.py
python samples/sample_reverse_search_cross_street_address.py
python samples/sample_search_nearby_point_of_interest.py
python samples/sample_search_point_of_interest_category.py
python samples/sample_search_point_of_interest.py
python samples/sample_search_structured_address.py

Notas: --pre la marca se puede agregar opcionalmente, es incluir versiones preliminares y de desarrollo para pip install. De forma predeterminada, pip solo encuentra versiones estables.

Para más información, consulte La introducción de ejemplos.

Documentación adicional

Para obtener documentación más amplia sobre Azure Maps Search, consulte la documentación de Azure Maps Search en docs.microsoft.com.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.