Guia de desenvolvedores do C# REST SDK

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.

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.

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

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-se 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 registar o novo aplicativo Microsoft Entra e conceder acesso ao Azure Maps ao atribuir a função necessária ao seu principal de serviço. Para obter mais informações, consulte Hospedar um daemon em recursos que não sejam do Azure. O ID da Aplicação (cliente), um ID de Diretório (locatário) e um Segredo do Cliente são devolvidos. 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:

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

Usando uma credencial de chave de subscrição

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

Geocodificação em lote de endereços

Este exemplo demonstra como realizar a 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 coordenadas

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

Geocodificação reversa em lote de 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.