Entwicklerhandbuch für C# REST SDK

Artikel
10/16/2024

Das Azure Maps C# SDK unterstützt die in der Azure Maps-REST-API verfügbaren Funktionen, z. B. die Adresssuche, die Weiterleitung zwischen verschiedenen Koordinaten und das Abrufen des geografischen Standorts einer bestimmten IP-Adresse. In diesem Artikel wird das C# REST SDK mit Beispielen für die ersten Schritte beim Erstellen standortbezogener Anwendungen in C# vorgestellt, die die Leistungsfähigkeit von Azure Maps nutzen.

Hinweis

Das Azure Maps C# SDK unterstützt alle .NET-Versionen, die mit .NET Standard, Version 2.0 oder höher, kompatibel sind. Eine interaktive Tabelle finden Sie unter .NET Standard-Versionen.

Voraussetzungen

Azure Maps-Konto
Abonnementschlüssel oder eine andere Form der Authentifizierung bei Azure Maps.
.NET Standard, Version 2.0 oder höher

Tipp

Sie können ein Azure Maps-Konto programmgesteuert erstellen. Hier sehen Sie ein Beispiel unter Verwendung der Azure CLI:

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

Erstellen eines .NET-Projekts.

Der folgende PowerShell-Codeausschnitt veranschaulicht die Verwendung von PowerShell zum Erstellen des Konsolenprogramms MapsDemo mit .NET 7.0. Sie können jede mit .NET Standard 2.0 kompatible Version als Framework verwenden.

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

Installieren erforderlicher Pakete

Um das Azure Maps C# SDK zu verwenden, müssen die erforderlichen Pakete installiert werden. Jeder der Azure Maps-Dienste, darunter Suche, Routing, Rendering und Geolocation, befindet sich jeweils in einem eigenen Paket. Da sich das Azure Maps C# SDK in der öffentlichen Vorschau befindet, müssen Sie das --prerelease-Flag hinzufügen:

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

Azure Maps-Dienste

Dienstname	NuGet-Paket	Beispiele
Suchen	Azure.Maps.Search	Beispiele für Suchen
Routing	Azure.Maps.Routing	Beispiele für das Routing
Darstellung	Azure.Maps.Rendering	Beispiel für das Rendering
Geolocation	Azure.Maps.Geolocation	Beispiel für Geolocation

Erstellen und Authentifizieren eines MapsSearchClient-Elements

Das Clientobjekt, das für den Zugriff auf die Such-APIs von Azure Maps verwendet wird, erfordert entweder ein AzureKeyCredential-Objekt zur Authentifizierung, wenn ein Azure Maps-Abonnementschlüssel verwendet wird, oder ein TokenCredential-Objekt mit der Client-ID von Azure Maps, wenn die Authentifizierung mit Microsoft Entra ID erfolgt. Weitere Informationen zur Authentifizierung finden Sie unter Authentifizierung bei Azure Maps.

Verwenden von Microsoft Entra-Anmeldeinformationen

Sie können sich mithilfe der Azure Identity-Bibliothek bei Microsoft Entra ID authentifizieren. Um den Anbieter DefaultAzureCredential zu verwenden, müssen Sie die Azure Identity-Clientbibliothek für .NET installieren:

dotnet add package Azure.Identity

Sie müssen die neue Microsoft Entra-Anwendung registrieren und ihr Zugriff auf Azure Maps gewähren, indem Sie Ihrem Dienstprinzipal die erforderliche Rolle zuweisen. Weitere Informationen finden Sie unter Hosten eines Daemons für Nicht-Azure-Ressourcen. Zurückgegeben werden die Anwendungs-ID (Client), eine Verzeichnis-ID (Mandant) und ein geheimer Clientschlüssel. Kopieren Sie diese Werte, und speichern Sie sie an einem sicheren Ort. Sie benötigen diese in den folgenden Schritten.

Legen Sie die Werte der Anwendungs-ID (Client-ID), der Verzeichnis-ID (Mandanten-ID) und des geheimen Clientschlüssels Ihrer Microsoft Entra-Anwendung sowie der Client-ID der Kartenressource als Umgebungsvariablen fest:

Umgebungsvariable	BESCHREIBUNG
AZURE_CLIENT_ID	Anwendungs-ID (Client-ID) in Ihrer registrierten Anwendung
AZURE_CLIENT_SECRET	Der Wert des geheimen Clientschlüssels in Ihrer registrierten Anwendung
AZURE_TENANT_ID	Verzeichnis-ID (Mandanten-ID) in Ihrer registrierten Anwendung
MAPS_CLIENT_ID	Die Client-ID in Ihrer Azure Map-Ressource

Sie können nun Umgebungsvariablen in PowerShell erstellen, um diese Werte zu speichern:

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

Nach dem Einrichten der Umgebungsvariablen können Sie sie in Ihrem Programm verwenden, um den AzureMapsSearch-Client zu instanziieren:

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

Wichtig

Die anderen Umgebungsvariablen, die im vorherigen Codeschnipsel erstellt wurden, werden zwar im Codebeispiel nicht verwendet, sind aber für DefaultAzureCredential() erforderlich. Wenn Sie diese Umgebungsvariablen nicht richtig festlegen und dieselben Benennungskonventionen verwenden, treten Laufzeitfehler auf. Wenn AZURE_CLIENT_ID beispielsweise fehlt oder ungültig ist, erhalten Sie den Fehler InvalidAuthenticationTokenTenant.

Verwenden von Abonnementschlüssel-Anmeldeinformationen

Sie können sich mit Ihrem Azure Maps-Abonnementschlüssel authentifizieren. Ihren Abonnementschlüssel finden Sie im Abschnitt Authentifizierung im Azure Maps-Konto, wie im folgenden Screenshot gezeigt:

Sie können nun Umgebungsvariablen in PowerShell erstellen, um den Abonnementschlüssel zu speichern:

$Env:SUBSCRIPTION_KEY="your subscription key"

Nachdem Ihre Umgebungsvariable erstellt wurde, können Sie in Ihrem Code darauf zugreifen:

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

Geocodieren einer Adresse

Rufen Sie die GetGeocoding-Methode auf, um die Koordinaten einer Adresse zu erhalten.

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

Batchgeocodieren von Adressen

Dieses Beispiel veranschaulicht, wie die Batchsuche nach Adressen funktioniert.

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

Umgekehrte Geocodierung einer Koordinate

Sie können Koordinaten in für Menschen lesbare Straßenadressen übersetzen. Dieser Vorgang wird auch als umgekehrte Geocodierung bezeichnet.

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

Umgekehrte Batch-Geocodierung einer Reihe von Koordinaten

Azure Maps Search bietet auch eine Reihe von Batchabfrage-APIs. Die Reverse Geocoding Batch-API sendet Batches von Abfragen an die Reverse Geocoding-API mithilfe eines einzigen API-Aufrufs. Mit der API kann der Aufrufer bis zu 100 Abfragen stapelweise verarbeiten.

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

Abrufen von Polygonen für einen bestimmten Standort

In diesem Beispiel wird das Durchsuchen von Polygonen veranschaulicht.

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

Verwenden von V1-SDKs für Suchen und Rendern

Weitere Informationen zur Verwendung von Search v1 finden Sie unter Azure Maps Search-Clientbibliothek für .NET. Weitere Informationen zur Verwendung von Render v1 finden Sie unter Azure Maps Render-Clientbibliothek für .NET.

Zusätzliche Informationen

Azure.Maps-Namespace in der .NET-Dokumentation

Freigeben über