Guia de desenvolvedores do SDK REST para C#

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

Pré-requisitos

• Conta do Azure Mapas.
• Chave de assinatura ou outra forma de autenticação com Azure Mapas.
• .NET Standard versão 2.0 ou superior.

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

Criar um projeto .NET

O snippet 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 os pacotes necessários

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

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 Mapas

Criar e autenticar um MapsSearchClient

O objeto cliente usado para acessar as APIs de Pesquisa do Azure Mapas exige que um objeto AzureKeyCredential seja autenticado ao usar uma chave de assinatura do Azure Mapas ou um objeto TokenCredential com a ID do cliente do Azure Mapas ao autenticar usando o Microsoft Entra ID. Para obter mais informações sobre autenticação, confira Autenticação no Azure Mapas.

Como usar 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ê precisará instalar a biblioteca de clientes da Identidade do Azure para .NET:

dotnet add package Azure.Identity 

Você precisa registrar o novo aplicativo do Microsoft Entra e conceder acesso ao Azure Mapas ao atribuir a função necessária ao seu service principal. Para obter mais informações, confira Hospedar um daemon em recursos que não são do Azure. O identificador do Aplicativo (cliente), um identificador de Diretório (locatário) e um segredo do cliente são retornados. Copie esses valores e armazene-os em um local seguro. Você precisará deles nas etapas a seguir.

Defina os valores do ID da Aplicação (cliente), ID do Diretório (locatário) e segredo do cliente da sua aplicação Microsoft Entra, além do ID do cliente do recurso do mapa, como variáveis de ambiente:

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 cliente AzureMapsSearch:

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

Usando uma credencial de chave de assinatura

Você pode autenticar com sua chave de assinatura do Azure Mapas. Sua chave de assinatura pode ser encontrada na seção Autenticação na conta do Azure Mapas, conforme mostrado na seguinte captura de tela:

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 método GetGeocoding 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));
}

Geocodificar endereços em lote

Este exemplo demonstra como realizar pesquisa de endereços 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));
    }
}

Geocodificação reversa de uma coordenada

Você pode traduzir coordenadas em endereços de rua legíveis por humanos. Esse 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);
}

Realizar a geocodificação reversa em lote de um conjunto de coordenadas

A Pesquisa do Azure Mapas também fornece algumas APIs de consulta em lote. A API em lote de geocodificação reversa envia lotes de solicitações para a API de Geocodificação Reversa por meio de uma única chamada de API. A API permite ao chamador agrupar em lote 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]));
    }
}

Use o SDK v1 para pesquisa

Para mais informações sobre o uso do Search v1, veja a biblioteca cliente Azure Mapas Search para .NET.

Informações adicionais

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