Przewodnik dla deweloperów zestawu SDK REST języka Python (wersja zapoznawcza)
Zestaw SDK języka Python usługi Azure Maps można zintegrować z aplikacjami i bibliotekami języka Python w celu tworzenia aplikacji powiązanych z mapą i obsługujących lokalizację. Zestaw SDK języka Python usługi Azure Maps zawiera interfejsy API wyszukiwania, tras, renderowania i geolokalizacji. Te interfejsy API obsługują operacje, takie jak wyszukiwanie adresu, routing między różnymi współrzędnymi, uzyskiwanie lokalizacji geograficznej określonego adresu IP.
Wymagania wstępne
- Konto usługi Azure Maps.
- Klucz subskrypcji lub inna forma uwierzytelniania za pomocą usługi Azure Maps.
- Środowisko Python w wersji 3.8 lub nowszej. Zaleca się korzystanie z najnowszej wersji. Aby uzyskać więcej informacji, zobacz Zasady obsługi wersji zestawu Azure SDK dla języka Python.
Napiwek
Konto usługi Azure Maps można utworzyć programowo. Oto przykład przy użyciu interfejsu wiersza polecenia platformy Azure:
az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"
Tworzenie projektu w języku Python
W poniższym przykładzie pokazano, jak utworzyć program konsoli o nazwie przy użyciu demo języka Python:
mkdir mapsDemo
cd mapsDemo
New-Item demo.py
Instalowanie wymaganych pakietów języka Python
Każda usługa w usłudze Azure Maps jest zawarta we własnym pakiecie. Korzystając z zestawu SDK języka Python usługi Azure Maps, możesz zainstalować tylko pakiety potrzebnych usług.
W tym miejscu instalujemy pakiet usługi Azure Maps Search. Ponieważ jest ona nadal dostępna w publicznej wersji zapoznawczej, musisz dodać flagę --pre :
pip install azure-maps-search --pre
Usługi Azure Maps
Zestaw SDK języka Python usługi Azure Maps obsługuje język Python w wersji 3.8 lub nowszej. Aby uzyskać więcej informacji na temat przyszłych wersji języka Python, zobacz Zasady obsługi wersji zestawu Azure SDK dla języka Python.
Tworzenie i uwierzytelnianie elementu MapsSearchClient
Potrzebujesz credential obiektu do uwierzytelniania podczas tworzenia obiektu używanego MapsSearchClient do uzyskiwania dostępu do interfejsów API wyszukiwania usługi Azure Maps. Do uwierzytelniania można użyć poświadczeń usługi Microsoft Entra lub klucza subskrypcji platformy Azure. Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Authentication with Azure Maps (Uwierzytelnianie za pomocą usługi Azure Maps).
Napiwek
JestMapsSearchClient to podstawowy interfejs dla deweloperów korzystających z biblioteki wyszukiwania usługi Azure Maps. Zobacz Bibliotekę klienta pakietu Usługi Azure Maps Search, aby dowiedzieć się więcej o dostępnych metodach wyszukiwania.
Używanie poświadczeń entra firmy Microsoft
Możesz uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft przy użyciu pakietu tożsamości platformy Azure. Aby użyć dostawcy DefaultAzureCredential , należy zainstalować pakiet klienta tożsamości platformy Azure:
pip install azure-identity
Musisz zarejestrować nową aplikację Firmy Microsoft Entra i udzielić dostępu do usługi Azure Maps, przypisując wymaganą rolę do jednostki usługi. Aby uzyskać więcej informacji, zobacz Hostowanie demona w zasobach spoza platformy Azure. Zwracany jest identyfikator aplikacji (klienta), identyfikator katalogu (dzierżawy) i klucz tajny klienta. Skopiuj te wartości i zapisz je w bezpiecznym miejscu. Są one potrzebne w poniższych krokach.
Następnie należy określić konto usługi Azure Maps, którego chcesz użyć, określając identyfikator klienta mapy. Identyfikator klienta konta usługi Azure Maps można znaleźć w sekcjach Uwierzytelnianie konta usługi Azure Maps. Aby uzyskać więcej informacji, zobacz Wyświetlanie szczegółów uwierzytelniania.
Ustaw wartości identyfikatora aplikacji (klienta), identyfikatora katalogu (dzierżawy) i wpisu tajnego klienta aplikacji Microsoft Entra oraz identyfikator klienta zasobu mapy jako zmienne środowiskowe:
| Zmienna środowiskowa | opis |
|---|---|
| AZURE_CLIENT_ID | Identyfikator aplikacji (klienta) w zarejestrowanej aplikacji |
| AZURE_CLIENT_SECRET | Wartość wpisu tajnego klienta w zarejestrowanej aplikacji |
| AZURE_TENANT_ID | Identyfikator katalogu (dzierżawy) w zarejestrowanej aplikacji |
| MAPS_CLIENT_ID | Identyfikator klienta na koncie usługi Azure Map |
Teraz możesz utworzyć zmienne środowiskowe w programie PowerShell, aby przechowywać następujące wartości:
$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"
Po skonfigurowaniu zmiennych środowiskowych możesz użyć ich w programie, aby utworzyć wystąpienie AzureMapsSearch klienta. Utwórz plik o nazwie demo.py i dodaj następujący kod:
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
)
Ważne
Inne zmienne środowiskowe utworzone w poprzednim fragmencie kodu, choć nie są używane w przykładzie kodu, są wymagane przez element DefaultAzureCredential(). Jeśli te zmienne środowiskowe nie zostaną poprawnie ustawione, użyjesz tych samych konwencji nazewnictwa, wystąpią błędy czasu wykonywania. Jeśli na przykład brakuje lub jest on nieprawidłowy, AZURE_CLIENT_ID zostanie wyświetlony InvalidAuthenticationTokenTenant błąd.
Używanie poświadczeń klucza subskrypcji
Możesz uwierzytelnić się przy użyciu klucza subskrypcji usługi Azure Maps. Klucz subskrypcji można znaleźć w sekcji Uwierzytelnianie na koncie usługi Azure Maps, jak pokazano na poniższym zrzucie ekranu:
Teraz możesz utworzyć zmienne środowiskowe w programie PowerShell, aby przechowywać klucz subskrypcji:
$Env:SUBSCRIPTION_KEY="your subscription key"
Po utworzeniu zmiennej środowiskowej możesz uzyskać do niej dostęp w kodzie. Utwórz plik o nazwie demo.py i dodaj następujący kod:
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)
)
Geokodowanie adresu
Poniższy fragment kodu pokazuje, jak w prostej aplikacji konsolowej uzyskać współrzędne długości i szerokości geograficznej dla danego adresu. W tym przykładzie użyto poświadczeń klucza subskrypcji do uwierzytelniania elementu MapsSearchClient. W pliku 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()
Ten przykładowy kod tworzy wystąpienie AzureKeyCredential za pomocą klucza subskrypcji usługi Azure Maps, a następnie używa go do utworzenia MapsSearchClient wystąpienia obiektu. Metody udostępniane przez MapsSearchClient przekazywanie żądania do punktów końcowych REST usługi Azure Maps. W końcu program iteruje wyniki i drukuje współrzędne dla każdego wyniku.
Adresy geokodów wsadowych
W tym przykładzie pokazano, jak wykonać wyszukiwanie wsadowe:
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()
Wykonaj 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 aplikacjach, które zużywają kanały GPS i chcą odnajdywać adresy w określonych punktach współrzędnych.
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()
Żądanie wsadowe dotyczące odwrotnego geokodowania
W tym przykładzie pokazano, jak wykonać wyszukiwanie odwrotne według podanych współrzędnych w partii.
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()
Pobieranie wielokątów dla danej lokalizacji
W tym przykładzie pokazano, jak wyszukiwać wielokąty.
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()
Używanie zestawów SDK w wersji 1 na potrzeby wyszukiwania i renderowania
Aby użyć zestawu SDK wyszukiwania w wersji 1 i renderowania w wersji 1, zobacz stronę pakietu SDK wyszukiwania w wersji 1 i pakiet zestawu SDK renderowania w wersji 1, aby uzyskać więcej informacji.
Dodatkowe informacje
Biblioteka klienta pakietu Azure Maps Search w dokumentacji zestawu Azure SDK dla języka Python w wersji zapoznawczej.