Azure 地圖服務適用于 Python 的地理位置套件用戶端程式庫 - 1.0.0b1 版

發行項
04/05/2023

此套件包含適用于地理位置Azure 地圖服務服務的 Python SDK。在這裡深入瞭解Azure 地圖服務服務

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691

開始使用

Prerequisites

需要 Python 3.7 或更新版本才能使用此套件。
Azure 訂用帳戶和Azure 地圖服務帳戶。
已部署的地圖服務資源。您可以透過 Azure 入口網站或 Azure CLI建立資源。

如果您使用 Azure CLI，請取代 <resource-group-name> 和 <account-name> 選擇，並根據您的需求透過 <sku-name> 參數選取適當的定價層。如需詳細資訊，請參閱此頁面。

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

安裝套件

安裝 Azure 地圖服務服務地理位置 SDK。

pip install azure-maps-geolocation

建立及驗證 MapsGeolocationClient

若要建立用戶端物件來存取Azure 地圖服務地理位置 API，您需要認證物件。 Azure 地圖服務地理位置用戶端也支援兩種方式進行驗證。

1.使用訂用帳戶金鑰認證進行驗證

您可以使用Azure 地圖服務訂用帳戶金鑰進行驗證。建立Azure 地圖服務訂用帳戶金鑰之後，請將金鑰的值設定為環境變數： AZURE_SUBSCRIPTION_KEY 。然後將作為 credential 參數傳遞 AZURE_SUBSCRIPTION_KEY 至AzureKeyCredential的實例。

from azure.core.credentials import AzureKeyCredential
from azure.maps.geolocation import MapsGeolocationClient

credential = AzureKeyCredential(os.environ.get("AZURE_SUBSCRIPTION_KEY"))

geolocation_client = MapsGeolocationClient(
    credential=credential,
)

2.使用 Azure Active Directory 認證進行驗證

您可以使用 Azure 身分識別連結庫向 Azure Active Directory (AAD) 權杖認證進行驗證。使用 AAD 進行驗證需要一些初始設定：

安裝 azure-identity
註冊新的 AAD 應用程式
將適當的角色指派給服務主體，以授與對Azure 地圖服務的存取權。請參閱管理驗證頁面。

安裝之後，您可以選擇要使用的認證azure.identity 類型。例如， DefaultAzureCredential 可用來驗證用戶端：

接下來，將 AAD 應用程式的用戶端識別碼、租使用者識別碼和用戶端密碼的值設定為環境變數： AZURE_CLIENT_ID 、、、 AZURE_TENANT_IDAZURE_CLIENT_SECRET

您也必須在用戶端選項中指定 clientId ，以指定您想要使用的Azure 地圖服務資源。 Azure 地圖服務資源用戶端識別碼可在Azure 地圖服務資源的 [驗證] 區段中找到。請參閱有關如何尋找的檔。

from azure.maps.geolocation import MapsGeolocationClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
geolocation_client = MapsGeolocationClient(
    client_id="<Azure Maps Client ID>",
    credential=credential
)

重要概念

適用于 Python 的Azure 地圖服務地理位置用戶端程式庫可讓您透過使用專用用戶端物件，與每個元件互動。

同步處理用戶端

MapsGeolocationClient是開發人員的主要用戶端，使用適用于 Python 的Azure 地圖服務地理位置用戶端程式庫。初始化 MapsGeolocationClient 類別之後，您可以探索此用戶端物件上的方法，以瞭解您可以存取之Azure 地圖服務地理位置服務的不同功能。

非同步用戶端

此程式庫包含 Python 3.5+ 上支援的完整非同步 API。若要使用它，您必須先安裝非同步傳輸，例如 aioHTTP。如需詳細資訊，請參閱 azure 核心檔。

不再需要非同步用戶端和認證時，應該關閉它們。這些物件是非同步內容管理員，並定義非同步 close 方法。

範例

下列各節提供數個程式碼片段，涵蓋一些最常見的Azure 地圖服務地理位置工作，包括：

取得地理位置

取得地理位置

此服務會傳回所提供 IP 位址的 ISO 國家/地區代碼。開發人員可以使用這項資訊，根據從中檢視應用程式的地理位置來封鎖或改變特定內容。

from azure.maps.geolocation import MapsGeolocationClient

BLOCK_COUNTRY_LIST = ['US', 'TW', 'AF', 'AX', 'DL']
INCOME_IP_ADDRESS = "2001:4898:80e8:b::189"
geolocation_result = client.get_country_code(ip_address=INCOME_IP_ADDRESS)

result_country_code = geolocation_result.iso_code

if result_country_code in BLOCK_COUNTRY_LIST:
    raise Exception("These IP address is from forebiden country")

疑難排解

一般

地圖地理位置用戶端會引發 Azure Core中定義的例外狀況。

此清單可用於參考，以攔截擲回的例外狀況。若要取得例外狀況的特定錯誤碼，請使用 error_code 屬性，也就是 exception.error_code 。

記錄

此程式庫會使用標準記錄程式庫進行記錄。 HTTP 會話的基本資訊 (URL、標頭等。) 會記錄在 INFO 層級。

您可以在具有引數的用戶端 logging_enable 上啟用詳細的 DEBUG 層級記錄，包括要求/回應主體和未回應標頭：

import sys
import logging
from azure.maps.geolocation import MapsGeolocationClient

# Create a logger for the 'azure.maps.geolocation' SDK
logger = logging.getLogger('azure.maps.geolocation')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

其他

仍然遇到問題嗎？如果您遇到任何錯誤或有建議，請在專案的 [問題 ] 區段中提出問題。

下一步

其他文件

如需Azure 地圖服務地理位置的詳細資訊，請參閱docs.microsoft.com Azure 地圖服務地理位置檔。

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

共用方式為