Azure Maps Render包客户端库

此包包含用于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.8或更高版本。
• 一个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-render

创建和验证 MapsRenderClient

要创建一个客户端对象以访问 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.render import MapsRenderClient

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

render_client = MapsRenderClient(
    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.render import MapsRenderClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
render_client = MapsRenderClient(
    client_id="<Azure Maps Client ID>",
    credential=credential
)

关键概念

Azure Maps 渲染客户端库允许您通过使用专门的客户端对象与每个组件进行交互。

同步客户端

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

异步客户端

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

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

示例

以下部分提供了几个代码片段，涵盖了 Azure Maps 渲染的一些常见任务，包括

• 获取地图归属
• 获取地图静态图像
• 获取地图瓦片
• 获取地图瓦片集
• 获取世界地图版权

获取地图归属

此请求允许用户请求瓦片集部分地图的版权归属信息。

from azure.core.credentials import AzureKeyCredential
from azure.maps.render import MapsRenderClient
from azure.maps.render import TilesetID

maps_render_client = MapsRenderClient(credential=AzureKeyCredential(subscription_key))

result = maps_render_client.get_map_attribution(
    tileset_id=TilesetID.MICROSOFT_BASE,
    zoom=6,
    bounds=[42.982261, 24.980233, 56.526017, 1.355233],
)

获取地图瓦片

此请求将返回以矢量或栅格格式返回的地图瓦片，通常用于集成到地图控件或SDK中。可以请求的示例瓦片包括Azure Maps道路瓦片、实时天气雷达瓦片。默认情况下，Azure Maps使用矢量瓦片为其网络地图控件（Web SDK）和Android SDK。

from azure.core.credentials import AzureKeyCredential
from azure.maps.render import MapsRenderClient
from azure.maps.render import TilesetID

maps_render_client = MapsRenderClient(credential=AzureKeyCredential(subscription_key))

result = maps_render_client.get_map_tile(
    tileset_id=TilesetID.MICROSOFT_BASE,
    z=6,
    x=9,
    y=22,
    tile_size="512"
)

获取地图瓦片集

此请求将为瓦片集提供元数据。

from azure.core.credentials import AzureKeyCredential
from azure.maps.render import MapsRenderClient
from azure.maps.render import TilesetID

maps_render_client = MapsRenderClient(credential=AzureKeyCredential(subscription_key))

result = maps_render_client.get_map_tileset(tileset_id=TilesetID.MICROSOFT_BASE)

获取地图静态图像

此请求将提供静态图像服务，该服务渲染用户定义的矩形图像，包含地图部分，使用从0到20的缩放级别。静态图像服务渲染用户定义的矩形图像，包含地图部分，使用从0到20的缩放级别。并将结果保存为png文件。

from azure.maps.render import MapsRenderClient

maps_render_client = MapsRenderClient(credential=AzureKeyCredential(subscription_key))

result = maps_render_client.get_map_static_image(
    zoom=10,
    bounding_box_private=[13.228, 52.4559, 13.5794, 52.629]
)

获取世界地图版权

此请求将为渲染瓦片服务提供版权信息。

from azure.core.credentials import AzureKeyCredential
from azure.maps.render import MapsRenderClient

maps_render_client = MapsRenderClient(credential=AzureKeyCredential(subscription_key))

result = maps_render_client.get_copyright_for_world()

故障排除

一般

地图渲染客户端抛出在Azure Core中定义的异常。

此列表可用于参考以捕获抛出的异常。要获取异常的具体错误代码，请使用error_code属性，即exception.error_code。

日志记录

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

可以通过客户端的logging_enable参数启用详细的DEBUG级别日志记录，包括请求/响应正文和未编辑的标题。

import sys
import logging
from azure.maps.render import MapsRenderClient

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

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

其他

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

下一步操作

更多示例代码

从我们的地图渲染示例开始（异步版本示例）。

SDK的GitHub存储库中提供了几个Azure Maps Render Python SDK示例。这些示例提供了在处理地图渲染时常见场景的示例代码。

set AZURE_SUBSCRIPTION_KEY="<RealSubscriptionKey>"

pip install azure-maps-render --pre

python samples/sample_authentication.py
python sample/sample_get_copyright_caption.py
python sample/sample_get_copyright_for_tile.py
python sample/sample_get_copyright_for_world.py
python sample/sample_get_copyright_from_bounding_box.py
python sample/sample_get_map_attribution.py
python sample/sample_get_map_static_image.py
python sample/sample_get_map_tile.py
python sample/sample_get_map_tileset.py

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

更多详细信息，请参阅示例简介

其他文档

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

贡献

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

当您提交拉取请求时，CLA-bot将自动确定您是否需要提供CLA，并适当地装饰PR（例如，标签、注释）。只需遵循bot提供的说明即可。您只需在整个使用我们的CLA的存储库中这样做一次。

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

发布历史

2.0.0b1 (2024-08-06)

新增功能

• 支持2024-04-01渲染API

1.0.0b3 (2024-05-15)

其他更改

• 修复Sphinx错误
• 修复mypy类型错误，针对mypy版本1.6.1

1.0.0b2 (2023-07-13)

其他更改

• 弃用高度瓦片枚举
• 移除对Python 3.6的支持

1.0.0b1 (2022-10-13)

新增功能

• 初始发布