Udostępnij za pośrednictwem

biblioteka klienta pakietu wyszukiwania Azure Maps dla języka Python — wersja 1.0.0b2

  • Artykuł

Ten pakiet zawiera zestaw SDK języka Python dla usług Azure Maps Dla wyszukiwania. Dowiedz się więcej o usługach Azure Maps tutaj

Kod | źródłowy Dokumentacja referencyjna interfejsu | API Dokumentacja produktu

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python dla zestawu Azure SDK dla języka Python 2.7 zakończyła się 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691

Wprowadzenie

Wymagania wstępne

Jeśli używasz interfejsu wiersza polecenia platformy Azure, zastąp <resource-group-name> elementy i <account-name> wybierz odpowiednią warstwę cenową w zależności od potrzeb za pośrednictwem parametru <sku-name> . Aby uzyskać więcej informacji, zapoznaj się z tą stroną .

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

Instalowanie pakietu

Zainstaluj zestaw SDK wyszukiwania usług Azure Maps.

pip install azure-maps-search

Tworzenie i uwierzytelnianie elementu MapsSearchClient

Aby utworzyć obiekt klienta w celu uzyskania dostępu do interfejsu API wyszukiwania Azure Maps, potrzebny jest obiekt poświadczeń. Azure Maps Klient wyszukiwania obsługuje również dwa sposoby uwierzytelniania.

1. Uwierzytelnianie przy użyciu poświadczeń klucza subskrypcji

Możesz uwierzytelnić się przy użyciu klucza subskrypcji Azure Maps. Po utworzeniu klucza subskrypcji Azure Maps ustaw wartość klucza jako zmienną środowiskową: AZURE_SUBSCRIPTION_KEY. Następnie przekaż element AZURE_SUBSCRIPTION_KEY jako credential parametr do wystąpienia obiektu 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. Uwierzytelnianie przy użyciu poświadczeń usługi Azure Active Directory

Możesz uwierzytelnić się przy użyciu poświadczeń tokenu usługi Azure Active Directory (AAD) przy użyciu biblioteki tożsamości platformy Azure. Uwierzytelnianie przy użyciu usługi AAD wymaga konfiguracji początkowej:

Po skonfigurowaniu można wybrać typ poświadczeńazure.identity do użycia. Na przykład wartość DefaultAzureCredential może służyć do uwierzytelniania klienta:

Następnie ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i klucza tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET

Należy również określić zasób Azure Maps, którego zamierzasz użyć, określając wartość clientId w opcjach klienta. Identyfikator klienta zasobu Azure Maps można znaleźć w sekcjach Uwierzytelnianie w zasobie Azure Maps. Zapoznaj się z dokumentacją dotyczącą tego, jak go znaleźć.

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

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

Kluczowe pojęcia

Biblioteka klienta usługi Azure Maps Search dla języka Python umożliwia interakcję z poszczególnymi składnikami za pomocą dedykowanego obiektu klienta.

Synchronizowanie klientów

MapsSearchClientjest podstawowym klientem dla deweloperów korzystających z biblioteki klienta usługi Azure Maps Search dla języka Python. Po zainicjowaniu MapsSearchClient klasy można zapoznać się z metodami na tym obiekcie klienta, aby zrozumieć różne funkcje Azure Maps usługa wyszukiwania, do których można uzyskać dostęp.

Klienci asynchroniczny

Ta biblioteka zawiera kompletny asynchroniczny interfejs API obsługiwany w języku Python 3.5 lub nowszym. Aby go używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację platformy azure-core .

Klienci asynchroniczne i poświadczenia powinny być zamykane, gdy nie są już potrzebne. Te obiekty są menedżerami kontekstu asynchronicznego i definiują metody asynchroniczne close .

Przykłady

W poniższych sekcjach przedstawiono kilka fragmentów kodu obejmujących niektóre z najczęstszych zadań Azure Maps wyszukiwania, w tym:

Żądaj współrzędnych szerokości i długości geograficznej dla adresu

Możesz użyć uwierzytelnionego klienta, aby przekonwertować adres na współrzędne szerokości i długości geograficznej. Ten proces jest również nazywany geokodowaniem. Oprócz zwracania współrzędnych odpowiedź zwróci również szczegółowe właściwości adresu, takie jak ulica, kod pocztowy, gmina i informacje o kraju/regionie.

from azure.maps.search import MapsSearchClient

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

Wyszukiwanie adresu lub punktu orientacyjnego

Wyszukiwanie rozmyte umożliwia wyszukiwanie adresu lub punktu orientacyjnego (POI). W poniższych przykładach przedstawiono sposób wyszukiwania pizza w zakresie określonego kraju (Francew tym przykładzie).

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

Utwórz wyszukiwanie odwrotne adresów, aby przetłumaczyć lokalizację współrzędnych na adres ulicy

Współrzędne można przetłumaczyć na czytelne dla człowieka adresy uliczne. Ten proces jest również nazywany odwrotnym geokodowaniem. Jest to często używane w przypadku aplikacji korzystających z kanałów GPS i chcą odnajdywać adresy w określonych punktach współrzędnych.

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

Tłumaczenie lokalizacji współrzędnych na zrozumiałą dla człowieka ulicę

Przetłumacz lokalizację współrzędnych na zrozumiałą dla człowieka ulicę, korzystając z interfejsu API odwrotnego cross street adresu wyszukiwania. Najczęściej jest to potrzebne w aplikacjach do śledzenia, które odbierają kanał GPS z urządzenia lub zasobu i chcą wiedzieć, gdzie znajduje się współrzędna.

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

Pobieranie asynchronicznych partii wyszukiwania rozmytego za pomocą parametrów i batchid

W tym przykładzie pokazano, jak przeprowadzić wyszukiwanie rozmyte według lokalizacji i lat/lon za pomocą metody asynchronicznej wsadowej. Ta funkcja akceptuje zarówno search_queries obiekt , jak i batch_id i zwraca obiekt AsyncLRO . W batch_id tym miejscu można pobrać obiekt LRO później, który trwa 14 dni.

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

Metoda begin_fuzzy_search_batch() przyjmuje batch_id również jako parametr . W batch_id tym miejscu można pobrać obiekt LRO później, który trwa 14 dni.

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

Nie można pobrać synchronizacji partii wyszukiwania rozmytego

W tym przykładzie pokazano, jak sprawdzić, czy w wyszukiwaniu fuzzy_search_batch występują błędy.

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

Wyszukiwanie wewnątrz geometrii

W tym przykładzie pokazano, jak przeprowadzić wyszukiwanie wewnątrz geometrii według danego obiektu docelowego, takiego jak pizza i wiele różnych geometrii jako dane wejściowe z obiektem 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)

W tym przykładzie pokazano, jak pracować z innymi istniejącymi pakietami, takimi jak shapely wyszukiwanie wewnątrz geometrii według danego obiektu docelowego, takiego jak 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)

Rozwiązywanie problemów

Ogólne

Klienci wyszukiwania w usłudze Maps zgłaszają wyjątki zdefiniowane w usłudze Azure Core.

Ta lista może służyć do przywoływania zgłaszanych wyjątków. Aby uzyskać określony kod błędu wyjątku, użyj atrybutu error_code , tj exception.error_code. .

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem 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)

logging_enable Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

service_client.get_service_stats(logging_enable=True)

Dodatkowe

Nadal występują problemy? Jeśli napotkasz jakiekolwiek usterki lub masz sugestie, zgłoś problem w sekcji Problemy w projekcie.

Następne kroki

Więcej przykładów kodu

Rozpocznij pracę z naszymi przykładami wyszukiwania w usłudze Maps (przykłady wersji asynchronicznych).

Kilka przykładów zestawu SDK wyszukiwania języka Python Azure Maps jest dostępnych w repozytorium GitHub zestawu SDK. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy często napotykanych podczas pracy z usługą Maps Search

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

Uwagi: --pre flaga może być opcjonalnie dodawana, ma ona zawierać wersje wstępne i programistyczne dla pip installprogramu . Domyślnie pip znajduje tylko stabilne wersje.

Więcej szczegółów można znaleźć w temacie Wprowadzenie do przykładów

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą wyszukiwania Azure Maps, zobacz dokumentację usługi Azure Maps Search dotyczącą docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.