Share via

biblioteca cliente pacote de pesquisa Azure Maps para Python - versão 1.0.0b2

  • Artigo

Este pacote contém um Python SDK para Azure Maps Serviços de Pesquisa. Leia mais sobre Azure Maps Serviços aqui

Código fonte | Documentação de | referência da API Documentação do produto

Exclusão de Responsabilidade

O apoio aos pacotes Azure SDK Python para python 2.7 terminou em 01 de janeiro de 2022. Para mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

Se utilizar o Azure CLI, substitua <resource-group-name> e <account-name> escolha, e selecione um nível de preços adequado baseado nas suas necessidades através do <sku-name> parâmetro. Consulte esta página para mais detalhes.

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

Instale o pacote

Instale o SDK de pesquisa de serviço de Azure Maps.

pip install azure-maps-search

Criar e Autenticar o MapsSearchClient

Para criar um objeto de cliente para aceder à API de pesquisa de Azure Maps, necessitará de um objeto credencial. Azure Maps Cliente de Pesquisa também suporta duas formas de autenticar.

1. Autenticar com uma credencial de chave de assinatura

Pode autenticar com a sua Azure Maps Chave de Subscrição. Uma vez criada a Chave de Subscrição Azure Maps, desaprova o valor da chave como variável ambiental: AZURE_SUBSCRIPTION_KEY. Em seguida, passe um AZURE_SUBSCRIPTION_KEY como credential parâmetro para um exemplo 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. Autenticar com uma credencial Azure Ative Directory

Pode autenticar com credencial de token Azure Ative (AAD) utilizando a biblioteca Azure Identity. A autenticação utilizando o AAD requer alguma configuração inicial:

Após a configuração, pode escolher de que tipo de credencialazure.identity se deve a utilizar. Como exemplo, o DefaultAzureCredential pode ser usado para autenticar o cliente:

Em seguida, definir os valores do ID do cliente, iD do inquilino e segredo de cliente da aplicação AAD como variáveis ambientais: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Também terá de especificar o Azure Maps recurso que pretende utilizar especificando as clientId opções do cliente. O id do Azure Maps do cliente de recursos pode ser encontrado nas secções de Autenticação no recurso Azure Maps. Por favor, consulte a documentação sobre como encontrá-la.

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

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

Conceitos-chave

A biblioteca de clientes Azure Maps Search para Python permite interagir com cada um dos componentes através da utilização de um objeto cliente dedicado.

Clientes sincronizados

MapsSearchClienté o principal cliente para desenvolvedores que usam a biblioteca de clientes de pesquisa de Azure Maps para Python. Uma vez inicializada uma MapsSearchClient aula, pode explorar os métodos neste objeto do cliente para entender as diferentes características do Azure Maps Serviço de pesquisa a que pode aceder.

Clientes Async

Esta biblioteca inclui uma API completa assínc suportada em Python 3.5+. Para usá-lo, primeiro deve instalar um transporte de async, como aiohttp. Consulte a documentação do núcleo azul para obter mais informações.

Clientes e credenciais async devem ser fechados quando já não são necessários. Estes objetos são gestores de contexto async e definem métodos async close .

Exemplos

As seguintes secções fornecem vários fragmentos de código que cobrem algumas das tarefas de pesquisa de Azure Maps mais comuns, incluindo:

Solicitar coordenadas de latitude e longitude para um endereço

Pode utilizar um cliente autenticado para converter um endereço em coordenadas de latitude e longitude. Este processo também é chamado de geocoding. Além da devolução das coordenadas, a resposta irá também devolver propriedades detalhadas de endereços como a informação de rua, código postal, município e informação de país/região.

from azure.maps.search import MapsSearchClient

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

Procurar um endereço ou Ponto de Interesse

Pode utilizar a Fuzzy Search para pesquisar um endereço ou um ponto de interesse (POI). Os exemplos que se seguem desesperam como procurar pizza no âmbito de um país específico (Franceneste exemplo).

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

Faça uma Pesquisa de Endereço Inverso para traduzir a localização de coordenadas para endereço de rua

Pode traduzir coordenadas em endereços de rua legívels para humanos. Este processo também é chamado de geocoding inverso. Isto é frequentemente usado para aplicações que consomem feeds GPS e querem descobrir endereços em pontos 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

Traduza a localização da coordenada numa rua transversal compreensível humana

Traduza a localização da coordenada numa rua transversal compreensível humana utilizando a API de Reverse Cross Street. Na maioria das vezes, isto é necessário no rastreio de aplicações que recebem um feed GPS de um dispositivo ou ativo, e deseja saber onde a coordenada está localizada.

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

Obtenha lote de pesquisa async fuzzy com param e batchid

Esta amostra demonstra como realizar pesquisas fuzzy por localização e lat/lon com método de lote de async. Esta função é aceitar ambos search_queries e batch_id devolver um AsyncLRO objeto. O batch_id aqui pode ser usado para recuperar o objeto LRO mais tarde, que dura 14 dias.

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

O método begin_fuzzy_search_batch() também aceita batch_id como parâmetro. O batch_id aqui pode ser usado para recuperar o objeto LRO mais tarde, que dura 14 dias.

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

Não conseguir sincronização de lote de pesquisa difusa

Esta amostra demonstra como verificar se existem falhas em busca 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.")

Pesquisa dentro da Geometria

Esta amostra demonstra como realizar a pesquisa dentro da geometria através de um alvo dado como pizza e múltiplas geometrias diferentes como a entrada com o 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)

Esta amostra demonstra como trabalhar com outros pacotes existentes, tais como shapely realizar pesquisas dentro da geometria por um determinado alvo, tais 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)

Resolução de problemas

Geral

Os clientes de pesquisa de mapas levantam exceções definidas no Azure Core.

Esta lista pode ser utilizada para referência a exceções lançadas às capturas. Para obter o código de erro específico da exceção, utilize o error_code atributo, ou seja, exception.error_code.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registar registos. Informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível info.

A registo detalhado do nível DEBUG, incluindo os órgãos de pedido/resposta e os cabeçalhos não redigidos, pode ser ativado num cliente com o 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)

Da mesma forma, logging_enable pode permitir a registo detalhado para uma única operação, mesmo quando não está habilitado para o cliente:

service_client.get_service_stats(logging_enable=True)

Adicionais

Ainda a ter problemas? Se encontrar algum bug ou tiver sugestões, por favor preencha um problema na secção Questões do projeto.

Passos seguintes

Mais código de amostra

Começa com as nossas amostras de Pesquisa de Mapas (amostras de Versão Async).

Várias amostras de Azure Maps Search Python SDK estão disponíveis para si no repositório GitHub da SDK. Estas amostras fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com a Pesquisa 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 a bandeira pode ser adicionada opcionalmente, é incluir versões de pré-lançamento e desenvolvimento para pip install. Por padrão, pip só encontra versões estáveis.

Mais detalhes por favor consulte a introdução de amostras

Documentação adicional

Para obter documentação mais extensa sobre Azure Maps Search, consulte a documentação de pesquisa de Azure Maps sobre docs.microsoft.com.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para mais informações consulte o Código de Conduta FAQ ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.