Przewodnik dla deweloperów zestawu SDK REST języka C#

Artykuł
10/16/2024

Zestaw SDK języka C# usługi Azure Maps obsługuje funkcje dostępne w interfejsie API REST usługi Azure Maps, takie jak wyszukiwanie adresu, routing między różnymi współrzędnymi i uzyskiwanie lokalizacji geograficznej określonego adresu IP. W tym artykule przedstawiono zestaw SDK REST języka C# z przykładami, które ułatwiają rozpoczęcie tworzenia aplikacji obsługujących lokalizację w języku C#, które obejmują możliwości usługi Azure Maps.

Uwaga

Zestaw SDK języka C# usługi Azure Maps obsługuje dowolną wersję platformy .NET zgodną ze standardem .NET w wersji 2.0 lub nowszej. Aby zapoznać się z tabelą interaktywną, zobacz wersje platformy .NET Standard.

Wymagania wstępne

Konto usługi Azure Maps.
Klucz subskrypcji lub inna forma uwierzytelniania za pomocą usługi Azure Maps.
.NET Standard w wersji 2.0 lub nowszej.

Napiwek

Konto usługi Azure Maps można utworzyć programowo. Oto przykład przy użyciu interfejsu wiersza polecenia platformy Azure:

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

Tworzenie projektu platformy .NET

Poniższy fragment kodu programu PowerShell pokazuje, jak za pomocą programu PowerShell utworzyć program MapsDemo konsolowy za pomocą programu .NET 7.0. Jako platformę można użyć dowolnej wersji zgodnej ze standardem .NET 2.0.

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

Instalowanie wymaganych pakietów

Aby użyć zestawu SDK języka C# usługi Azure Maps, musimy zainstalować wymagane pakiety. Każda z usług Azure Maps, w tym wyszukiwanie, routing, renderowanie i geolokalizacja, znajdują się we własnym pakiecie. Ponieważ zestaw SDK języka C# usługi Azure Maps jest w publicznej wersji zapoznawczej, należy dodać 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

Usługi Azure Maps

Nazwa usługi	Pakiet NuGet	Próbki
Wyszukaj	Azure.Maps.Search	wyszukiwanie przykładów
Routing	Azure.Maps.Routing	przykłady routingu
Renderowanie	Azure.Maps.Rendering	renderowanie przykładu
Geolokalizacja	Azure.Maps.Geolocation	przykład geolokalizacji

Tworzenie i uwierzytelnianie elementu MapsSearchClient

Obiekt klienta używany do uzyskiwania dostępu do interfejsów API usługi Azure Maps Search wymaga AzureKeyCredential uwierzytelnienia obiektu podczas korzystania z klucza subskrypcji usługi Azure Maps lub TokenCredential obiektu z identyfikatorem klienta usługi Azure Maps podczas uwierzytelniania przy użyciu identyfikatora entra firmy Microsoft. Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Authentication with Azure Maps (Uwierzytelnianie za pomocą usługi Azure Maps).

Używanie poświadczeń entra firmy Microsoft

Możesz uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft przy użyciu biblioteki tożsamości platformy Azure. Aby użyć dostawcy DefaultAzureCredential , należy zainstalować bibliotekę klienta tożsamości platformy Azure dla platformy .NET:

dotnet add package Azure.Identity

Musisz zarejestrować nową aplikację Firmy Microsoft Entra i udzielić dostępu do usługi Azure Maps, przypisując wymaganą rolę do jednostki usługi. Aby uzyskać więcej informacji, zobacz Hostowanie demona w zasobach spoza platformy Azure. Zwracany jest identyfikator aplikacji (klienta), identyfikator katalogu (dzierżawy) i klucz tajny klienta. Skopiuj te wartości i zapisz je w bezpiecznym miejscu. Są one potrzebne w poniższych krokach.

Ustaw wartości identyfikatora aplikacji (klienta), identyfikatora katalogu (dzierżawy) i wpisu tajnego klienta aplikacji Microsoft Entra oraz identyfikator klienta zasobu mapy jako zmienne środowiskowe:

Zmienna środowiskowa	opis
AZURE_CLIENT_ID	Identyfikator aplikacji (klienta) w zarejestrowanej aplikacji
AZURE_CLIENT_SECRET	Wartość wpisu tajnego klienta w zarejestrowanej aplikacji
AZURE_TENANT_ID	Identyfikator katalogu (dzierżawy) w zarejestrowanej aplikacji
MAPS_CLIENT_ID	Identyfikator klienta w zasobie usługi Azure Map

Teraz możesz utworzyć zmienne środowiskowe w programie PowerShell, aby przechowywać następujące wartości:

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

Po skonfigurowaniu zmiennych środowiskowych możesz użyć ich w programie, aby utworzyć wystąpienie AzureMapsSearch klienta:

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

Ważne

Inne zmienne środowiskowe utworzone w poprzednim fragmencie kodu, choć nie są używane w przykładzie kodu, są wymagane przez element DefaultAzureCredential(). Jeśli te zmienne środowiskowe nie zostaną poprawnie ustawione, użyjesz tych samych konwencji nazewnictwa, wystąpią błędy czasu wykonywania. Jeśli na przykład brakuje lub jest on nieprawidłowy, AZURE_CLIENT_ID zostanie wyświetlony InvalidAuthenticationTokenTenant błąd.

Używanie poświadczeń klucza subskrypcji

Możesz uwierzytelnić się przy użyciu klucza subskrypcji usługi Azure Maps. Klucz subskrypcji można znaleźć w sekcji Uwierzytelnianie na koncie usługi Azure Maps, jak pokazano na poniższym zrzucie ekranu:

Teraz możesz utworzyć zmienne środowiskowe w programie PowerShell, aby przechowywać klucz subskrypcji:

$Env:SUBSCRIPTION_KEY="your subscription key"

Po utworzeniu zmiennej środowiskowej możesz uzyskać do niej dostęp w kodzie:

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

Geokodowanie adresu

Wywołaj metodę , GetGeocoding aby uzyskać współrzędną adresu.

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

Adresy geokodów wsadowych

W tym przykładzie pokazano, jak wykonać wyszukiwanie wsadowe.

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

Odwrotne geokodowanie współrzędnych

Współrzędne można przetłumaczyć na czytelne dla człowieka adresy uliczne. Ten proces jest również nazywany odwrotnym geokodowaniem.

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

Odwrotne geokodowanie wsadowe — zestaw współrzędnych

Usługa Azure Maps Search udostępnia również niektóre interfejsy API zapytań wsadowych. Odwrotny interfejs API geokodowania wsadowego wysyła partie zapytań do interfejsu API odwrotnego geokodowania przy użyciu tylko jednego wywołania interfejsu API. Interfejs API umożliwia obiektowi wywołującego dzielenie na partie do 100 zapytań.

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

Pobieranie wielokątów dla danej lokalizacji

W tym przykładzie pokazano, jak wyszukiwać wielokąty.

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

Używanie zestawów SDK w wersji 1 na potrzeby wyszukiwania i renderowania

Aby uzyskać więcej informacji na temat korzystania z usługi Search w wersji 1, zobacz Biblioteka klienta usługi Azure Maps Search dla platformy .NET. Aby uzyskać więcej informacji na temat korzystania z funkcji Renderowanie w wersji 1, zobacz Biblioteka klienta renderowania usługi Azure Maps dla platformy .NET.

Dodatkowe informacje

Przestrzeń nazw Azure.Maps w dokumentacji platformy .NET.

Udostępnij za pośrednictwem