Bagikan melalui

Azure Maps pustaka klien Paket Pencarian untuk Python - versi 1.0.0b2

  • Artikel

Paket ini berisi Python SDK untuk Azure Maps Services for Search. Baca selengkapnya tentang Layanan Azure Maps di sini

Kode sumber | Dokumentasi | referensi API Dokumentasi produk

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi lebih lanjut dan pertanyaan, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Memulai

Prasyarat

Jika Anda menggunakan Azure CLI, ganti <resource-group-name> dan <account-name> pilihan Anda, dan pilih tingkat harga yang tepat berdasarkan kebutuhan Anda melalui <sku-name> parameter . Harap tinjau halaman ini untuk detail selengkapnya.

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

Instal paketnya

Instal SDK Azure Maps Service Search.

pip install azure-maps-search

Membuat dan Mengautentikasi MapsSearchClient

Untuk membuat objek klien untuk mengakses Azure Maps Search API, Anda memerlukan objek kredensial. klien Azure Maps Search juga mendukung dua cara untuk mengautentikasi.

1. Autentikasi dengan Kredensial Kunci Langganan

Anda dapat mengautentikasi dengan Kunci Langganan Azure Maps Anda. Setelah Kunci Langganan Azure Maps dibuat, atur nilai kunci sebagai variabel lingkungan: AZURE_SUBSCRIPTION_KEY. Kemudian teruskan AZURE_SUBSCRIPTION_KEY sebagai credential parameter ke dalam instans 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. Mengautentikasi dengan kredensial Azure Active Directory

Anda dapat mengautentikasi dengan kredensial token Azure Active Directory (AAD) menggunakan pustaka Azure Identity. Autentikasi dengan menggunakan AAD memerlukan beberapa penyiapan awal:

Setelah penyiapan, Anda dapat memilih jenis kredensialazure.identity mana yang akan digunakan. Sebagai contoh, DefaultAzureCredential dapat digunakan untuk mengautentikasi klien:

Selanjutnya, atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET

Anda juga perlu menentukan sumber daya Azure Maps yang ingin Anda gunakan dengan menentukan clientId di opsi klien. Id klien sumber daya Azure Maps dapat ditemukan di bagian Autentikasi di sumber daya Azure Maps. Silakan lihat dokumentasi tentang cara menemukannya.

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

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

Konsep utama

Pustaka klien Azure Maps Search untuk Python memungkinkan Anda berinteraksi dengan setiap komponen melalui penggunaan objek klien khusus.

Sinkronkan Klien

MapsSearchClientadalah klien utama untuk pengembang yang menggunakan pustaka klien Azure Maps Search untuk Python. Setelah menginisialisasi MapsSearchClient kelas, Anda dapat menjelajahi metode pada objek klien ini untuk memahami berbagai fitur Azure Maps layanan Pencarian yang dapat Anda akses.

Klien Asinkron

Pustaka ini mencakup API asinkron lengkap yang didukung pada Python 3.5+. Untuk menggunakannya, Anda harus menginstal transportasi asinkron terlebih dahulu, seperti aiohttp. Lihat dokumentasi azure-core untuk informasi selengkapnya.

Klien dan kredensial asinkron harus ditutup ketika tidak lagi diperlukan. Objek-objek ini adalah manajer konteks asinkron dan mendefinisikan metode asinkron close .

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas pencarian Azure Maps yang paling umum, termasuk:

Meminta koordinat lintang dan bujur untuk alamat

Anda dapat menggunakan klien terautentikasi untuk mengonversi alamat menjadi koordinat lintang dan bujur. Proses ini juga disebut geocoding. Selain menampilkan koordinat, respons juga akan menampilkan properti detail alamat seperti jalan, kode pos, kotamadya, dan informasi negara/wilayah.

from azure.maps.search import MapsSearchClient

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

Mencari alamat atau Tempat Menarik

Anda dapat menggunakan Pencarian Fuzzy untuk mencari alamat atau tempat menarik (POI). Contoh berikut menunjukkan cara mencari pizza di atas cakupan negara tertentu (France, dalam contoh ini).

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

Membuat Pencarian Alamat Terbalik untuk menerjemahkan lokasi koordinat ke alamat jalan

Anda dapat menerjemahkan koordinat ke alamat jalan yang dapat dibaca manusia. Proses ini juga disebut geocoding terbalik. Ini sering digunakan untuk aplikasi yang menggunakan umpan GPS dan ingin menemukan alamat pada titik koordinat tertentu.

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

Menerjemahkan lokasi koordinat ke dalam lintas jalan yang dapat dimengerti manusia

Terjemahkan lokasi koordinat menjadi lintas jalan yang dapat dipahami manusia dengan menggunakan Search Address Reverse Cross Street API. Paling sering, hal ini diperlukan dalam aplikasi pelacakan yang menerima umpan GPS dari perangkat atau aset, dan ingin tahu di mana koordinatnya berada.

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

Dapatkan batch pencarian fuzzy asinkron dengan param dan batchid

Sampel ini menunjukkan cara melakukan pencarian fuzzy berdasarkan lokasi dan lat/lon dengan metode batch asinkron. Fungsi ini menerima dan search_queriesbatch_id dan mengembalikan AsyncLRO objek. di batch_id sini dapat digunakan untuk mengambil objek LRO nanti yang 14 hari terakhir.

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

Metode begin_fuzzy_search_batch() ini juga menerima batch_id sebagai parameter . di batch_id sini dapat digunakan untuk mengambil objek LRO nanti yang 14 hari terakhir.

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

Gagal mendapatkan sinkronisasi batch pencarian fuzzy

Sampel ini menunjukkan cara memeriksa apakah ada kegagalan dalam mencari 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.")

Cari di dalam Geometri

Sampel ini menunjukkan cara melakukan pencarian di dalam geometri dengan target tertentu seperti pizza dan beberapa geometri yang berbeda sebagai input dengan objek 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)

Sampel ini menunjukkan cara bekerja dengan paket lain yang ada seperti shapely untuk melakukan pencarian di dalam geometri oleh target tertentu seperti 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)

Pemecahan Masalah

Umum

Klien Pencarian Maps memunculkan pengecualian yang ditentukan di Azure Core.

Daftar ini dapat digunakan untuk referensi guna menangkap pengecualian yang dilemparkan. Untuk mendapatkan kode kesalahan tertentu dari pengecualian, gunakan error_code atribut , yaitu , exception.error_code.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan logging_enable argumen :

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)

Demikian pula, logging_enable dapat mengaktifkan pengelogan terperinci untuk satu operasi, bahkan ketika tidak diaktifkan untuk klien:

service_client.get_service_stats(logging_enable=True)

Tambahan

Masih mengalami masalah? Jika Anda menemukan bug atau memiliki saran, silakan ajukan masalah di bagian Masalah proyek.

Langkah berikutnya

Lebih banyak kode sampel

Mulai menggunakan sampel Pencarian Maps (sampel Versi Asinkron).

Beberapa sampel SDK Python Pencarian Azure Maps tersedia untuk Anda di repositori GitHub SDK. Sampel ini menyediakan kode contoh untuk skenario tambahan yang biasa ditemui saat bekerja dengan Pencarian Maps

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

Catatan: --pre bendera dapat ditambahkan secara opsional, yaitu menyertakan versi pra-rilis dan pengembangan untuk pip install. Secara default, pip hanya menemukan versi yang stabil.

Detail lebih lanjut silakan merujuk ke Pengenalan Sampel

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang pencarian Azure Maps, lihat dokumentasi pencarian Azure Maps di docs.microsoft.com.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.