Panduan Pengembang Python REST SDK (pratinjau)

2024-08-16

Azure Maps Python SDK dapat diintegrasikan dengan aplikasi dan pustaka Python untuk membangun aplikasi terkait peta dan sadar lokasi. Azure Maps Python SDK berisi API untuk Pencarian, Rute, Render, dan Geolokasi. API ini mendukung operasi seperti mencari alamat, perutean antara koordinat yang berbeda, mendapatkan lokasi geografis alamat IP tertentu.

Prasyarat

Akun Azure Maps.
Kunci langganan atau bentuk Autentikasi lainnya dengan Azure Maps.
Python pada 3.8 atau yang lebih baru. Disarankan untuk menggunakan rilis terbaru. Untuk informasi selengkapnya, lihat Kebijakan dukungan versi Azure SDK for Python.

Tip

Anda dapat membuat akun Azure Maps secara terprogram, Berikut adalah contoh menggunakan Azure CLI:

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

Membuat proyek python

Contoh berikut menunjukkan cara membuat program konsol bernama demo dengan Python:

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py

Menginstal paket python yang diperlukan

Setiap layanan di Azure Maps terkandung dalam paketnya sendiri. Saat menggunakan Azure Maps Python SDK, Anda hanya dapat menginstal paket layanan yang Anda butuhkan.

Di sini kita menginstal paket Pencarian Azure Maps. Karena masih dalam pratinjau publik, Anda perlu menambahkan --pre bendera:

pip install azure-maps-search --pre

Layanan Azure Maps

Azure Maps Python SDK mendukung Python versi 3.8 atau yang lebih baru. Untuk informasi selengkapnya tentang versi Python di masa mendatang, lihat Kebijakan dukungan versi Azure SDK for Python.

Nama layanan	Paket PyPi	Sampel
Mencari	azure-maps-search	sampel pencarian
Rute	azure-maps-route	sampel rute
Render	azure-maps-render	sampel render
Geolokasi	azure-maps-geolocation	sampel geolokasi

Membuat dan mengautentikasi MapsSearchClient

Anda memerlukan objek untuk autentikasi credential saat membuat objek yang MapsSearchClient digunakan untuk mengakses API pencarian Azure Maps. Anda dapat menggunakan kredensial Microsoft Entra atau kunci langganan Azure untuk mengautentikasi. Untuk informasi selengkapnya tentang autentikasi, lihat Autentikasi dengan Azure Maps.

Tip

MapsSearchClient adalah antarmuka utama untuk pengembang yang menggunakan pustaka pencarian Azure Maps. Lihat Pustaka klien paket Pencarian Azure Maps untuk mempelajari selengkapnya tentang metode pencarian yang tersedia.

Menggunakan kredensial Microsoft Entra

Anda dapat mengautentikasi dengan ID Microsoft Entra menggunakan paket Identitas Azure. Untuk menggunakan penyedia DefaultAzureCredential , Anda perlu menginstal paket klien Azure Identity:

pip install azure-identity

Anda perlu mendaftarkan aplikasi Microsoft Entra baru dan memberikan akses ke Azure Maps dengan menetapkan peran yang diperlukan ke perwakilan layanan Anda. Untuk informasi selengkapnya, lihat Menghosting daemon pada sumber daya non-Azure. ID Aplikasi (klien), ID Direktori (penyewa), dan rahasia klien dikembalikan. Salin nilai-nilai ini dan simpan di tempat yang aman. Anda membutuhkannya dalam langkah-langkah berikut.

Selanjutnya Anda perlu menentukan akun Azure Maps yang ingin Anda gunakan dengan menentukan ID klien peta. ID klien akun Azure Maps dapat ditemukan di bagian Autentikasi akun Azure Maps. Untuk informasi selengkapnya, lihat Menampilkan detail autentikasi.

Atur nilai ID Aplikasi (klien), ID Direktori (penyewa), dan rahasia klien aplikasi Microsoft Entra Anda, dan ID klien sumber daya peta sebagai variabel lingkungan:

Variabel lingkungan	Deskripsi
AZURE_CLIENT_ID	ID aplikasi (klien) di aplikasi terdaftar Anda
AZURE_CLIENT_SECRET	Nilai rahasia klien dalam aplikasi terdaftar Anda
AZURE_TENANT_ID	ID direktori (penyewa) di aplikasi terdaftar Anda
MAPS_CLIENT_ID	ID klien di akun Azure Map Anda

Sekarang Anda dapat membuat variabel lingkungan di PowerShell untuk menyimpan nilai-nilai ini:

$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"

Setelah menyiapkan variabel lingkungan, Anda dapat menggunakannya dalam program Anda untuk membuat AzureMapsSearch instans klien. Buat file bernama demo.py dan tambahkan kode berikut:

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
)

Penting

Variabel lingkungan lain yang dibuat dalam cuplikan kode sebelumnya, sementara tidak digunakan dalam sampel kode, diperlukan oleh DefaultAzureCredential(). Jika Anda tidak mengatur variabel lingkungan ini dengan benar, menggunakan konvensi penamaan yang sama, Anda akan mendapatkan kesalahan run-time. Misalnya, jika Anda AZURE_CLIENT_ID hilang atau tidak valid, Anda akan mendapatkan kesalahan InvalidAuthenticationTokenTenant .

Menggunakan kredensial kunci langganan

Anda dapat mengautentikasi dengan kunci langganan Azure Maps Anda. Kunci langganan Anda dapat ditemukan di bagian Autentikasi di akun Azure Maps seperti yang ditunjukkan pada cuplikan layar berikut:

Sekarang Anda dapat membuat variabel lingkungan di PowerShell untuk menyimpan kunci langganan:

$Env:SUBSCRIPTION_KEY="your subscription key"

Setelah variabel lingkungan dibuat, Anda dapat mengaksesnya dalam kode Anda. Buat file bernama demo.py dan tambahkan kode berikut:

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

Geocode alamat

Cuplikan kode berikut menunjukkan bagaimana, dalam aplikasi konsol sederhana, untuk mendapatkan koordinat garis bujur dan lintang untuk alamat tertentu. Contoh ini menggunakan kredensial kunci langganan untuk mengautentikasi MapsSearchClient. Di 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()

Kode sampel ini membuat instans AzureKeyCredential dengan kunci langganan Azure Maps, lalu menggunakannya untuk membuat MapsSearchClient instans objek. Metode yang disediakan dengan MapsSearchClient meneruskan permintaan ke titik akhir REST Azure Maps. Pada akhirnya, program melakukan iterasi melalui hasil dan mencetak koordinat untuk setiap hasil.

Alamat geocode batch

Sampel ini menunjukkan cara melakukan alamat pencarian batch:

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()

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.

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()

Permintaan batch untuk geocoding terbalik

Sampel ini menunjukkan cara melakukan pencarian terbalik dengan koordinat yang diberikan dalam batch.

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()

Mendapatkan poligon untuk lokasi tertentu

Sampel ini menunjukkan cara mencari poligon.

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()

Menggunakan SDK V1 untuk Pencarian dan Render

Untuk menggunakan Search V1 dan Render V1 SDK, silakan lihat halaman paket Search V1 SDK dan paket Render V1 SDK untuk informasi lebih lanjut.

Informasi Tambahan

Pustaka klien paket Pencarian Azure Maps di dokumentasi Pratinjau Azure SDK for Python.

Bagikan melalui