Guida per sviluppatori di C# REST SDK
Azure Maps C# SDK 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.
Nota
C# SDK di Mappe di Azure supporta qualsiasi versione di .NET compatibile con .NET Standard versione 2.0 o successiva. Per una tabella interattiva, vedere .NET Standard versions (Versioni di .NET Standard).
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.
Suggerimento
È possibile creare un account Mappe di Azure a livello di codice, di seguito è riportato un esempio usando l'interfaccia della riga di comando di Azure:
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
Nome servizio | Pacchetto NuGet | Esempi |
---|---|---|
Cerca | Azure.Maps.Search | esempi di ricerca |
Routing | Azure.Maps.Routing | esempi di routing |
Rendering | Azure.Maps.Rendering | esempio di rendering |
Georilevazione | Azure.Maps.Geolocation | esempio di georilevazione |
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 a Mappe di Azure assegnando il ruolo necessario all'entità servizio. 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.
Impostare i valori dell'ID applicazione (client), dell'ID directory (tenant), del segreto client dell'applicazione Microsoft Entra e dell'ID client della risorsa della mappa come variabili di ambiente:
Variabile di ambiente | Descrizione |
---|---|
AZURE_CLIENT_ID | ID applicazione (client) nell'applicazione registrata |
AZURE_CLIENT_SECRET | Valore del segreto client nell'applicazione registrata |
AZURE_TENANT_ID | ID directory (tenant) nell'applicazione registrata |
MAPS_CLIENT_ID | ID client nella risorsa di Mappe di Azure |
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);
Importante
Le altre variabili di ambiente create nel frammento di codice precedente, mentre non vengono usate nell'esempio di codice, sono richieste da DefaultAzureCredential()
. Se queste variabili di ambiente non vengono impostate correttamente, usando le stesse convenzioni di denominazione, si otterranno errori in fase di esecuzione. Ad esempio, se AZURE_CLIENT_ID
è mancante o non è valido, verrà visualizzato un errore di InvalidAuthenticationTokenTenant
.
Uso delle credenziali della 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));
}
Indirizzi di geocodifica batch
Questo esempio illustra come eseguire l'indirizzo di ricerca batch.
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));
}
}
Invertire la geocodifica delle 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 batch un set 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]));
}
}
Uso degli SDK V1 per la ricerca e il rendering
Per altre informazioni sull'uso di Ricerca v1, vedere la Libreria client di Ricerca di Mappe di Azure per .NET. Per altre informazioni sull'uso di Render v1, vedere la Libreria client render di Mappe di Azure per .NET.
Informazioni aggiuntive
Spazio dei nomi di Azure.Maps nella documentazione di .NET.