Azure Maps Routingclientbibliothek für .NET – Version 1.0.0-beta.2

Artikel
07/20/2023

Azure Maps Routing ist eine Bibliothek, die eine Route zu einem Standort oder zu interessanten Punkten finden kann.

Quellcode | API-Referenzdokumentation | REST-API-Referenzdokumentation | Produktdokumentation

Erste Schritte

Installieren des Pakets

Installieren Sie die Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Maps.Routing --prerelease

Voraussetzungen

Sie müssen über ein Azure-Abonnement und Azure Maps Konto verfügen.

Um ein neues Azure Maps-Konto zu erstellen, können Sie das Azure-Portal, Azure PowerShell oder die Azure CLI verwenden. Beispiel für die Verwendung der Azure-Befehlszeilenschnittstelle:

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

Authentifizieren des Clients

Es gibt zwei Möglichkeiten, den Client zu authentifizieren: Authentifizierung mit freigegebenem Schlüssel und Azure AD.

Authentifizierung mit gemeinsam verwendetem Schlüssel

Wechseln Sie zur Registerkarte "Kontoauthentifizierung>" Azure Maps.
Kopieren Primary Key oder Secondary Key im Abschnitt Authentifizierung mit freigegebenem Schlüssel

// Create a MapsRoutingClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsRoutingClient client = new MapsRoutingClient(credential);

Azure AD-Authentifizierung

Um mit dem Azure Maps-Dienst zu interagieren, müssen Sie eine instance der MapsRoutingClient -Klasse erstellen. Die Azure Identity-Bibliothek erleichtert das Hinzufügen von Azure Active Directory-Unterstützung für die Authentifizierung von Azure SDK-Clients mit den entsprechenden Azure-Diensten.

Um die AAD-Authentifizierung zu verwenden, legen Sie die Umgebungsvariablen wie in der Azure Identity-INFODATEI beschrieben fest, und erstellen Sie eine DefaultAzureCredential instance, die MapsRoutingClientmit verwendet werden soll.

Außerdem benötigen wir eine Azure Maps-Client-ID, die im Abschnitt "Azure Active Directory-Authentifizierung" auf der Azure Maps > Seite > "Client-ID" zu finden ist.

AzureMapsPortal

// Create a MapsRoutingClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsRoutingClient client = new MapsRoutingClient(credential, clientId);

SAS-Authentifizierung (Shared Access Signature)

Shared Access Signature (SAS)-Token sind Authentifizierungstoken, die mit dem JSON-Webtoken-Format (JWT) erstellt und kryptografisch signiert werden, um die Authentifizierung für eine Anwendung gegenüber der Azure Maps-REST-API nachzuweisen.

Vor der Integration der SAS-Tokenauthentifizierung müssen wir und Azure.ResourceManager.Maps (Version 1.1.0-beta.2 oder höher) installierenAzure.ResourceManager:

dotnet add package Azure.ResourceManager
dotnet add package Azure.ResourceManager.Maps --prerelease

Im Code müssen die folgenden Zeilen sowohl für Azure Maps SDK als auch für ResourceManager importiert werden:

using Azure.Core.GeoJson;
using Azure.Maps.Routing;
using Azure.Maps.Routing.Models;

using Azure.Core;
using Azure.ResourceManager;
using Azure.ResourceManager.Maps;
using Azure.ResourceManager.Maps.Models;

Anschließend können wir SAS-Token über die List Sas-API abrufen und es MapsRoutingClientzuweisen. Im folgenden Codebeispiel rufen wir eine bestimmte Zuordnungskontoressource ab und erstellen ein SAS-Token für eine Ablaufzeit von 1 Tag, wenn der Code ausgeführt wird.

// Get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// Authenticate your client
ArmClient armClient = new ArmClient(cred);

string subscriptionId = "MyMapsSubscriptionId";
string resourceGroupName = "MyMapsResourceGroupName";
string accountName = "MyMapsAccountName";

// Get maps account resource
ResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);

// Assign SAS token information
// Every time you want to SAS token, update the principal ID, max rate, start and expiry time
string principalId = "MyManagedIdentityObjectId";
int maxRatePerSecond = 500;

// Set start and expiry time for the SAS token in round-trip date/time format
DateTime now = DateTime.Now;
string start = now.ToString("O");
string expiry = now.AddDays(1).ToString("O");

MapsAccountSasContent sasContent = new MapsAccountSasContent(MapsSigningKey.PrimaryKey, principalId, maxRatePerSecond, start, expiry);
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);

// Create a SearchClient that will authenticate via SAS token
AzureSasCredential sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);
MapsRoutingClient client = new MapsRoutingClient(sasCredential);

Wichtige Begriffe

MapsRoutingClient wurde für Folgendes entwickelt:

Kommunizieren sie mit Azure Maps Endpunkt, um die Route zu Standorten oder Interessenpunkten zu erhalten
Kommunikation mit Azure Maps Endpunkt, um eine Reihe von Standorten zu berechnen, die vom Ursprungspunkt aus erreicht werden können, basierend auf dem angegebenen Kraftstoff-, Energie-, Zeit- oder Entfernungsbudget
Kommunizieren mit Azure Maps Endpunkt, um eine Matrix von Routenzusammenfassungen für eine Gruppe von Routen zu berechnen, die durch Ursprungs- und Zielorte definiert sind

Weitere Informationen finden Sie in unseren Beispielen.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Beispiele

Mithilfe unserer Beispiele können Sie sich mit verschiedenen APIs vertraut machen.

Instanziieren Sie vor dem Aufrufen von Routen-APIs eine MapsRoutingClient erste Instanz. In diesem Beispiel wird AAD verwendet, um den Client instance zu erstellen:

// Create a MapsRoutingClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsRoutingClient client = new MapsRoutingClient(credential, clientId);

Routenbeschreibung

Hier sehen Sie ein einfaches Beispiel für das Routing an einen Standort:

// Create origin and destination routing points
List<GeoPosition> routePoints = new List<GeoPosition>()
{
    new GeoPosition(123.751, 45.9375),
    new GeoPosition(123.791, 45.96875),
    new GeoPosition(123.767, 45.90625)
};

// Create Route direction query object
RouteDirectionQuery query = new RouteDirectionQuery(routePoints);
Response<RouteDirections> result = client.GetDirections(query);

// Route direction result
Console.WriteLine($"Total {0} route results", result.Value.Routes.Count);
Console.WriteLine(result.Value.Routes[0].Summary.LengthInMeters);
Console.WriteLine(result.Value.Routes[0].Summary.TravelTimeDuration);

// Route points
foreach (RouteLeg leg in result.Value.Routes[0].Legs)
{
    Console.WriteLine("Route path:");
    foreach (GeoPosition point in leg.Points)
    {
        Console.WriteLine($"point({point.Latitude}, {point.Longitude})");
    }
}

Sie können auch den Reisemodus, den Routentyp, die Sprache und andere Optionen angeben, wenn Sie zum Point of Interest weitergeleitet werden:

// Create origin and destination routing points
List<GeoPosition> routePoints = new List<GeoPosition>()
{
    new GeoPosition(123.751, 45.9375),
    new GeoPosition(123.791, 45.96875),
    new GeoPosition(123.767, 45.90625)
};

RouteDirectionOptions options = new RouteDirectionOptions()
{
    RouteType = RouteType.Fastest,
    UseTrafficData = true,
    TravelMode = TravelMode.Bicycle,
    Language = RoutingLanguage.EnglishUsa,
};

// Create Route direction query object
RouteDirectionQuery query = new RouteDirectionQuery(routePoints);
Response<RouteDirections> result = client.GetDirections(query);

// Route direction result
Console.WriteLine($"Total {0} route results", result.Value.Routes.Count);
Console.WriteLine(result.Value.Routes[0].Summary.LengthInMeters);
Console.WriteLine(result.Value.Routes[0].Summary.TravelTimeDuration);

// Route points
foreach (RouteLeg leg in result.Value.Routes[0].Legs)
{
    Console.WriteLine("Route path:");
    foreach (GeoPosition point in leg.Points)
    {
        Console.WriteLine($"point({point.Latitude}, {point.Longitude})");
    }
}

Ausführlichere Beispiele finden Sie auf der Seite Routenrichtungsbeispiele .

Routenmatrix

Um die Routenmatrix zwischen mehreren Ursprüngen und Zielen zu finden, sollten Azure Maps Routenmatrix-APIs Ihre Anforderungen erfüllen. Ein einfaches Routenmatrixanforderungsbeispiel sieht wie der folgende Codeausschnitt aus:

// A simple route matrix request
RouteMatrixQuery routeMatrixQuery = new RouteMatrixQuery
{
    // two origin points
    Origins = new List<GeoPosition>()
    {
        new GeoPosition(123.751, 45.9375),
        new GeoPosition(123.791, 45.96875)
    },
    // one destination point
    Destinations = new List<GeoPosition>() { new GeoPosition(123.767, 45.90625) },
};
Response<RouteMatrixResult> result = client.GetImmediateRouteMatrix(routeMatrixQuery);

Eine asynchrone Routenmatrixanforderung sieht wie unten aus. Dies ist nützlich, wenn Sie über Datenpunkte verfügen origin * destination > 100 .

// Instantiate route matrix query
RouteMatrixQuery routeMatrixQuery = new RouteMatrixQuery
{
    // two origin points
    Origins = new List<GeoPosition>()
    {
        new GeoPosition(123.751, 45.9375),
        new GeoPosition(123.791, 45.96875)
    },
    // one destination point
    Destinations = new List<GeoPosition>() { new GeoPosition(123.767, 45.90625) },
};

// Instantiate route matrix options
RouteMatrixOptions routeMatrixOptions = new RouteMatrixOptions(routeMatrixQuery)
{
    TravelTimeType = TravelTimeType.All,
};

// Invoke an long-running operation route matrix request and directly wait for completion
GetRouteMatrixOperation result = client.GetRouteMatrix(WaitUntil.Completed, routeMatrixOptions);

Ausführlichere Beispiele finden Sie auf der Seite Routenmatrixbeispiele .

Routenbereich

Die Routenbereichs-API hilft ihnen, eine Reihe von Standorten zu finden, die vom Ursprungspunkt aus erreicht werden können, basierend auf dem angegebenen Kraftstoff-, Energie-, Zeit- oder Entfernungsbudget. Eine Polygongrenze (oder Isochrone) wird in einer Ausrichtung gegen den Uhrzeigersinn sowie dem präzisen Polygonmittelpunkt zurückgegeben, der das Ergebnis des Ursprungspunkts war.

// Search from a point of time budget that can be reached in 2000 seconds
RouteRangeOptions options = new RouteRangeOptions(123.75, 46)
{
    TimeBudget = new TimeSpan(0, 20, 0)
};
Response<RouteRangeResult> result = client.GetRouteRange(options);

Ausführlichere Beispiele finden Sie auf der Seite routenbereichsbeispiele .

Problembehandlung

Allgemein

Wenn Sie mit dem Azure Maps-Diensten interagieren, entsprechen die vom Dienst zurückgegebenen Fehler den gleichen HTTP-status-Codes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise falsche Routingpunkte übergeben, wird ein Fehler zurückgegeben, der auf "Ungültige Anforderung" (HTTP 400) hinweist.

try
{
    // An empty route points list
    List<GeoPosition> routePoints = new List<GeoPosition>() { };
    RouteDirectionQuery query = new RouteDirectionQuery(routePoints);

    Response<RouteDirections> result = client.GetDirections(query);
    // Do something with result ...
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Nächste Schritte

Weitere Kontext- und zusätzliche Szenarien finden Sie unter : ausführliche Beispiele

Mitwirken

Weitere Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie im CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter <cla.microsoft.com>.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe

Freigeben über