Guia de desenvolvedores do SDK REST do Python (versão prévia)

O SDK do Python do Azure Mapas pode ser integrado a aplicativos e bibliotecas Python para criar aplicativos relacionados a mapas e com reconhecimento de localização. O SDK do Python do Azure Mapas contém APIs para Pesquisa, Rota, Renderização e Geolocalização. Essas APIs dão suporte a operações como a pesquisa de endereço, o roteamento entre coordenadas diferentes, a obtenção da geolocalização de um endereço IP específico.

Pré-requisitos

• Conta do Azure Mapas.
• Chave de assinatura ou outra forma de autenticação com Azure Mapas.
• Python na versão 3.8 ou posterior. É recomendável usar a versão mais recente. Para obter mais informações, confira a Política de suporte de versão do SDK do Azure para Python.

Dica

Você pode criar uma conta Azure Mapas programaticamente. Aqui está um exemplo usando a CLI do Azure:

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

Crie um projeto do Python

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

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py 

Instalar pacotes do Python necessários

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

Aqui, instalamos o pacote de Pesquisa do Azure Mapas. Como ainda está em versão prévia pública, você precisa adicionar o sinalizador --pre:

pip install azure-maps-search --pre 

Serviços do Azure Mapas

O SDK do Python do Azure Mapas 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 do SDK do Azure para Python.

Nome do serviço	Pacote PyPi	Exemplos
Pesquisa	azure-maps-search	exemplos de pesquisas
Route	azure-maps-route	exemplos de rota
Render	azure-maps-render	renderizar amostra
Geolocalização	azure-maps-geolocation	exemplo de geolocalização

Criar e autenticar um MapsSearchClient

Você precisará de um objeto credential para autenticação ao criar o objeto MapsSearchClient usado para acessar as APIs de pesquisa do Azure Mapas. 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, confira Autenticação no Azure Mapas.

Dica

O MapsSearchClient é a interface principal para desenvolvedores que usam a biblioteca de pesquisa do Azure Mapas. Consulte Biblioteca de clientes do pacote de Pesquisa do Azure Mapas para saber mais sobre os métodos de pesquisa disponíveis.

Como usar uma credencial do Microsoft Entra

Você pode autenticar com o Microsoft Entra ID usando o pacote de Identidade do Azure. Para usar o provedor DefaultAzureCredential, você precisará instalar o pacote de clientes da Identidade do Azure:

pip install azure-identity 

Você precisará registrar o novo aplicativo do Microsoft Entra e permitir acesso ao Azure Mapas atribuindo a função necessária à entidade de serviço. Para obter mais informações, confira Hospedar um daemon em recursos que não são 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ê precisará deles nas etapas a seguir.

Em seguida, você precisará especificar a conta do Azure Mapas que pretende usar especificando a ID do cliente dos mapas. A ID do cliente da conta do Azure Mapas pode ser encontrada nas seções de Autenticação da conta do Azure Mapas. Para mais informações, consulte a 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 aplicativo do Microsoft Entra e a ID do cliente do recurso de mapa como variáveis de ambiente:

Variável de ambiente	Descrição
AZURE_CLIENT_ID	ID do aplicativo (cliente) no aplicativo registrado
AZURE_CLIENT_SECRET	O valor do segredo do cliente no aplicativo registrado
AZURE_TENANT_ID	ID do diretório (locatário) no aplicativo registrado
MAPS_CLIENT_ID	A ID do cliente na conta do Azure Mapas

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 criar uma instância do cliente AzureMapsSearch. 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
)

Importante

As outras variáveis de ambiente criadas no snippet de código anterior, embora não sejam usadas no exemplo de código, são exigidas pela DefaultAzureCredential(). Se você não definir essas variáveis de ambiente corretamente, usando as mesmas convenções de nomenclatura, receberá erros em tempo de execução. Por exemplo, se o AZURE_CLIENT_ID for ignorado ou inválido, você receberá um erro InvalidAuthenticationTokenTenant.

Usando uma credencial de chave de assinatura

Você pode autenticar com sua chave de assinatura do Azure Mapas. Sua chave de assinatura pode ser encontrada na seção Autenticação na conta do Azure Mapas, conforme mostrado na seguinte captura de tela:

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

O código de exemplo acima cria uma instância AzureKeyCredential com a chave de assinatura do Azure Mapas e, em seguida, cria uma instância do objeto MapsSearchClient. Os métodos fornecidos por MapsSearchClient encaminham a solicitação para os pontos de extremidade REST do Azure Mapas. No final, o programa itera pelos resultados e imprime as coordenadas para cada resultado.

Endereços de código geográfico do 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 Inverso para traduzir o local da coordenada para o endereço de rua

Você pode traduzir coordenadas em endereços de rua legíveis por humanos. Esse processo também é chamado de geocodificação reversa. Isso geralmente é usado para aplicativos que consomem feeds GPS e desejam 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 em lote para geocodificação reversa

Este exemplo demonstra como executar a pesquisa inversa 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 SDK de Pesquisa V1 e Renderização V1, consulte a página de pacote do SDK da Pesquisa V1 e renderize o pacote do SDK V1 para obter mais informações.

Informações adicionais

A biblioteca de clientes do Pacote de pesquisa do Azure Mapas na documentação do SDK do Azure para versão prévia do Python.