Azure Maps bibliothèque cliente de package de recherche pour Python - version 1.0.0b2

  • Article

Ce package contient un Kit de développement logiciel (SDK) Python pour Azure Maps Services pour la recherche. En savoir plus sur Azure Maps Services ici

| Code sourceDocumentation de référence sur les | API Documentation produit

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Prérequis

Si vous utilisez Azure CLI, remplacez <resource-group-name> et <account-name> de votre choix, puis sélectionnez un niveau tarifaire approprié en fonction de vos besoins via le <sku-name> paramètre . Pour plus d’informations, consultez cette page.

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

Installer le package

Installez le Kit de développement logiciel (SDK) Azure Maps Service Search.

pip install azure-maps-search

Créer et authentifier mapsSearchClient

Pour créer un objet client afin d’accéder à l’API recherche Azure Maps, vous avez besoin d’un objet d’informations d’identification. Azure Maps client De recherche prend également en charge deux façons de s’authentifier.

1. S’authentifier avec des informations d’identification de clé d’abonnement

Vous pouvez vous authentifier avec votre clé d’abonnement Azure Maps. Une fois la clé d’abonnement Azure Maps créée, définissez la valeur de la clé comme variable d’environnement : AZURE_SUBSCRIPTION_KEY. Passez ensuite un AZURE_SUBSCRIPTION_KEY en tant que credential paramètre dans une instance d’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. S’authentifier avec des informations d’identification Azure Active Directory

Vous pouvez vous authentifier avec les informations d’identification de jeton Azure Active Directory (AAD) à l’aide de la bibliothèque d’identités Azure. L’authentification à l’aide d’AAD nécessite une configuration initiale :

Après l’installation, vous pouvez choisir le type d’informations d’identificationazure.identity à utiliser. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client :

Ensuite, définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Vous devez également spécifier la ressource Azure Maps que vous envisagez d’utiliser en spécifiant dans clientId les options client. L’ID client de la ressource Azure Maps se trouve dans les sections Authentification de la ressource Azure Maps. Reportez-vous à la documentation pour savoir comment le trouver.

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

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

Concepts clés

La bibliothèque cliente de recherche Azure Maps pour Python vous permet d’interagir avec chacun des composants à l’aide d’un objet client dédié.

Synchroniser les clients

MapsSearchClientest le client principal pour les développeurs qui utilisent la bibliothèque de client recherche Azure Maps pour Python. Une fois que vous avez initialisé une MapsSearchClient classe, vous pouvez explorer les méthodes de cet objet client pour comprendre les différentes fonctionnalités de l’Azure Maps service Search auxquelles vous pouvez accéder.

Clients asynchrones

Cette bibliothèque inclut une API asynchrone complète prise en charge sur Python 3.5+. Pour l’utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Pour plus d’informations, consultez la documentation azure-core .

Les clients et les informations d’identification asynchrones doivent être fermés lorsqu’ils ne sont plus nécessaires. Ces objets sont des gestionnaires de contexte asynchrones et définissent des méthodes asynchrones close .

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches de recherche Azure Maps les plus courantes, notamment :

Demander des coordonnées de latitude et de longitude pour une adresse

Vous pouvez utiliser un client authentifié pour convertir une adresse en coordonnées de latitude et de longitude. Ce processus est également appelé géocodage. En plus de retourner les coordonnées, la réponse retourne également des propriétés détaillées de l’adresse telles que la rue, le code postal, la commune et les informations relatives au pays ou à la région.

from azure.maps.search import MapsSearchClient

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

Rechercher une adresse ou un point d’intérêt

Vous pouvez utiliser la recherche approximative pour rechercher une adresse ou un point d’intérêt (POI). Les exemples suivants montrent comment effectuer une recherche pizza dans l’étendue d’un pays spécifique (Francedans cet exemple).

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

Effectuer une recherche d’adresse inversée pour traduire l’emplacement des coordonnées en adresse postale

Vous pouvez traduire des coordonnées en adresses postales lisibles par l’homme. Ce processus est également appelé géocodage inverse. Cela est souvent utilisé pour les applications qui utilisent des flux GPS et qui souhaitent découvrir des adresses à des points de coordonnées spécifiques.

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

Traduire l’emplacement de coordonnées en une rue croisée compréhensible par l’homme

Traduisez l’emplacement des coordonnées en une intersection compréhensible en utilisant de l’API Search Address Reverse Cross Street. Le plus souvent, cela est nécessaire dans les applications de suivi qui reçoivent le flux GPS d’un appareil ou d’une ressource et qui souhaitent connaître l’emplacement auquel correspondent les coordonnées.

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

Obtenir un lot de recherche approximative asynchrone avec param et batchid

Cet exemple montre comment effectuer une recherche approximative par emplacement et par lat/lon avec la méthode de lot asynchrone. Cette fonction accepte à la fois search_queries et batch_id retourne un AsyncLRO objet . Le batch_id ici peut être utilisé pour récupérer l’objet LRO plus tard, qui dure 14 jours.

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

La méthode begin_fuzzy_search_batch() accepte batch_id également comme paramètre. Le batch_id ici peut être utilisé pour récupérer l’objet LRO plus tard, qui dure 14 jours.

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

Échec de l’obtention de la synchronisation par lots de recherche approximative

Cet exemple montre comment vérifier s’il existe des échecs dans la recherche 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.")

Rechercher dans Geometry

Cet exemple montre comment effectuer une recherche à l’intérieur de geometry par cible donnée, par pizza exemple et plusieurs géométries différentes en tant qu’entrée avec l’objet 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)

Cet exemple montre comment utiliser d’autres packages existants, par exemple shapely pour effectuer une recherche à l’intérieur de geometry par une cible donnée telle que 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)

Dépannage

Général

Les clients de recherche mappent des exceptions définies dans Azure Core.

Cette liste peut être utilisée à des fins de référence pour intercepter les exceptions levées. Pour obtenir le code d’erreur spécifique de l’exception, utilisez l’attribut error_code , exception.error_codec’est-à-dire .

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument logging_enable :

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)

De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :

service_client.get_service_stats(logging_enable=True)

Informations supplémentaires

Vous rencontrez toujours des problèmes ? Si vous rencontrez des bogues ou si vous avez des suggestions, signalez un problème dans la section Problèmes du projet.

Étapes suivantes

Autres exemples de code

Prise en main de nos exemples de recherche de cartes (exemples de version asynchrone).

Plusieurs exemples Azure Maps search python SDK sont disponibles dans le dépôt GitHub du SDK. Ces exemples fournissent un exemple de code pour d’autres scénarios couramment rencontrés lors de l’utilisation de La recherche de cartes

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

Remarques : --pre l’indicateur peut être ajouté éventuellement. Il s’agit d’inclure les versions de préversion et de développement pour pip install. Par défaut, pip recherche uniquement les versions stables.

Pour plus d’informations, reportez-vous à La présentation des exemples

Documentation complémentaire

Pour obtenir une documentation plus complète sur Azure Maps Recherche, consultez la documentation recherche Azure Maps sur docs.microsoft.com.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.