Guia de desenvolvedores do C# REST SDK

Artigo
10/14/2024

O SDK C# do Azure Maps dá suporte à funcionalidade disponível na API Rest do Azure Maps, como procurar um endereço, rotear entre coordenadas diferentes e obter a localização geográfica de um endereço IP específico. Este artigo apresenta o C# REST SDK com exemplos para ajudá-lo a começar a criar aplicativos com reconhecimento de local em C# que incorporam o poder do Azure Maps.

Nota

O SDK do Azure Maps C# dá suporte a qualquer versão do .NET que seja compatível com o .NET standard versão 2.0 ou superior. Para obter uma tabela interativa, consulte Versões do .NET Standard.

Pré-requisitos

Conta do Azure Maps.
Chave de subscrição ou outra forma de Autenticação com o Azure Maps.
.NET standard versão 2.0 ou superior.

Gorjeta

Você pode criar uma conta do Azure Maps programaticamente, Aqui está um exemplo usando a CLI do Azure:

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

Criar um projeto .NET

O trecho de código do PowerShell a seguir demonstra como usar o PowerShell para criar um programa MapsDemo de console com o .NET 7.0. Você pode usar qualquer versão compatível com o .NET standard 2.0 como a estrutura.

dotnet new console -lang C# -n MapsDemo -f net7.0 
cd MapsDemo

Instalar pacotes necessários

Para usar o SDK C# do Azure Maps, precisamos instalar os pacotes necessários. Cada um dos serviços do Azure Maps, incluindo pesquisa, roteamento, renderização e geolocalização, está cada um em seu próprio pacote. Como o SDK C# do Azure Maps está em visualização pública, você precisa adicionar o --prerelease sinalizador:

dotnet add package Azure.Maps.Rendering --prerelease
dotnet add package Azure.Maps.Routing --prerelease
dotnet add package Azure.Maps.Search --prerelease
dotnet add package Azure.Maps.Geolocation --prerelease

Serviços do Azure Maps

Nome do serviço	Pacote NuGet	Amostras
Procurar	Azure.Maps.Search	Exemplos de pesquisa
Encaminhamento	Azure.Maps.Routing	Exemplos de roteamento
Composição	Azure.Maps.Rendering	Exemplo de renderização
Geolocalização	Azure.Maps.Geolocalização	Exemplo de geolocalização

Criar e autenticar um MapsSearchClient

O objeto cliente usado para acessar as APIs de Pesquisa do Azure Maps requer um AzureKeyCredential objeto para autenticação ao usar uma chave de assinatura do Azure Maps ou um TokenCredential objeto com a ID do cliente do Azure Maps ao autenticar usando a ID do Microsoft Entra. Para obter mais informações sobre autenticação, consulte Autenticação com mapas do Azure.

Usando uma credencial do Microsoft Entra

Você pode autenticar com o Microsoft Entra ID usando a biblioteca de Identidade do Azure. Para usar o provedor DefaultAzureCredential , você precisa instalar a biblioteca de cliente do Azure Identity para .NET:

dotnet add package Azure.Identity

Você precisa registrar o novo aplicativo Microsoft Entra e conceder acesso ao Azure Maps atribuindo a função necessária à sua entidade de serviço. Para obter mais informações, consulte Hospedar um daemon em recursos que não sejam do Azure. A ID do aplicativo (cliente), uma ID de diretório (locatário) e um segredo do cliente são retornados. Copie esses valores e armazene-os em um local seguro. Você precisa deles nas etapas a seguir.

Defina os valores da ID do aplicativo (cliente), da ID do diretório (locatário) e do segredo do cliente do seu aplicativo Microsoft Entra e da ID do cliente do recurso de mapa como variáveis de ambiente:

Variável de Ambiente	Description
AZURE_CLIENT_ID	ID do pedido (cliente) na sua candidatura registada
AZURE_CLIENT_SECRET	O valor do segredo do cliente na sua aplicação registada
AZURE_TENANT_ID	ID do diretório (locatário) em seu aplicativo registrado
MAPS_CLIENT_ID	A ID do cliente em seu recurso de Mapa do Azure

Agora você pode criar variáveis de ambiente no PowerShell para armazenar esses valores:

$Env:AZURE_CLIENT_ID="Application (client) ID"
$Env:AZURE_CLIENT_SECRET="your client secret"
$Env:AZURE_TENANT_ID="your Directory (tenant) ID"
$Env:MAPS_CLIENT_ID="your Azure Maps client ID"

Depois de configurar as variáveis de ambiente, você pode usá-las em seu programa para instanciar o AzureMapsSearch cliente:

using System;
using Azure.Identity; 
using Azure.Maps.Search; 

var credential = new DefaultAzureCredential(); 
var clientId = Environment.GetEnvironmentVariable("MAPS_CLIENT_ID"); 
var client = new MapsSearchClient(credential, clientId);

Importante

As outras variáveis de ambiente criadas no trecho de código anterior, embora não sejam usadas no exemplo de código, são exigidas pelo DefaultAzureCredential(). Se você não definir essas variáveis de ambiente corretamente, usando as mesmas convenções de nomenclatura, obterá erros em tempo de execução. Por exemplo, se o seu AZURE_CLIENT_ID estiver ausente ou inválido, você receberá um InvalidAuthenticationTokenTenant erro.

Usando uma credencial de chave de assinatura

Pode autenticar-se com a sua chave de subscrição do Azure Maps. Sua chave de assinatura pode ser encontrada na seção Autenticação na conta do Azure Maps, conforme mostrado na captura de tela a seguir:

Agora você pode criar variáveis de ambiente no PowerShell para armazenar a chave de assinatura:

$Env:SUBSCRIPTION_KEY="your subscription key"

Depois que a variável de ambiente for criada, você poderá acessá-la em seu código:

using System;
using Azure; 
using Azure.Maps.Search; 

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

Geocodificar um endereço

Chame o GetGeocoding método para obter a coordenada de um endereço.

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

Response<GeocodingResponse> searchResult = client.GetGeocoding(
    "1 Microsoft Way, Redmond, WA 98052");

for (int i = 0; i < searchResult.Value.Features.Count; i++)
{
    Console.WriteLine("Coordinate:" + string.Join(",", searchResult.Value.Features[i].Geometry.Coordinates));
}

Endereços de geocódigo de lote

Este exemplo demonstra como executar o endereço de pesquisa em lote.

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

List<GeocodingQuery> queries = new List<GeocodingQuery>
{
    new GeocodingQuery()
    {
        Query ="15171 NE 24th St, Redmond, WA 98052, United States"
    },
    new GeocodingQuery()
    {
        AddressLine = "400 Broad St"
    },
};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);

//Print coordinates
for (var i = 0; i < results.Value.BatchItems.Count; i++)
{
    for (var j = 0; j < results.Value.BatchItems[i].Features.Count; j++)
    {
        Console.WriteLine("Coordinates: " + string.Join(",", results.Value.BatchItems[i].Features[j].Geometry.Coordinates));
    }
}

Inverter geocodificar uma coordenada

Você pode traduzir coordenadas em endereços legíveis por humanos. Este processo também é chamado de geocodificação reversa.

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential); 

GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);
Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);

//Print addresses
for (int i = 0; i < result.Value.Features.Count; i++)
{
    Console.WriteLine(result.Value.Features[i].Properties.Address.FormattedAddress);
}

Geocódigo reverso de lote um conjunto de coordenadas

A Pesquisa de Mapas do Azure também fornece algumas APIs de consulta em lote. A API de Lote de Geocodificação Reversa envia lotes de consultas para a API de Geocodificação Reversa usando apenas uma única chamada de API. A API permite que o chamador agrupe até 100 consultas.

using System;
using Azure; 
using Azure.Maps.Search; 
using System.Collections.Generic;
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Queries;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

List<ReverseGeocodingQuery> items = new List<ReverseGeocodingQuery>
{
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.349309, 47.620498)
    },
    new ReverseGeocodingQuery()
    {
        Coordinates = new GeoPosition(-122.138679, 47.630356),
        ResultTypes = new List<ReverseGeocodingResultTypeEnum>(){ ReverseGeocodingResultTypeEnum.Address, ReverseGeocodingResultTypeEnum.Neighborhood }
    },
};
Response<GeocodingBatchResponse> result = client.GetReverseGeocodingBatch(items);
//Print addresses
for (var i = 0; i < result.Value.BatchItems.Count; i++)
{
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.AddressLine);
    Console.WriteLine(result.Value.BatchItems[i].Features[0].Properties.Address.Neighborhood);
}

Obter polígonos para um determinado local

Este exemplo demonstra como pesquisar polígonos.

using System;
using Azure; 
using Azure.Maps.Search; 
using Azure.Core.GeoJson;
using Azure.Maps.Search.Models;
using Azure.Maps.Search.Models.Options;

// Use Azure Maps subscription key authentication 
var subscriptionKey = Environment.GetEnvironmentVariable("SUBSCRIPTION_KEY") ?? string.Empty;
var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

GetPolygonOptions options = new GetPolygonOptions()
{
    Coordinates = new GeoPosition(-122.204141, 47.61256),
    ResultType = BoundaryResultTypeEnum.Locality,
    Resolution = ResolutionEnum.Small,
};
Response<Boundary> result = client.GetPolygon(options);

var count = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates.Count;
for (var i = 0; i < count; i++)
{
    var coorCount = ((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i].Count;
    for (var j = 0; j < coorCount; j++)
    {
        Console.WriteLine(string.Join(",",((GeoJsonPolygon)((GeoJsonGeometryCollection)result.Value.Geometry).Geometries[0]).Coordinates[i][j]));
    }
}

Usando SDKs V1 para pesquisa e renderização

Para obter mais informações sobre como usar a Pesquisa v1, consulte Biblioteca de cliente do Azure Maps Search para .NET. Para obter mais informações sobre como usar o Render v1, consulte Biblioteca de cliente de renderização do Azure Maps para .NET.

Informações adicionais

O namespace Azure.Maps na documentação do .NET.

Partilhar via