Guide du développeur sur le SDK REST Python (préversion)

Article
08/17/2024

Le SDK Python Azure Maps peut être intégré aux bibliothèques et applications Python pour créer des applications liées au mappage et prenant en charge la localisation. Le SDK Python Azure Maps contient des API pour la recherche, l’itinéraire, le rendu et la géolocalisation. Ces API prennent en charge des opérations telles que la recherche d’une adresse, l’acheminement entre différentes coordonnées et l’obtention de la géolocalisation d’une adresse IP spécifique.

Prérequis

Compte Azure Maps.
Clé d’abonnement ou autre forme d’authentification avec Azure Maps.
Python 3.8 ou version ultérieure. Il est recommandé d’utiliser la version la plus récente. Pour plus d’informations, consultez la politique de support de la version Azure SDK pour Python.

Conseil

Vous pouvez créer un compte Azure Maps par programmation. Voici un exemple qui utilise Azure CLI :

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

Créer un projet Python

L’exemple suivant montre comment créer un programme de console nommé demo avec Python :

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py

Installer les packages Python nécessaires

Chaque service dans Azure Maps est contenu dans son propre package. Lorsque vous utilisez le SDK Python Azure Maps, vous pouvez installer uniquement les packages des services dont vous avez besoin.

Ici, nous installons le package de recherche Azure Maps Search. Étant donné qu’il est toujours en préversion publique, vous devez ajouter l’indicateur --pre :

pip install azure-maps-search --pre

Services Azure Maps

Le SDK Python Azure Maps prend en charge Python version 3.8 ou ultérieure. Pour plus d’informations sur les futures versions de Python, consultez la politique de support de la version Azure SDK pour Python.

Nom du service	Package PyPi	Exemples
action	azure-maps-search	exemples de recherches
Itinéraire	azure-maps-route	exemples d’itinéraires
Render	azure-maps-render	afficher l’exemple
Géolocalisation	azure-maps-geolocation	exemple de géolocalisation

Créer et authentifier un objet MapsSearchClient

Vous avez besoin d’un objet credential pour l’authentification lors de la création de l’objet MapsSearchClient utilisé pour accéder aux API de recherche Azure Maps. Vous pouvez utiliser des informations d’identification Microsoft Entra ou une clé d’abonnement Azure pour vous authentifier. Pour plus d’informations sur l’authentification, consultez Authentification avec Azure Maps.

Conseil

MapsSearchClient est l’interface principale pour les développeurs qui utilisent la bibliothèque de recherche Azure Maps. Pour en savoir plus sur les méthodes de recherche disponibles, consultez la bibliothèque de client Azure Maps package Search.

Utilisation des informations d'identification Microsoft Entra

Vous pouvez vous authentifier auprès de Microsoft Entra ID à l’aide du package Azure Identity. Pour utiliser le fournisseur DefaultAzureCredential, vous devez installer le package client Azure Identity :

pip install azure-identity

Vous devez inscrire la nouvelle application Microsoft Entra et accorder l’accès à Azure Maps en attribuant le rôle nécessaire à votre principal de service. Pour plus d’informations, consultez Héberger un démon sur des ressources non-Azure. L’ID d’application (client), un ID de répertoire (locataire) et une clé secrète client sont retournés. Copiez ces valeurs et stockez-les dans un endroit sécurisé. Vous en aurez besoin dans les étapes qui suivent.

Vous devez ensuite spécifier le compte Azure Maps que vous envisagez d’utiliser en spécifiant l’ID client des cartes. L’ID client du compte Azure Maps se trouve dans les sections Authentification du compte Azure Maps. Pour plus d’informations, consultez Afficher les détails d’authentification.

Définissez les valeurs de l’ID d’application (client), de l’ID de répertoire (tenant) et de la clé secrète client de votre application Microsoft Entra, ainsi que l’ID client de la ressource de carte en tant que variables d’environnement :

Variable d’environnement	Description
AZURE_CLIENT_ID	ID d’application (client) dans votre application inscrite
AZURE_CLIENT_SECRET	Valeur de la clé secrète client dans votre application inscrite
AZURE_TENANT_ID	ID d’annuaire (locataire) dans votre application inscrite
MAPS_CLIENT_ID	ID client dans votre compte Azure Map

Vous pouvez maintenant créer des variables d’environnement dans PowerShell pour stocker ces valeurs :

$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"

Après avoir configuré les variables d'environnement, vous pouvez les utiliser dans votre programme pour instancier le client AzureMapsSearch. Créez un fichier nommé demo.py et ajoutez le code suivant :

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
)

Important

Les autres variables d'environnement créées dans l’extrait de code précédent, bien que non utilisées dans l'exemple de code ici, sont requises par DefaultAzureCredential(). Si vous ne définissez pas ces variables d’environnement correctement, en utilisant les mêmes conventions de nommage, vous obtiendrez des erreurs d’exécution. Par exemple, si votre AZURE_CLIENT_ID est manquant ou invalide, vous obtiendrez une erreur InvalidAuthenticationTokenTenant.

Utilisation d’informations d’identification de clé d’abonnement

Vous pouvez vous authentifier avec votre clé d’abonnement Azure Maps. Votre clé d’abonnement se trouve dans la section Authentification du compte Azure Maps, comme illustré dans la capture d’écran suivante :

Vous pouvez maintenant créer des variables d’environnement dans PowerShell pour stocker la clé d’abonnement :

$Env:SUBSCRIPTION_KEY="your subscription key"

Une fois votre variable d’environnement créée, vous pouvez y accéder dans votre code. Créez un fichier nommé demo.py et ajoutez le code suivant :

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

Géocoder une adresse

L’extrait de code suivant montre comment obtenir des coordonnées de longitude et de latitude pour une adresse donnée dans une application console simple. Cet exemple utilise les informations d’identification de la clé d’abonnement pour authentifier MapsSearchClient. Dans 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()

Cet exemple de code instancie AzureKeyCredential avec la clé d’abonnement Azure Maps, puis pour instancier l’objet MapsSearchClient. Les méthodes fournies par MapsSearchClient transfèrent la demande aux points de terminaison REST Azure Maps. À la fin, le programme itère au sein des résultats et imprime les coordonnées de chaque résultat.

Géocoder des adresses par lots

Cet exemple montre comment effectuer une recherche d’adresses par lots :

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

Créer une recherche d’adresse inversée pour traduire les coordonnées de l’emplacement en adresse postale

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

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

Demande par lots pour le géocodage inverse

Cet exemple montre comment effectuer une recherche inverse avec des coordonnées par lots.

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

Obtenir des polygones pour une localisation donnée

Cet exemple montre comment rechercher dans des polygones.

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

Utilisation des kits SDK V1 pour Search et Render

Pour utiliser le SDK Search V1 et Render V1, reportez-vous à la page du package du SDK Search V1 et du package du SDK Render V1 pour plus d’informations.

Informations supplémentaires

La bibliothèque cliente du package Azure Maps Search dans la documentation de la Préversion du SDK Azure pour Python.

Partager via