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

Azure Maps适用于 .NET 的地理位置客户端库 - 版本 1.0.0-beta.2

项目
07/20/2023

Azure Maps地理位置是一个库，可以找到某个位置或兴趣点的地理位置。

入门

安装包

使用 NuGet 安装适用于 .NET 的客户端库：

dotnet add package Azure.Maps.Geolocation --prerelease

先决条件

必须具有 Azure 订阅和Azure Maps帐户。

若要创建新的Azure Maps帐户，可以使用 Azure 门户、Azure PowerShell或 Azure CLI。下面是使用 Azure CLI 的示例：

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

验证客户端

可通过两种方式对客户端进行身份验证：共享密钥身份验证和 Azure AD。

共享密钥身份验证

转到“Azure Maps帐户>身份验证”选项卡
“共享密钥身份验证”部分下的“复制Primary Key”或Secondary Key

// Create a MapsGeolocationClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsGeolocationClient client = new MapsGeolocationClient(credential);

Azure AD 身份验证

若要与 Azure Maps 服务交互，需要创建类的MapsGeolocationClient实例。使用 Azure 标识库可以轻松添加 Azure Active Directory 支持，以便使用相应的 Azure 服务对 Azure SDK 客户端进行身份验证。

若要使用 AAD 身份验证，请设置 Azure 标识自述文件中所述的环境变量，并创建要 DefaultAzureCredential 与一起使用的 MapsRouteClient实例。

我们还需要Azure Maps客户端 ID，该 ID 可从“Azure Active Directory 身份验证”部分中的“身份验证”选项卡>Azure Maps页>获取。

// Create a MapsGeolocationClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsGeolocationClient client = new MapsGeolocationClient(credential, clientId);

共享访问签名 (SAS) 身份验证

共享访问签名 (SAS) 令牌是使用 JSON Web 令牌 (JWT) 格式创建的身份验证令牌，通过加密签名来证明应用程序对 Azure Maps REST API 的身份验证。

在集成 SAS 令牌身份验证之前，我们需要安装 Azure.ResourceManager 并 Azure.ResourceManager.Maps (版本 1.1.0-beta.2 或更高版本) ：

dotnet add package Azure.ResourceManager
dotnet add package Azure.ResourceManager.Maps --prerelease

在代码中，我们需要为 Azure Maps ResourceManager 导入以下行：

using Azure.Maps.Geolocation;
using Azure.Core;
using Azure.ResourceManager;
using Azure.ResourceManager.Maps;
using Azure.ResourceManager.Maps.Models;

然后，可以通过列出 Sas API 获取 SAS 令牌并将其 MapsGeolocationClient分配给。在以下代码示例中，我们提取特定的 maps 帐户资源，并在执行代码时创建 1 天的过期时间的 SAS 令牌。

// Get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// Authenticate your client
ArmClient armClient = new ArmClient(cred);

string subscriptionId = "MyMapsSubscriptionId";
string resourceGroupName = "MyMapsResourceGroupName";
string accountName = "MyMapsAccountName";

// Get maps account resource
ResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);

// Assign SAS token information
// Every time you want to SAS token, update the principal ID, max rate, start and expiry time
string principalId = "MyManagedIdentityObjectId";
int maxRatePerSecond = 500;

// Set start and expiry time for the SAS token in round-trip date/time format
DateTime now = DateTime.Now;
string start = now.ToString("O");
string expiry = now.AddDays(1).ToString("O");

MapsAccountSasContent sasContent = new MapsAccountSasContent(MapsSigningKey.PrimaryKey, principalId, maxRatePerSecond, start, expiry);
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);

// Create a SearchClient that will authenticate via SAS token
AzureSasCredential sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);
MapsGeolocationClient client = new MapsGeolocationClient(sasCredential);

关键概念

MapsGeolocationClient 设计用于：

与 Azure Maps Geolocation SDK 终结点通信，从给定的 IP 地址获取位置

详细了解示例中的示例

线程安全

我们保证所有客户端实例方法都是线程安全的，并且彼此独立 (准则) 。这可确保重用客户端实例的建议始终是安全的，即使在线程之间也是如此。

其他概念

示例

可以使用我们的示例熟悉不同的 API。

在调用地理位置 API 之前，请先实例化。MapsGeolocationClient 以下示例使用 AAD 创建客户端实例：

// Create a MapsGeolocationClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsGeolocationClient client = new MapsGeolocationClient(credential, clientId);

获取位置

此服务将返回提供的 IP 地址的 ISO 国家/地区代码。开发人员可以使用此信息根据查看应用程序的地理位置阻止或更改某些内容。

//Get location by given IP address
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");
Response<CountryRegionResult> result = client.GetCountryCode(ipAddress);

//Get location result country code
Console.WriteLine($"Country code results by given IP Address: {result.Value.IsoCode}");

有关更详细的示例，请参阅地理位置示例页。

疑难解答

常规

与 Azure Maps 服务交互时，语言服务返回的错误对应于为 REST API 请求返回的相同 HTTP 状态代码。

例如，如果传递了错误的 IP 地址，则返回错误，指示“错误的请求” (HTTP 状态代码：400) 。

try
{
    // An invalid IP address
    IPAddress inValidIpAddress = IPAddress.Parse("2001:4898:80e8:b:123123213123");

    Response<CountryRegionResult> result = client.GetCountryCode(inValidIpAddress);
    // Do something with result ...
}
catch (FormatException e)
{
    Console.WriteLine(e.ToString());
}

后续步骤

有关更多上下文和其他方案，请参阅：更详细的示例

供稿

有关构建、测试和参与此库的详细信息，请参阅 CONTRIBUTING.md 。

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 <cla.microsoft.com>。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

曝光数

通过