Azure Maps bibliothèque de client de géolocalisation pour .NET - version 1.0.0-beta.2

Article
07/20/2023

Azure Maps géolocalisation est une bibliothèque qui peut trouver la géolocalisation à un emplacement ou à des points d’intérêt.

| Code source Documentation de référence sur les | APIDocumentation | de référence sur l’API REST Documentation produit

Prise en main

Installer le package

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

dotnet add package Azure.Maps.Geolocation --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 2 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 MapsGeolocationClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsGeolocationClient client = new MapsGeolocationClient(credential);

Authentification Azure AD

Pour interagir avec le service Azure Maps, vous devez créer une instance de la MapsGeolocationClient classe . La bibliothèque d’identités Azure 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 le fichier README d’identité Azure et créez un DefaultAzureCredential instance à utiliser avec .MapsRouteClient

Nous avons également besoin Azure Maps’ID client qui peut être obtenu à partir de Azure Maps page > Onglet Authentification > « ID client » dans la section Authentification Azure Active Directory.

// Create a MapsGeolocationClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsGeolocationClient client = new MapsGeolocationClient(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 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 ResourceManager :

using Azure.Maps.Geolocation;
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 Sas de liste et l’affecter à MapsGeolocationClient. Dans l’exemple de code suivant, nous récupérons une ressource de compte de mappages spécifique et créons un jeton SAS pour une durée 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://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);
MapsGeolocationClient client = new MapsGeolocationClient(sasCredential);

Concepts clés

MapsGeolocationClient est conçu pour :

Communiquer avec Azure Maps point de terminaison du SDK de géolocalisation pour obtenir l’emplacement à partir d’une adresse IP donnée

En savoir plus sur les exemples dans les exemples

Sécurité des threads

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

Concepts supplémentaires

Exemples

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

Avant d’appeler des API de géolocalisation, instanciez une MapsGeolocationClient première. L’exemple ci-dessous utilise AAD pour créer le client instance :

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

Obtenir l’emplacement

Ce service retourne le code de pays ISO pour l’adresse IP fournie. Les développeurs peuvent utiliser ces informations pour bloquer ou modifier certains contenus en fonction des emplacements géographiques à partir desquels l’application est consultée.

//Get location by given IP address
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");
Response<CountryRegionResult> result = client.GetCountryCode(ipAddress);

//Get location result country code
Console.WriteLine($"Country code results by given IP Address: {result.Value.IsoCode}");

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

Dépannage

Général

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

Par exemple, si vous transmettez une adresse IP incorrecte, une erreur est retournée, indiquant « Demande incorrecte » (code d’état HTTP : 400).

try
{
    // An invalid IP address
    IPAddress inValidIpAddress = IPAddress.Parse("2001:4898:80e8:b:123123213123");

    Response<CountryRegionResult> result = client.GetCountryCode(inValidIpAddress);
    // Do something with result ...
}
catch (FormatException e)
{
    Console.WriteLine(e.ToString());
}

Étapes suivantes

Pour plus de contexte et d’autres scénarios, consultez : Exemples plus détaillés

Contribution

Consultez la 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, visitez <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

Partager via