你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Python REST SDK 开发人员指南（预览版）

项目
10/17/2024

Azure Maps Python SDK 可与 Python 应用程序和库集成，以生成与地图相关的位置感知应用程序。 Azure Maps Python SDK 包含用于搜索、路线规划、呈现和地理位置的 API。这些 API 支持搜索地址、在不同坐标之间规划路线、获取特定 IP 地址的地理位置等操作。

先决条件

Azure Maps 帐户。
Azure Maps 中的订阅密钥或其他形式的身份验证。
Python 3.8 或更高版本。建议使用最新版本。有关详细信息，请参阅 Azure SDK for Python 版本支持策略。

提示

可以通过编程方式创建 Azure Maps 帐户。下面是使用 Azure CLI 的示例：

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

创建 Python 项目

以下示例演示如何使用 Python 创建名为 demo 的控制台程序：

mkdir mapsDemo 
cd mapsDemo 
New-Item demo.py

安装所需的 Python 包

Azure Maps 中的每个服务包含在其自己的包中。使用 Azure Maps Python SDK 时，可以仅安装所需服务的包。

在此处我们将安装 Azure Maps 搜索包。由于它仍为公共预览版，因此需要添加 --pre 标志：

pip install azure-maps-search --pre

Azure Maps 服务

Azure Maps Python SDK 支持 Python 版本 3.8 或更高版本。有关未来 Python 版本的详细信息，请参阅 Azure SDK for Python 版本支持策略。

Service name	PyPi 包	示例
搜索	azure-maps-search	搜索示例
Route	azure-maps-route	路由示例
呈现	azure-maps-render	呈现示例
地理位置	azure-maps-geolocation	地理位置示例

创建 MapsSearchClient 并对其进行身份验证

创建用于访问 Azure Maps 搜索 API 的 credential 对象时，需要 MapsSearchClient 对象进行身份验证。可以使用 Microsoft Entra 凭据或 Azure 订阅密钥进行身份验证。有关身份验证的详细信息，请参阅向 Azure Maps 进行身份验证。

提示

MapsSearchClient 是开发人员使用 Azure Maps 搜索库的主要接口。请参阅 Azure Maps 搜索包客户端库，详细了解可用的搜索方法。

使用 Microsoft Entra 凭据

可以使用 Azure 标识包对 Microsoft Entra ID 进行身份验证。若要使用 DefaultAzureCredential 提供程序，需要安装 Azure 标识客户端包：

pip install azure-identity

需要注册新的 Microsoft Entra 应用程序，并通过向服务主体分配所需角色来授予对 Azure Maps 的访问权限。有关详细信息，请参阅在非 Azure 资源上托管守护程序。此时将返回应用程序（客户端）ID、目录（租户）ID 和和客户端密码。复制这些值并将其存储在安全位置。在后续步骤中需要用到这些值。

接下来，需要通过指定地图的客户端 ID 来指定你要使用的 Azure Maps 帐户。可以在 Azure Maps 帐户的“身份验证”部分找到 Azure Maps 帐户客户端 ID。有关详细信息，请参阅查看身份验证详细信息。

将 Microsoft Entra 应用程序的应用程序（客户端）ID、目录（租户）ID 和客户端机密的值以及映射资源的客户端 ID 设置为环境变量：

环境变量	描述
AZURE_CLIENT_ID	已注册的应用程序中的应用程序（客户端）ID
AZURE_CLIENT_SECRET	已注册的应用程序中客户端密码的值
AZURE_TENANT_ID	已注册的应用程序中的目录（租户）ID
MAPS_CLIENT_ID	Azure Maps 帐户中的客户端 ID

现在，可以在 PowerShell 中创建环境变量来存储这些值：

$Env:AZURE_CLIENT_ID="Application (client) ID"
$Env:AZURE_CLIENT_SECRET="your client secret"
$Env:AZURE_TENANT_ID="your Directory (tenant) ID"
$Env:MAPS_CLIENT_ID="your Azure Maps client ID"

设置环境变量后，可以在程序中使用它们来实例化 AzureMapsSearch 客户端。创建一个名为 demo.py 的文件，并添加以下代码：

import os
from azure.identity import DefaultAzureCredential 
from azure.maps.search import MapsSearchClient 

credential = DefaultAzureCredential()
maps_client_id = os.getenv("MAPS_CLIENT_ID")
maps_search_client = MapsSearchClient(
    client_id=maps_client_id,
    credential=credential
)

重要

虽然在上一个代码片段中创建的其他环境变量未用于代码示例，但 DefaultAzureCredential() 需要使用它们。如果未使用相同的命名约定正确设置这些环境变量，则会出现运行时错误。例如，如果 AZURE_CLIENT_ID 缺失或无效，则会出现 InvalidAuthenticationTokenTenant 错误。

使用订阅密钥凭据

可以使用 Azure Maps 订阅密钥进行身份验证。可以在 Azure Maps 帐户的“身份验证”部分找到订阅密钥，如以下屏幕截图所示：

现在，可以在 PowerShell 中创建环境变量来存储订阅密钥：

$Env:SUBSCRIPTION_KEY="your subscription key"

创建环境变量后，可以在代码中访问它。创建一个名为 demo.py 的文件，并添加以下代码：

import os

from azure.core.credentials import AzureKeyCredential
from azure.maps.search import MapsSearchClient

# Use Azure Maps subscription key authentication
subscription_key = os.getenv("SUBSCRIPTION_KEY")
maps_search_client = MapsSearchClient(
   credential=AzureKeyCredential(subscription_key)
)

对地址进行地理编码

以下代码片段演示了如何在简单的控制台应用程序中获取给定地址的经度和纬度坐标。此示例使用订阅密钥凭据对 MapsSearchClient 进行身份验证。在 demo.py中：

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def geocode():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_geocoding(query="15127 NE 24th Street, Redmond, WA 98052")
        if result.get('features', False):
            coordinates = result['features'][0]['geometry']['coordinates']
            longitude = coordinates[0]
            latitude = coordinates[1]

            print(longitude, latitude)
        else:
            print("No results")

    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    geocode()

以上示例代码使用 Azure Maps 订阅密钥实例化 AzureKeyCredential，然后实例化 MapsSearchClient 对象。 MapsSearchClient 提供的方法将请求转发到 Azure Maps REST 终结点。最后，该程序循环访问结果并输出每个结果的坐标。

批量对地址进行地理编码

此示例演示了如何执行批量搜索地址：

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def geocode_batch():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_geocoding_batch({
          "batchItems": [
            {"query": "400 Broad St, Seattle, WA 98109"},
            {"query": "15127 NE 24th Street, Redmond, WA 98052"},
          ],
        },)

        if not result.get('batchItems', False):
            print("No batchItems in geocoding")
            return

        for item in result['batchItems']:
            if not item.get('features', False):
                print(f"No features in item: {item}")
                continue

            coordinates = item['features'][0]['geometry']['coordinates']
            longitude, latitude = coordinates
            print(longitude, latitude)

    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    geocode_batch()

执行反向地址搜索，将坐标位置转换为街道地址。

你可以将坐标转换为人类可理解的街道地址。此过程也称为反向地理编码。这通常用于使用 GPS 源并且要发现位于特定坐标点的地址的应用程序。

import os

from azure.core.exceptions import HttpResponseError

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def reverse_geocode():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_reverse_geocoding(coordinates=[-122.138679, 47.630356])
        if result.get('features', False):
            props = result['features'][0].get('properties', {})
            if props and props.get('address', False):
                print(props['address'].get('formattedAddress', 'No formatted address found'))
            else:
                print("Address is None")
        else:
            print("No features available")
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")


if __name__ == '__main__':
   reverse_geocode()

批量处理反向地理编码请求

此示例演示了如何批量根据给定坐标执行反向搜索。

import os
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import HttpResponseError
from azure.maps.search import MapsSearchClient

subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def reverse_geocode_batch():
    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_reverse_geocoding_batch({
              "batchItems": [
                {"coordinates": [-122.349309, 47.620498]},
                {"coordinates": [-122.138679, 47.630356]},
              ],
            },)

        if result.get('batchItems', False):
            for idx, item in enumerate(result['batchItems']):
                features = item['features']
                if features:
                    props = features[0].get('properties', {})
                    if props and props.get('address', False):
                        print(
                            props['address'].get('formattedAddress', f'No formatted address for item {idx + 1} found'))
                    else:
                        print(f"Address {idx + 1} is None")
                else:
                    print(f"No features available for item {idx + 1}")
        else:
            print("No batch items found")
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")


if __name__ == '__main__':
   reverse_geocode_batch()

获取表示给定位置的多边形

此示例演示了如何搜索多边形。

import os

from azure.core.exceptions import HttpResponseError
from azure.maps.search import Resolution
from azure.maps.search import BoundaryResultType


subscription_key = os.getenv("AZURE_SUBSCRIPTION_KEY", "your subscription key")

def get_polygon():
    from azure.core.credentials import AzureKeyCredential
    from azure.maps.search import MapsSearchClient

    maps_search_client = MapsSearchClient(credential=AzureKeyCredential(subscription_key))
    try:
        result = maps_search_client.get_polygon(
          coordinates=[-122.204141, 47.61256],
          result_type=BoundaryResultType.LOCALITY,
          resolution=Resolution.SMALL,
        )

        if not result.get('geometry', False):
            print("No geometry found")
            return

        print(result["geometry"])
    except HttpResponseError as exception:
        if exception.error is not None:
            print(f"Error Code: {exception.error.code}")
            print(f"Message: {exception.error.message}")

if __name__ == '__main__':
    get_polygon()

使用 V1 SDK 进行搜索和呈现

若要使用搜索 V1 和呈现 V1 SDK，请参阅“搜索 V1 SDK”程序包页和“呈现 V1 SDK”程序包来了解详细信息。

其他信息

Azure SDK for Python 预览版文档中的 Azure Maps 搜索包客户端库。

通过