Azure Maps bibliothèque cliente de routage pour .NET - version 1.0.0-beta.2

  • Article

Azure Maps Routage est une bibliothèque qui peut trouver un itinéraire vers un emplacement ou des points d’intérêt.

| Code sourceDocumentation de référence sur les | APIDocumentation | de référence sur l’API RESTDocumentation produit

Prise en main

Installer le package

Installez la bibliothèque cliente pour .NET avec NuGet :

dotnet add package Azure.Maps.Routing --prerelease

Prérequis

Vous devez disposer d’un abonnement Azure et d’un compte Azure Maps.

Pour créer un compte Azure Maps, vous pouvez utiliser le portail Azure, Azure PowerShell ou Azure CLI. Voici un exemple utilisant Azure CLI :

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

Authentifier le client

Il existe deux façons d’authentifier le client : l’authentification par clé partagée et Azure AD.

Authentification par clé partagée

  • Accédez à Azure Maps onglet Authentification du compte >
  • Copier Primary Key ou Secondary Key sous la section Authentification par clé partagée
// Create a MapsRoutingClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsRoutingClient client = new MapsRoutingClient(credential);

Authentification Azure AD

Pour interagir avec le service Azure Maps, vous devez créer un instance de la MapsRoutingClient classe. La bibliothèque Azure Identity facilite l’ajout de la prise en charge d’Azure Active Directory pour l’authentification des clients du Kit de développement logiciel (SDK) Azure auprès de leurs services Azure correspondants.

Pour utiliser l’authentification AAD, définissez les variables d’environnement comme décrit dans azure Identity README et créez un DefaultAzureCredential instance à utiliser avec .MapsRoutingClient

Nous avons également besoin d’un ID client Azure Maps qui se trouve dans la page > Azure Maps onglet Authentification > « ID client » dans la section Authentification Azure Active Directory.

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

Authentification par signature d’accès partagé (SAP)

Les jetons SAS (signature d’accès partagé) sont des jetons d’authentification créés à l’aide du format JWT (JSON Web Token). Ils sont signés par chiffrement pour prouver l’authentification d’une application auprès de l’API REST Azure Maps.

Avant d’intégrer l’authentification par jeton SAS, nous devons installer Azure.ResourceManager et Azure.ResourceManager.Maps (version 1.1.0-beta.2 ou version ultérieure) :

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

Dans le code, nous devons importer les lignes suivantes pour Azure Maps SDK et ResourceManager :

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;

Ensuite, nous pouvons obtenir un jeton SAS via l’API List Sas et l’affecter à MapsRoutingClient. Dans l’exemple de code suivant, nous récupérons une ressource de compte de mappage spécifique et créons un jeton SAP pour une heure d’expiration d’un jour lorsque le code est exécuté.

// Get your azure access token, for more details of how Azure SDK get your access token, please refer to https://video2.skills-academy.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);

Concepts clés

MapsRoutingClient a été conçu pour :

  • Communiquer avec Azure Maps point de terminaison pour obtenir l’itinéraire vers des emplacements ou des points d’intérêt
  • Communiquer avec Azure Maps point de terminaison pour calculer un ensemble d’emplacements qui peuvent être atteints à partir du point d’origine en fonction du carburant, de l’énergie, du temps ou du budget de distance spécifié
  • Communiquer avec Azure Maps point de terminaison pour calculer une matrice de résumés d’itinéraires pour un ensemble d’itinéraires définis par les emplacements d’origine et de destination

Pour en savoir plus, consultez nos exemples dans des exemples

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options clientes | Accès à la réponse | Opérations de longue durée | Gestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

Vous pouvez vous familiariser avec différentes API à l’aide de nos exemples.

Avant d’appeler les API de routage, instanciez une MapsRoutingClient première. Cet exemple utilise AAD pour créer le client instance :

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

Itinéraires

Voici un exemple simple de routage vers un emplacement :

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

Vous pouvez également spécifier le mode de voyage, le type d’itinéraire, la langue et d’autres options lors de l’acheminement vers un point d’intérêt :

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

Pour obtenir des exemples plus détaillés, consultez la page d’exemples d’itinéraires .

Matrice d’itinéraire

Pour rechercher la matrice de routage entre plusieurs origines et destinations, Azure Maps API de matrice de routage doivent répondre à vos besoins. Un exemple de demande de matrice de routage simple ressemble à l’extrait de code ci-dessous :

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

Une demande de matrice de routage asynchrone ressemble à celle ci-dessous. Cela est utile lorsque vous avez des points de origin * destination > 100 données.

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

Pour obtenir des exemples plus détaillés, consultez la page d’exemples de matrice de routage .

Zone d’itinéraire

L’API de plage d’itinéraires permet de trouver un ensemble d’emplacements qui peuvent être atteints à partir du point d’origine en fonction du carburant, de l’énergie, du temps ou du budget de distance spécifié. Une limite de polygone (ou Isochrone) est retournée dans une orientation dans le sens inverse des aiguilles d’une montre, ainsi que dans le centre de polygone précis qui a été le résultat du point d’origine.

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

Pour obtenir des exemples plus détaillés, consultez la page exemples de plages de routes .

Dépannage

Général

Lorsque vous interagissez avec les services Azure Maps, les erreurs retournées par le service correspondent aux mêmes codes status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous passez des points de routage incorrects, une erreur est retournée, indiquant « Requête incorrecte » (HTTP 400).

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

Étapes suivantes

Contribution

Consultez le CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez <cla.microsoft.com>.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions