Sdílet prostřednictvím

Klientská knihovna balíčku vyhledávání Azure Maps pro Python – verze 1.0.0b2

  • Článek

Tento balíček obsahuje sadu Python SDK pro službu Azure Maps Services for Search. Další informace o Azure Maps Services najdete tady.

Zdrojový kód | Referenční dokumentace k | rozhraní API Dokumentace k produktu

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Začínáme

Požadavky

Pokud používáte Azure CLI, nahraďte <resource-group-name> a <account-name> podle vlastního výběru a pomocí parametru <sku-name> vyberte správnou cenovou úroveň na základě vašich potřeb. Další podrobnosti najdete na této stránce .

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

Instalace balíčku

Nainstalujte sadu SDK služby Azure Maps Service Search.

pip install azure-maps-search

Vytvoření a ověření klienta MapsSearchClient

Pokud chcete vytvořit objekt klienta pro přístup k rozhraní AZURE MAPS Search API, budete potřebovat objekt přihlašovacích údajů. Klient služby Azure Maps Search také podporuje dva způsoby ověřování.

1. Ověření pomocí přihlašovacích údajů klíče předplatného

K ověření můžete použít klíč předplatného Azure Maps. Po vytvoření klíče předplatného Azure Maps nastavte hodnotu klíče jako proměnnou prostředí: AZURE_SUBSCRIPTION_KEY. Pak jako parametr předejte AZURE_SUBSCRIPTION_KEYcredential instanci 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. Ověřování pomocí přihlašovacích údajů Azure Active Directory

K ověření můžete použít přihlašovací údaje tokenu Azure Active Directory (AAD) pomocí knihovny Identit Azure. Ověřování pomocí AAD vyžaduje určité počáteční nastavení:

Po nastavení můžete zvolit, jaký typ přihlašovacích údajůazure.identity se má použít. Například DefaultAzureCredential se dá použít k ověření klienta:

Dále nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnné prostředí: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Budete také muset určit Azure Maps prostředek, který chcete použít, zadáním parametru clientId v možnostech klienta. ID klienta prostředku Azure Maps najdete v částech Ověřování prostředku Azure Maps. Informace o tom, jak ji najít, najdete v dokumentaci .

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

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

Klíčové koncepty

Klientská knihovna Azure Maps Search pro Python umožňuje interakci s každou komponentou pomocí vyhrazeného objektu klienta.

Synchronizace klientů

MapsSearchClientje primární klient pro vývojáře, kteří používají klientskou knihovnu Azure Maps Search pro Python. Jakmile jste inicializovali MapsSearchClient třídu, můžete prozkoumat metody tohoto klientského objektu, abyste porozuměli různým funkcím Azure Maps Search, ke kterým máte přístup.

Asynchronní klienti

Tato knihovna obsahuje kompletní asynchronní rozhraní API podporované v Pythonu 3.5 nebo novějším. Abyste ho mohli používat, musíte nejdřív nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k azure-core .

Asynchronní klienti a přihlašovací údaje by se měly zavřít, když už je nepotřebujete. Tyto objekty jsou správci asynchronního kontextu a definují asynchronní close metody.

Příklady

Následující části obsahují několik fragmentů kódu, které pokrývají některé z nejběžnějších úloh Azure Maps vyhledávání, mezi které patří:

Vyžádání souřadnic zeměpisné šířky a délky pro adresu

Ověřeného klienta můžete použít k převodu adresy na souřadnice zeměpisné šířky a délky. Tento proces se také označuje jako geokódování. Kromě vrácení souřadnic vrátí odpověď také podrobné vlastnosti adresy, jako jsou například ulice, PSČ, obec a informace o zemi/oblasti.

from azure.maps.search import MapsSearchClient

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

Vyhledání adresy nebo bodu zájmu

K vyhledání adresy nebo bodu zájmu (POI) můžete použít funkci Přibližné vyhledávání. Následující příklady demostrují, jak hledat pizza v rozsahu konkrétní země (Francev tomto příkladu).

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

Provedení zpětného vyhledávání adresy pro překlad souřadnicového umístění na adresu ulice

Souřadnice můžete přeložit na adresy ulic, které jsou čitelné pro člověka. Tento proces se také označuje jako reverzní geokódování. To se často používá pro aplikace, které využívají informační kanály GPS a chtějí zjistit adresy v konkrétních souřadnicích.

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

Překlad umístění souřadnic na srozumitelnou křížovou ulici

Umístění souřadnic můžete přeložit na srozumitelnou křížovou ulici pomocí rozhraní API Prohledat adresu Reverse Cross Street. Nejčastěji je to potřeba při sledování aplikací, které přijímají informační kanál GPS ze zařízení nebo prostředku a chtějí vědět, kde se souřadnice nachází.

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

Získání dávky asynchronního vyhledávání přibližných shod s parametry param a batchid

Tato ukázka ukazuje, jak provést přibližné vyhledávání podle umístění a lat/lon pomocí asynchronní dávkové metody. Tato funkce přijímá objekt search_queries a batch_id a vrací ho AsyncLRO . Pomocí batch_id následujícího příkazu můžete později načíst objekt LRO, který trvá 14 dní.

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() také přijímá batch_id jako parametr . Pomocí batch_id následujícího příkazu můžete později načíst objekt LRO, který trvá 14 dní.

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

Nepodařilo se získat přibližnou synchronizaci dávkového vyhledávání

Tato ukázka ukazuje, jak zkontrolovat, jestli při hledání fuzzy_search_batch nedošlo k chybám.

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

Hledání uvnitř geometrie

Tato ukázka ukazuje, jak provést vyhledávání uvnitř geometrie podle daného cíle, jako pizza je a více různých geometrií jako vstup s objektem 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)

Tato ukázka ukazuje, jak pracovat s jinými existujícími balíčky, například shapely k provádění vyhledávání uvnitř geometrie podle daného cíle, například 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)

Poradce při potížích

Obecné

Klienti služby Maps Search vyvolávají výjimky definované v Azure Core.

Tento seznam lze použít jako referenci k zachycení vyvolaných výjimek. Pokud chcete získat konkrétní kód chyby výjimky, použijte error_code atribut , tj exception.error_code. .

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nezopravovaných hlaviček, je možné povolit na klientovi s 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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

service_client.get_service_stats(logging_enable=True)

Další

Stále dochází k problémům? Pokud narazíte na nějaké chyby nebo máte návrhy, nahlaste problém v části Problémy projektu.

Další kroky

Další vzorový kód

Začněte s našimi ukázkami vyhledávání v mapách (ukázky asynchronních verzí).

Několik ukázek sady Python SDK pro vyhledávání Azure Maps je k dispozici v úložišti sady SDK Na GitHubu. Tyto ukázky poskytují ukázkový kód pro další scénáře, se kterými se při práci s vyhledáváním v mapách běžně setkáte.

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

Poznámky: --pre Příznak lze přidat volitelně, má obsahovat předběžné a vývojové verze pro pip install. Ve výchozím nastavení pip najde pouze stabilní verze.

Další podrobnosti najdete v úvodu k ukázkům.

Další dokumentace

Podrobnější dokumentaci k Azure Maps Search najdete v dokumentaci Azure Maps Search na docs.microsoft.com.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.