Azure Maps Route包的Python客户端库

此包包含用于Azure Maps服务的路线的Python SDK。有关Azure Maps服务的更多信息，请参阅此处

源代码 | API参考文档 | 产品文档

免责声明

Azure SDK Python包对Python 2.7的支持已于2022年1月1日结束。有关更多信息，请参阅https://github.com/Azure/azure-sdk-for-python/issues/20691

入门

先决条件

• 使用此包需要Python 3.6或更高版本。
• 一个Azure订阅和一个Azure Maps账户。
• 已部署的Maps服务资源。您可以通过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 Maps 服务路由 SDK。

pip install azure-maps-route

创建并验证 MapsRouteClient

要创建一个用于访问 Azure Maps 路线 API 的客户端对象，您需要一个 凭证 对象。Azure Maps 路线客户端还支持两种认证方式。

1. 使用订阅密钥凭证进行认证

您可以使用您的 Azure Maps 订阅密钥进行认证。一旦创建了 Azure Maps 订阅密钥，将其值设置为环境变量：AZURE_SUBSCRIPTION_KEY。然后，将 AZURE_SUBSCRIPTION_KEY 作为 credential 参数传递给 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 Active Directory (AAD) 令牌凭证 通过 Azure Identity 库 进行认证。使用 AAD 进行认证需要一些初始设置。

• 安装 azure-identity
• 注册一个新的 AAD 应用
• 通过分配适当的角色到您的服务主体来授予对 Azure Maps 的访问权限。请参阅管理认证页面。

设置完成后，您可以从 azure.identity 中选择使用哪种类型的 凭证。例如，可以使用 DefaultAzureCredential 对客户端进行认证。

接下来，将 AAD 应用的客户端 ID、租户 ID 和客户端机密设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET

您还需要通过在客户端选项中指定 clientId 来指定您打算使用的 Azure Maps 资源。Azure Maps 资源客户端 ID 可在 Azure Maps 资源的认证部分找到。请参阅文档了解如何找到它。

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 Maps 路线客户端库允许您通过使用专用的客户端对象与每个组件进行交互。

同步客户端

MapsRouteClient 是 Python 的 Azure Maps 路线客户端库的开发者使用的主要客户端。一旦初始化了 MapsRouteClient 类，您就可以通过探索此客户端对象上的方法来了解您可以访问的 Azure Maps 路线服务的不同功能。

异步客户端

此库包括一个完全支持 Python 3.5+ 的异步 API。要使用它，您必须首先安装一个异步传输，例如 aiohttp。有关更多信息，请参阅azure-core 文档。

不再需要时，应关闭异步客户端和凭证。这些对象是异步上下文管理器，并定义了异步 close 方法。

示例

以下部分提供了一些代码片段，涵盖了 Azure Maps 路线的一些最常见任务，包括

• 请求和获取路线方向
• 请求和获取路线范围
• 获取路线矩阵
• 获取路线方向批量

请求和获取路线方向

此服务请求返回从起点到终点的路线，如果指定了途经点，则将通过途经点。路线将考虑当前交通状况以及请求的星期几和一天中的时间典型道路速度等因素。

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。

日志记录

此库使用标准的logging库进行日志记录。HTTP会话（URL、头等）的基本信息以INFO级别进行记录。

启用详细DEBUG级别日志记录，包括请求/响应体和未删除的头信息，可以在具有logging_enable参数的客户端上启用。

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)

其他

仍在遇到问题？如果您遇到任何错误或提出建议，请在项目的问题部分提交问题。

下一步操作

更多示例代码

开始使用我们的地图路线示例（异步版本示例）。

在SDK的GitHub存储库中，您可以找到几个Azure Maps Route Python SDK示例。这些示例提供了在处理地图路线时通常遇到的附加场景的示例代码。

set AZURE_SUBSCRIPTION_KEY="<RealSubscriptionKey>"

pip install azure-maps-route --pre

python samples/sample_authentication.py
python sample/sample_get_route_range.py
python samples/sample_get_route_directions.py
python samples/sample_request_route_matrix.py
python samples/async_samples/sample_authentication_async.py
python samples/async_samples/sample_get_route_range_async.py
python samples/async_samples/sample_request_route_matrix_async.py
python samples/async_samples/sample_get_route_directions_async.py

注意：可以可选地添加--pre标志，它是为了在pip install中包含预发布和开发版本。默认情况下，pip只找到稳定版本。

更多信息请参阅示例介绍

其他文档

有关Azure Maps Route的更详细文档，请参阅docs.microsoft.com上的Azure Maps Route文档。

贡献

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权利并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并相应地装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需要在整个使用我们的CLA的存储库中进行一次此操作。

此项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ或通过opencode@microsoft.com联系以获取任何额外的问题或评论。

发行历史

1.0.0b1 (2022-10-13)

• 首次发布