Python REST SDK 開發人員指南 (預覽)

發行項
08/16/2024

Azure 地圖服務 Python SDK 可以整合 Python 應用程式和程式庫，以建置地圖相關和位置感知應用程式。 Azure 地圖服務 Python SDK 包含搜尋、路線、轉譯和地理位置的 API。這些 API 支援搜尋地址、不同座標之間的路線、取得特定 IP 位址的地理位置等作業。

必要條件

Azure 地圖服務帳戶。
訂用帳戶金鑰或其他形式的 Azure 地圖服務驗證。
3.8 或更新版本的 Python。建議使用最新的版本。如需詳細資訊，請參閱適用於 Python 的 Azure SDK 版本支援原則。

提示

您可以透過程式設計方式建立 Azure 地圖服務帳戶，以下是使用 Azure CLI 的範例：

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

建立 Python 專案

下列範例示範如何使用 Python 建立名為 demo 的主控台程式：

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py

安裝所需的 Python 套件

Azure 地圖服務中的每項服務都包含在各自的套件中。使用 Azure 地圖服務 Python SDK 時，您可以只安裝所需的服務套件。

我們會在此安裝 Azure 地圖服務搜尋套件。由於它仍處於公開預覽狀態，因此您必須新增 --pre 旗標：

pip install azure-maps-search --pre

Azure 地圖服務

Azure 地圖服務 Python SDK 支援 Python 3.8 版或更新版本。如需未來 Python 版本的詳細資訊，請參閱適用於 Python 的 Azure SDK 版本支援原則。

服務名稱	PyPi 套件	範例
Search	azure-maps-search (英文)	搜尋樣本 (英文)
路由	azure-maps-route (英文)	路由樣本 (英文)
轉譯	azure-maps-render (英文)	轉譯樣本 (英文)
地理位置	azure-maps-geolocation (英文)	地理位置樣本 (英文)

建立及驗證 MapsSearchClient

建立用以存取 Azure 地圖服務搜尋 API 的 MapsSearchClient 物件時，您需要 credential 物件以供驗證。您可以使用 Microsoft Entra 認證或 Azure 訂用帳戶金鑰進行驗證。如需關於驗證的詳細資訊，請參閱驗證 Azure 地圖服務。

提示

MapsSearchClient 是開發人員使用 Azure 地圖服務搜尋程式庫的主要介面。若要深入了解可用的搜尋方法，請參閱 Azure 地圖服務搜尋套件用戶端程式庫。

使用 Microsoft Entra 認證

您可以使用 Azure 身分識別套件向 Microsoft Entra ID 進行驗證。若要使用 DefaultAzureCredential 提供者，您必須安裝 Azure 身分識別用戶端套件：

pip install azure-identity

您必須註冊新的 Microsoft Entra 應用程式，並將所需的角色指派給服務主體，以授與對 Azure 地圖服務的存取權。如需詳細資訊，請參閱在非 Azure 資源上裝載精靈。系統會傳回應用程式 (用戶端) 識別碼、目錄 (租用戶) 識別碼，以及用戶端密碼。複製這些值，並將其儲存在安全的地方。在下列步驟中，您會需要用到這些資料。

接下來，您必須指定地圖的用戶端識別碼，以指定您想要使用的 Azure 地圖服務帳戶。您可以在 Azure 地圖服務帳戶的 [驗證] 區段中找到 Azure 地圖服務帳戶用戶端識別碼。如需詳細資訊，請參閱檢視驗證詳細資料。

將應用程式 (用戶端) 識別碼、目錄 (租用戶) 識別碼和 Microsoft Entra 應用程式用戶端密碼的值，以及地圖資源的用戶端識別碼的值設定為環境變數：

環境變數	描述
AZURE_CLIENT_ID	已註冊應用程式中的應用程式 (用戶端) 識別碼
AZURE_CLIENT_SECRET	已註冊應用程式中用戶端密碼的值
AZURE_TENANT_ID	已註冊應用程式中的目錄 (租用戶) 識別碼
MAPS_CLIENT_ID	Azure 地圖服務帳戶中的用戶端識別碼

現在您可以在 PowerShell 中建立環境變數來儲存這些值：

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

設定環境變數之後，您可以在程式中使用這些變數來具現化 AzureMapsSearch 用戶端。建立名為 demo.py 的檔案，並新增以下程式碼：

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
)

重要

DefaultAzureCredential() 需要使用在之前的程式碼片段中建立的其他環境變數，但在程式碼範例中未使用這些變數。如果您並未使用相同的命名慣例正確設定這些環境變數，您將會收到執行階段錯誤。例如，如果您的 AZURE_CLIENT_ID 遺失或無效，您將會收到 InvalidAuthenticationTokenTenant 錯誤。

使用訂用帳戶金鑰認證

您可以使用 Azure 地圖服務訂用帳戶金鑰進行驗證。您可以在 Azure 地圖服務帳戶的 [驗證] 區段中找到您的訂用帳戶金鑰，如下列螢幕擷取畫面所示：

現在您可以在 PowerShell 中建立環境變數來儲存這些訂用帳戶金鑰：

$Env:SUBSCRIPTION_KEY="your subscription key"

建立環境變數之後，您可以在程式碼中進行存取。建立名為 demo.py 的檔案，並新增以下程式碼：

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

地理編碼地址

下列代碼段示範如何在簡單的控制台應用程式中取得指定位址的經度和緯度座標。此範例會使用訂用帳戶密鑰認證來驗證 MapsSearchClient。在 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()

此範例程式碼會使用 Azure 地圖服務訂用帳戶金鑰具現化 AzureKeyCredential，然後使用它來具現化 MapsSearchClient 物件。 MapsSearchClient 提供的方法會將要求轉送至 Azure 地圖服務 REST 端點。最後，程式會逐一查看結果，並列印每個結果的座標。

批次地理編碼地址

此範例示範如何執行批次搜尋位址：

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

進行反向位址搜尋，將座標位置轉譯為街道位址

您可以將座標轉譯成人類可讀的街道地址。此程序也稱為反向地理編碼。這通常用於取用 GPS 摘要的應用程式，並想要在特定座標點探索位址。

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

反向地理編碼的批次要求

此範例示範如何在批次中依指定的座標執行反向搜尋。

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

取得指定位置的多邊形

此範例示範如何搜尋多邊形。

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

使用 V1 SDK 進行搜尋和轉譯

若要使用搜尋 V1 和轉譯 V1 SDK，請參閱搜尋 V1 SDK 套件頁面和轉譯 V1 SDK 套件以取得詳細資訊。

其他資訊

適用於 Python 的 Azure SDK 預覽版文件中的 Azure 地圖服務搜尋套件用戶端程式庫。

共用方式為