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

Azure Maps适用于 .NET 的呈现客户端库 - 版本 1.0.0-beta.2

项目
07/20/2023

Azure Maps Render 是一个库，可以提取图像磁贴和版权信息。

入门

安装包

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

dotnet add package Azure.Maps.Rendering --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 MapsRenderingClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsRenderingClient client = new MapsRenderingClient(credential);

Azure AD 身份验证

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

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

我们还需要一个Azure Maps客户端 ID，可在 azure Active Directory 身份验证部分Azure Maps页>“身份验证”选项卡>“客户端 ID”中找到。

AzureMapsPortal

// Create a MapsRenderingClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsRenderingClient client = new MapsRenderingClient(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 SDK 和 ResourceManager 导入以下行：

using Azure.Maps.Rendering;

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

然后，可以通过列出 Sas API 获取 SAS 令牌并将其 MapsRenderingClient分配给。在以下代码示例中，我们提取特定的 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);
MapsRenderingClient client = new MapsRenderingClient(sasCredential);

关键概念

MapsRenderingClient 设计用于：

与Azure Maps终结点通信以获取图像和磁贴
与Azure Maps终结点通信以获取图像和磁贴的版权

详细了解示例中的示例

线程安全

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

其他概念

示例

可以使用我们的示例熟悉不同的 API。呈现地图图块需要了解缩放级别和图块网格系统。有关详细信息，请参阅文档。

获取图像磁贴

下面是呈现图像磁贴的简单示例：

int zoom = 10, tileSize = 256;

// Get tile X, Y index by coordinate, zoom and tile size information
MapTileIndex tileIndex = MapsRenderingClient.PositionToTileXY(new GeoPosition(13.3854, 52.517), zoom, tileSize);

// Fetch imagery map tiles
GetMapTileOptions GetMapTileOptions = new GetMapTileOptions(
    MapTileSetId.MicrosoftImagery,
    new MapTileIndex(tileIndex.X, tileIndex.Y, zoom)
);
Response<Stream> mapTile = client.GetMapTile(GetMapTileOptions);

// Prepare a file stream to save the imagery
using (FileStream fileStream = File.Create(".\\BerlinImagery.png"))
{
    mapTile.Value.CopyTo(fileStream);
}

疑难解答

常规

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

例如，如果尝试获取具有错误的磁贴索引的图像磁贴，则会返回错误，指示“错误的请求” (HTTP 400) 。

try
{
    var options = new GetMapTileOptions(
        MapTileSetId.MicrosoftBaseHybrid,
        new MapTileIndex(12, 12, 2)
    );

    Response<Stream> imageryTile = client.GetMapTile(options);
    using var imageryStream = new MemoryStream();
    imageryTile.Value.CopyTo(imageryStream);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

后续步骤

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

供稿

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

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

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

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

曝光数

通过