Guia de desenvolvedores do SDK Python REST (visualização)

O SDK Python do Azure Maps pode ser integrado com aplicativos e bibliotecas Python para criar aplicativos relacionados a mapas e com reconhecimento de local. O SDK Python do Azure Maps contém APIs para Pesquisa, Rota, Renderização e Localização Geográfica. Essas APIs suportam operações como a busca de um endereço, roteamento entre diferentes coordenadas, obtenção da geolocalização de um endereço IP específico.

Pré-requisitos

• Conta do Azure Maps.
• Chave de subscrição ou outra forma de Autenticação com o Azure Maps.
• Python em 3.8 ou posterior. Recomenda-se usar a versão mais recente. Para obter mais informações, consulte Política de suporte de versão do SDK do Azure para Python.

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

Criar um projeto python

O exemplo a seguir mostra como criar um programa de console chamado demo com Python:

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py 

Instale os pacotes python necessários

Cada serviço no Azure Maps está contido em seu próprio pacote. Ao usar o SDK Python do Azure Maps, você pode instalar apenas os pacotes dos serviços necessários.

Aqui instalamos o pacote de Pesquisa do Azure Maps. Como ainda está em visualização pública, você precisa adicionar a --pre bandeira:

pip install azure-maps-search --pre 

Serviços do Azure Maps

O SDK do Python do Azure Maps dá suporte ao Python versão 3.8 ou posterior. Para obter mais informações sobre versões futuras do Python, consulte Política de suporte de versão do SDK do Azure para Python.

Criar e autenticar um MapsSearchClient

Você precisa de um credential objeto para autenticação ao criar o MapsSearchClient objeto usado para acessar as APIs de pesquisa do Azure Maps. Você pode usar uma credencial do Microsoft Entra ou uma chave de assinatura do Azure para autenticar. Para obter mais informações sobre autenticação, consulte Autenticação com mapas do Azure.

Usando uma credencial do Microsoft Entra

Você pode autenticar com o Microsoft Entra ID usando o pacote Azure Identity. Para usar o provedor DefaultAzureCredential , você precisa instalar o pacote do cliente do Azure Identity:

pip install azure-identity 

Você precisa registrar o novo aplicativo Microsoft Entra e conceder acesso ao Azure Maps atribuindo a função necessária à sua entidade de serviço. Para obter mais informações, consulte Hospedar um daemon em recursos que não sejam do Azure. A ID do aplicativo (cliente), uma ID de diretório (locatário) e um segredo do cliente são retornados. Copie esses valores e armazene-os em um local seguro. Você precisa deles nas etapas a seguir.

Em seguida, você precisa especificar a conta do Azure Maps que pretende usar especificando a ID do cliente dos mapas. A ID do cliente da conta do Azure Maps pode ser encontrada nas seções Autenticação da conta do Azure Maps. Para obter mais informações, consulte Exibir detalhes de autenticação.

Defina os valores da ID do aplicativo (cliente), da ID do diretório (locatário) e do segredo do cliente do seu aplicativo Microsoft Entra e da ID do cliente do recurso de mapa como variáveis de ambiente:

Agora você pode criar variáveis de ambiente no PowerShell para armazenar esses 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"

Depois de configurar as variáveis de ambiente, você pode usá-las em seu programa para instanciar o AzureMapsSearch cliente. Crie um arquivo chamado demo.py e adicione o seguinte 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
)

Usando uma credencial de chave de assinatura

Pode autenticar-se com a sua chave de subscrição do Azure Maps. Sua chave de assinatura pode ser encontrada na seção Autenticação na conta do Azure Maps, conforme mostrado na captura de tela a seguir:

Agora você pode criar variáveis de ambiente no PowerShell para armazenar a chave de assinatura:

$Env:SUBSCRIPTION_KEY="your subscription key"

Depois que a variável de ambiente for criada, você poderá acessá-la em seu código. Crie um arquivo chamado demo.py e adicione o seguinte 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)
)

Geocodificar um endereço

O trecho de código a seguir demonstra como, em um aplicativo de console simples, obter coordenadas de longitude e latitude para um determinado endereço. Este exemplo usa credenciais de chave de assinatura para autenticar MapsSearchClient. Em 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 exemplo é instanciado AzureKeyCredential com a chave de assinatura do Azure Maps e, em seguida, usa-o para instanciar o MapsSearchClient objeto. Os métodos fornecidos encaminhando MapsSearchClient a solicitação para os pontos de extremidade REST do Azure Maps. No final, o programa itera através dos resultados e imprime as coordenadas para cada resultado.

Endereços de geocódigo de lote

Este exemplo demonstra como executar o endereço de pesquisa em lote:

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

Fazer uma Pesquisa de Endereço Inversa para traduzir a localização da coordenada para o endereço

Você pode traduzir coordenadas em endereços legíveis por humanos. Este processo também é chamado de geocodificação reversa. Isso é frequentemente usado para aplicativos que consomem feeds GPS e querem descobrir endereços em pontos 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()

Solicitação de lote para geocodificação reversa

Este exemplo demonstra como executar a pesquisa reversa por determinadas coordenadas em lote.

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

Obter polígonos para um determinado local

Este exemplo demonstra como pesquisar 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()

Usando SDKs V1 para pesquisa e renderização

Para usar o Search V1 e o Render V1 SDK, consulte a página do pacote Search V1 SDK e o pacote Render V1 SDK para obter mais informações.

Informações adicionais

A biblioteca de cliente do pacote Azure Maps Search na documentação do SDK do Azure para Python Preview .