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

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.

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.

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

Utwórz i uwierzytelnij MapsSearchClient

"Obiekt klienta używany do uzyskiwania dostępu do interfejsów API Azure Maps Search wymaga obiektu AzureKeyCredential do uwierzytelniania przy użyciu klucza subskrypcji Azure Maps lub obiektu TokenCredential z identyfikatorem klienta Azure Maps przy uwierzytelnianiu za pomocą Microsoft Entra ID." 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 Microsoft Entra ID, korzystając z biblioteki Azure Identity. 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ę Microsoft Entra i udzielić dostępu do usługi Azure Maps, przypisując wymaganą rolę jednostce usługi. Aby uzyskać więcej informacji, zobacz Hostowanie demona w zasobach spoza platformy Azure. Zwracane są: identyfikator aplikacji (klienta), identyfikator katalogu (dzierżawy) oraz tajny klucz 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 tajnego klucza klienta Twojej aplikacji Microsoft Entra oraz identyfikatora klienta zasobu mapy jako zmienne środowiskowe:

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 zainicjować klienta 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); 

Używanie danych 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));
}

Geokodowanie adresów wsadowo

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

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

Wsadowe odwrotne geokodowanie zestawu współrzędnych

Usługa Azure Maps Search udostępnia również interfejsy API do zapytań wsadowych. Wsadowe API odwrotnego geokodowania wysyła partie zapytań do API odwrotnego geokodowania przy użyciu tylko jednego wywołania 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);
}

Pobierz wielokąty 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.