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

C# REST SDK 开发人员指南

项目
10/16/2024

Azure Maps C# SDK 支持 Azure Maps Rest API 中提供的功能，例如搜索地址、在不同坐标之间规划路线，以及获取特定 IP 地址的地理位置。本文将通过示例介绍 C# REST SDK，以帮助你开始生成位置感知的、整合了 Azure Maps 强大功能的 C# 应用程序。

注意

Azure Maps C# SDK 支持与 .NET 标准 2.0 或更高版本兼容的所有 .NET 版本。有关交互式表的信息，请参阅 .NET Standard 版本。

先决条件

Azure Maps 帐户。
Azure Maps 中的订阅密钥或其他形式的身份验证。
.NET 标准版本 2.0 或更高版本。

提示

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

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

创建 .NET 项目

以下 PowerShell 代码片段演示如何通过 PowerShell 创建使用 .NET 7.0 的控制台程序 MapsDemo。可以使用任何与 .NET 标准 2.0 兼容的版本作为框架。

dotnet new console -lang C# -n MapsDemo -f net7.0 
cd MapsDemo

安装所需程序包

若要使用 Azure Maps C# SDK，我们需要安装所需的包。每个 Azure Maps 服务（包括搜索、路线规划、呈现和地理位置）都包含在其自身的包中。由于 Azure Maps C# SDK 目前为公共预览版，因此需要添加 --prerelease 标志：

dotnet add package Azure.Maps.Rendering --prerelease
dotnet add package Azure.Maps.Routing --prerelease
dotnet add package Azure.Maps.Search --prerelease
dotnet add package Azure.Maps.Geolocation --prerelease

Azure Maps 服务

Service name	NuGet 包	示例
搜索	Azure.Maps.Search	搜索示例
路由	Azure.Maps.Routing	路由示例
呈现	Azure.Maps.Rendering	呈现示例
地理位置	Azure.Maps.Geolocation	地理位置示例

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

使用 Azure Maps 订阅密钥时，用于访问 Azure Maps 搜索 API 的客户端对象需要使用一个 AzureKeyCredential 对象进行身份验证；在使用 Microsoft Entra ID 进行身份验证时，它需要一个包含 Azure Maps 客户端 ID 的 TokenCredential 对象。有关身份验证的详细信息，请参阅向 Azure Maps 进行身份验证。

使用 Microsoft Entra 凭据

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

dotnet add package Azure.Identity

需要注册新的 Microsoft Entra 应用程序，并通过向服务主体分配所需角色来授予对 Azure Maps 的访问权限。有关详细信息，请参阅在非 Azure 资源上托管守护程序。此时将返回应用程序（客户端）ID、目录（租户）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 客户端：

using System;
using Azure.Identity; 
using Azure.Maps.Search; 

var credential = new DefaultAzureCredential(); 
var clientId = Environment.GetEnvironmentVariable("MAPS_CLIENT_ID"); 
var client = new MapsSearchClient(credential, clientId);

重要

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

使用订阅密钥凭据

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

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

$Env:SUBSCRIPTION_KEY="your subscription key"

创建环境变量后，可以在代码中访问它：

using System;
using Azure; 
using Azure.Maps.Search; 

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

对地址进行地理编码

调用 GetGeocoding 方法以获取地址的坐标。

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

Response<GeocodingResponse> searchResult = client.GetGeocoding(
    "1 Microsoft Way, Redmond, WA 98052");

for (int i = 0; i < searchResult.Value.Features.Count; i++)
{
    Console.WriteLine("Coordinate:" + string.Join(",", searchResult.Value.Features[i].Geometry.Coordinates));
}

批量对地址进行地理编码

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

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

List<GeocodingQuery> queries = new List<GeocodingQuery>
{
    new GeocodingQuery()
    {
        Query ="15171 NE 24th St, Redmond, WA 98052, United States"
    },
    new GeocodingQuery()
    {
        AddressLine = "400 Broad St"
    },
};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);

//Print coordinates
for (var i = 0; i < results.Value.BatchItems.Count; i++)
{
    for (var j = 0; j < results.Value.BatchItems[i].Features.Count; j++)
    {
        Console.WriteLine("Coordinates: " + string.Join(",", results.Value.BatchItems[i].Features[j].Geometry.Coordinates));
    }
}

对坐标进行反向地理编码

你可以将坐标转换为人类可理解的街道地址。此过程也称为反向地理编码。

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);
Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);

//Print addresses
for (int i = 0; i < result.Value.Features.Count; i++)
{
    Console.WriteLine(result.Value.Features[i].Properties.Address.FormattedAddress);
}

对一组坐标进行批量反向地理编码

Azure Maps 搜索还提供了一些批量查询 API。反向地理编码批量 API 仅使用单个 API 调用即可将批量查询发送到反向地理编码 API。该 API 允许调用方批处理最多 100 个查询。

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

List<ReverseGeocodingQuery> items = new List<ReverseGeocodingQuery>
{
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.349309, 47.620498)
    },
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.138679, 47.630356),
        ResultTypes = new List<ReverseGeocodingResultTypeEnum>(){ ReverseGeocodingResultTypeEnum.Address, ReverseGeocodingResultTypeEnum.Neighborhood }
    },
};
Response<GeocodingBatchResponse> result = client.GetReverseGeocodingBatch(items);
//Print addresses
for (var i = 0; i < result.Value.BatchItems.Count; i++)
{
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.AddressLine);
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.Neighborhood);
}

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

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

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Options;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

GetPolygonOptions options = new GetPolygonOptions()
{
    Coordinates = new GeoPosition(-122.204141, 47.61256),
    ResultType = BoundaryResultTypeEnum.Locality,
    Resolution = ResolutionEnum.Small,
};
Response<Boundary> result = client.GetPolygon(options);

var count = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates.Count;
for (var i = 0; i < count; i++)
{
    var coorCount = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i].Count;
    for (var j = 0; j < coorCount; j++)
    {
        Console.WriteLine(string.Join(",",((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i][j]));
    }
}

使用 V1 SDK 进行搜索和呈现

若要详细了解如何使用搜索 v1，请参阅适用于 .NET 的 Azure Maps 搜索客户端库。若要详细了解如何使用呈现 v1，请参阅适用于 .NET 的 Azure Maps 呈现客户端库。

其他信息

.NET 文档中的 Azure.Maps 命名空间。

通过