Azure Mapas Renderizar biblioteca de clientes para .NET – versão 1.0.0-beta.2

Azure Mapas Render é uma biblioteca que pode buscar blocos de imagem e informações de direitos autorais.

Código-fonte | Documentação | de referência da APIDocumentação | de referência da API RESTDocumentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de clientes para .NET com o NuGet:

dotnet add package Azure.Maps.Rendering --prerelease

Pré-requisitos

Você deve ter uma assinatura do Azure e uma conta Azure Mapas.

Para criar uma nova conta Azure Mapas, você pode usar o Portal do Azure, Azure PowerShell ou a CLI do Azure. Aqui, está um exemplo usando a CLI do Azure:

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

Autenticar o cliente

Há duas maneiras de autenticar o cliente: autenticação de chave compartilhada e Azure AD.

Autenticação de Chave Compartilhada

• Vá para Azure Mapas guia Autenticação de conta >
• Copiar Primary Key ou Secondary Key na seção Autenticação de Chave Compartilhada

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

Autenticação do Azure AD

Para interagir com o serviço Azure Mapas, você precisará criar uma instância da MapsRenderingClient classe . A biblioteca de Identidade do Azure facilita a adição do suporte do Azure Active Directory para autenticar clientes do SDK do Azure com seus serviços correspondentes do Azure.

Para usar a autenticação do AAD, as variáveis de ambiente, conforme descrito no README de Identidade do Azure e criar uma DefaultAzureCredential instância a ser usada com o MapsRenderingClient.

Também precisamos de uma ID do cliente Azure Mapas que possa ser encontrada na página > Azure Mapas guia > Autenticação "ID do cliente" na seção Autenticação do Azure Active Directory.

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

Autenticação SAS (Assinatura de Acesso Compartilhado)

Os tokens de SAS (assinatura de acesso compartilhado) são tokens de autenticação criados usando o formato JWT (token Web JSON) e são assinados criptograficamente para provar a autenticação de um aplicativo para a API REST do Azure Mapas.

Antes de integrar a autenticação de token SAS, precisamos instalar Azure.ResourceManager e Azure.ResourceManager.Maps (versão 1.1.0-beta.2 ou superior):

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

No código, precisamos importar as seguintes linhas para Azure Mapas SDK e ResourceManager:

using Azure.Maps.Rendering;

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

Em seguida, podemos obter o token SAS por meio da API Sas de Lista e atribuí-lo a MapsRenderingClient. No exemplo de código a seguir, buscamos um recurso de conta de mapas específico e criamos um token SAS por um dia de expiração quando o código é executado.

// 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);

Principais conceitos

MapsRenderingClient foi projetado para:

• Comunicar-se com Azure Mapas ponto de extremidade para obter imagens e blocos
• Comunicar-se com Azure Mapas ponto de extremidade para obter direitos autorais para imagens e blocos

Saiba mais sobre exemplos em exemplos

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções | do clienteAcessando a resposta | Operações de execução prolongada | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

Você pode se familiarizar com APIs diferentes usando nossos exemplos. Renderizar blocos de mapa requer conhecimento sobre níveis de zoom e sistema de grade de blocos. Consulte a documentação para obter mais informações.

Obter blocos de imagens

Aqui está um exemplo simples de renderização de blocos de imagens:

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);
}

Solução de problemas

Geral

Quando você interage com os serviços de Azure Mapas, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações de API REST.

Por exemplo, se você tentar obter um bloco de imagens com índice de bloco incorreto, um erro será retornado, indicando "Solicitação Incorreta" (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());
}

Próximas etapas

• Para obter mais contexto e cenários adicionais, consulte: exemplos detalhados

Participante

Consulte o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite <cla.microsoft.com>.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.