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.6 或更新版本才能使用此套件。
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 地圖服務 Service Route SDK。

pip install azure-maps-route

建立及驗證 MapsRouteClient

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

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

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

from azure.core.credentials import AzureKeyCredential
from azure.maps.route import MapsRouteClient

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

route_client = MapsRouteClient(
    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.route import MapsRouteClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
route_client = MapsRouteClient(
    client_id="<Azure Maps Client ID>",
    credential=credential
)

重要概念

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

同步處理用戶端

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

非同步用戶端

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

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

範例

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

要求和取得路線指示
要求和取得路由範圍
取得路由矩陣
取得路線指示批次

要求和取得路線指示

此服務要求會傳回來源與目的地之間的路由，並在指定時通過路線點。路線將考慮目前交通和一般道路速度等因素，如一周中要求的一天和一天的時間。

from azure.maps.route import MapsRouteClient

route_directions_result = client.get_route_directions(route_points=[LatLon(47.60323, -122.33028), LatLon(53.2, -106)]);

要求和取得路由範圍

此服務會計算一組位置，這些位置可從指定座標從原點到達，並根據指定的燃料、能源、時間或距離預算。

from azure.maps.route import MapsRouteClient

route_range_result = client.get_route_range(coordinates=LatLon(47.60323, -122.33028), time_budget_in_sec=6000);

取得路由矩陣

如果成功接受矩陣路由要求，回應中的 Location 標頭會包含要下載要求結果的 URL。

擷取先前路由矩陣要求的結果。方法會傳回輪詢器來擷取結果。

from azure.maps.route import MapsRouteClient

route_matrix_result = client.begin_get_route_matrix_result(matrix_id="11111111-2222-3333-4444-555555555555");

取得路線指示批次

擷取先前路由方向批次要求的結果。方法會傳回輪詢器來擷取結果。

from azure.maps.route import MapsRouteClient

route_directions_batch_poller_result = client.begin_get_route_directions_batch_result(batch_id="11111111-2222-3333-4444-555555555555");

疑難排解

一般

地圖路由用戶端會引發 Azure Core中定義的例外狀況。

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

記錄

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

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

import sys
import logging
from azure.maps.route import MapsRouteClient

# Create a logger for the 'azure.maps.route' SDK
logger = logging.getLogger('azure.maps.route')
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。

共用方式為