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

Artigo
07/20/2023

Azure Mapas Geolocalização é uma biblioteca que pode encontrar a localização geográfica em um local ou pontos de interesse.

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

Introdução

Instalar o pacote

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

dotnet add package Azure.Maps.Geolocation --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

Acesse Azure Mapas guia Autenticação da conta >
Copiar Primary Key ou Secondary Key na seção Autenticação de Chave Compartilhada

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

Autenticação do Azure AD

Para interagir com o serviço Azure Mapas, você precisará criar uma instância da MapsGeolocationClient 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 do Azure correspondentes.

Para usar a autenticação do AAD, defina as variáveis de ambiente conforme descrito no LEIAME de Identidade do Azure e crie uma DefaultAzureCredential instância para usar com o MapsRouteClient.

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

// Create a MapsGeolocationClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsGeolocationClient client = new MapsGeolocationClient(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 ResourceManager:

using Azure.Maps.Geolocation;
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 MapsGeolocationClient. No exemplo de código a seguir, buscamos um recurso de conta de mapas específico e criamos um token SAS para 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);
MapsGeolocationClient client = new MapsGeolocationClient(sasCredential);

Principais conceitos

MapsGeolocationClient foi projetado para:

Comunicar-se com Azure Mapas ponto de extremidade do SDK de Geolocalização para obter a localização de determinado endereço IP

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

Exemplos

Você pode se familiarizar com diferentes APIs usando nossos Exemplos.

Antes de chamar APIs de geolocalização, instancie uma MapsGeolocationClient primeira. O exemplo abaixo usa o AAD para criar a instância do cliente:

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

Obter Localização

Esse serviço retornará o código de país ISO para o endereço IP fornecido. Os desenvolvedores podem usar essas informações para bloquear ou alterar determinado conteúdo com base em locais geográficos de onde o aplicativo está sendo exibido.

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

Para obter exemplos mais detalhados, consulte a página de exemplos de geolocalização .

Solução de problemas

Geral

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

Por exemplo, se você passar um endereço IP errado, um erro será retornado, indicando "Solicitação Incorreta" (código de status 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());
}

Próximas etapas

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

Participante

Consulte a 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.

Impressões