Guida per sviluppatori di C# REST SDK

L'SDK C# di Mappe di Azure supporta le funzionalità disponibili nell'API REST di Mappe di Azure, ad esempio la ricerca di un indirizzo, il routing tra coordinate diverse e il recupero della posizione geografica di un indirizzo IP specifico. Questo articolo presenta l'SDK REST C# con esempi che consentono di iniziare a creare applicazioni che supportano la posizione in C# che incorporano la potenza di Mappe di Azure.

Prerequisiti

• Account Mappe di Azure.
• Una chiave di sottoscrizione o un altro tipo di autenticazione con Mappe di Azure.
• .NET Standard versione 2.0 o successiva.

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

Creare un progetto .NET

Il frammento di codice di PowerShell seguente illustra come usare PowerShell per creare un programma console MapsDemo con .NET 7.0. È possibile usare qualsiasi versione compatibile con .NET Standard 2.0 come framework.

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

Installare i pacchetti necessari

Per usare C# SDK di Mappe di Azure, è necessario installare i pacchetti necessari. Ognuno dei servizi di Mappe di Azure, tra cui ricerca, routing, rendering e georilevazione, sono contenuti in un proprio pacchetto. Poiché C# SDK di Mappe di Azure è in anteprima pubblica, è necessario aggiungere il flag --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

Servizi di Mappe di Azure

Creare ed autenticare un oggetto MapsSearchClient

L'oggetto client usato per accedere alle API di ricerca di Mappe di Azure richiede un oggetto AzureKeyCredential per l'autenticazione quando si usa una chiave di sottoscrizione di Mappe di Azure o un oggetto TokenCredential con l'ID client di Mappe di Azure durante l'autenticazione con Microsoft Entra ID. Per altre informazioni sull'autenticazione, vedere Autenticazione con Mappe di Azure.

Uso delle credenziali di Microsoft Entra

È possibile eseguire l'autenticazione con Microsoft Entra ID usando la Libreria delle identità di Azure. Per usare il provider di DefaultAzureCredential, è necessario installare la libreria client di Identità di Azure per .NET:

dotnet add package Azure.Identity 

È necessario registrare la nuova applicazione Microsoft Entra e concedere l'accesso ad Mappe di Azure assegnando il ruolo richiesto al service principal. Per altre informazioni, vedere Ospitare un daemon in risorse non di Azure. Vengono restituiti l'ID applicazione (client), un ID directory (tenant) e un segreto client. Copiare questi valori e archiviarli in un luogo sicuro. Sono necessari nei passaggi seguenti.

Imposta come variabili di ambiente i valori dell'ID applicazione (client), dell'ID directory (tenant), del segreto client della tua applicazione Microsoft Entra e dell'ID client della risorsa di mappa:

A questo punto è possibile creare variabili di ambiente in PowerShell per archiviare questi valori:

$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"

Dopo aver configurato le variabili di ambiente, è possibile usarle nel programma per creare un'istanza del client 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); 

Uso di una credenziale con chiave di sottoscrizione

È possibile eseguire l'autenticazione con la chiave di sottoscrizione di Mappe di Azure. La chiave di sottoscrizione è disponibile nella sezione Autenticazione nell'account Mappe di Azure, come illustrato nello screenshot seguente:

A questo punto è possibile creare variabili di ambiente in PowerShell per archiviare la chiave di sottoscrizione:

$Env:SUBSCRIPTION_KEY="your subscription key"

Dopo aver creato la variabile di ambiente, è possibile accedervi nel codice:

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

Geocodificare un indirizzo

Chiamare il metodo GetGeocoding per ottenere la coordinata di un indirizzo.

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 indirizzi in blocco

Questo esempio illustra come eseguire una ricerca batch di indirizzi.

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 inversa di coordinate

È possibile convertire le coordinate in indirizzi stradali leggibili. Questo processo è chiamato anche geocodifica inversa.

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 inversa in modalità batch di una serie di coordinate

Ricerca di Mappe di Azure offre anche alcune API di query batch. L'API Batch di geocodifica inversa invia batch di query all’API di geocodifica inversa usando una singola chiamata API. L'API consente al chiamante di eseguire il batch fino a 100 query.

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

Ottenere i poligoni per una determinata posizione

Questo esempio illustra come cercare i poligoni.

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

Usa l'SDK v1 per la ricerca

Per maggiori informazioni sull'uso di Search v1, consulta Mappe di Azure Search per la libreria client .NET.

Informazioni aggiuntive

Spazio dei nomi di Azure.Maps nella documentazione di .NET.