通过

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

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

  • 项目

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

源代码 | API 参考文档 | REST API 参考文档 | 产品文档

入门

安装包

使用 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 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。

曝光数