Azure Maps Geolocation Package客户端库

此软件包包含用于地理定位的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.7或更高版本。
• 一个Azure订阅和一个Azure 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-geolocation

创建和认证 MapsGeolocationClient

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

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

geolocation_client = MapsGeolocationClient(
    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.geolocation import MapsGeolocationClient
from azure.identity import DefaultAzureCredential

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

关键概念

Azure Maps 地理位置 Python 客户端库允许您通过使用专用客户端对象与每个组件进行交互。

同步客户端

MapsGeolocationClient 是 Python Azure Maps 地理位置客户端库的开发者使用的首要客户端。一旦初始化了一个 MapsGeolocationClient 类，您就可以探索此客户端对象上的方法，了解您可以访问的 Azure Maps 地理位置服务的不同功能。

异步客户端

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

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

示例

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

• 获取地理定位

获取地理定位

本服务将返回提供的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。

日志记录

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

详细DEBUG级别日志记录，包括请求数据/响应数据和未删除的头信息，可以通过在客户端使用logging_enable参数来启用

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)

其他

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

下一步

更多示例代码

开始使用我们的地图地理位置示例（异步版本示例）。

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

set AZURE_SUBSCRIPTION_KEY="<RealSubscriptionKey>"

pip install azure-maps-geolocation --pre

python samples/sample_authentication.py
python sample/sample_get_country_code.py

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

更多详情请参阅示例简介

其他文档

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

贡献

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

当您提交pull请求时，CLA机器人将自动判断您是否需要提供CLA，并相应地装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您在整个使用我们CLA的所有仓库中只需这样做一次。

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

发行历史

1.0.0b1 (2022-10-11)

新增功能

• 初始发布