Guide du développeur sur le SDK REST C#

Le SDK C# Azure Maps prend en charge les fonctionnalités disponibles dans l’API REST Azure Maps, comme la recherche d’une adresse, le routage entre différentes coordonnées et l’obtention de l’emplacement géographique d’une adresse IP spécifique. Cet article présente le kit SDK REST C# à l'aide d'exemples pour vous aider à commencer à créer des applications de géolocalisation en C# qui intègrent la puissance d'Azure Maps.

Prérequis

• Compte Azure Maps.
• Clé d’abonnement ou autre forme d’authentification avec Azure Maps.
• .NET Standard, version 2.0 ou ultérieure.

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

Créer un projet .NET

L’extrait de code PowerShell suivant montre comment utiliser PowerShell pour créer un programme de console MapsDemo avec .NET 7.0. Pour le framework, vous pouvez utiliser n’importe quelle version compatible avec .NET 2.0.

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

Installer les packages nécessaires

Pour utiliser le SDK C# Azure Maps, vous devez installer les packages nécessaires. Chacun des services Azure Maps, y compris la recherche, le routage, le rendu et la géolocalisation, se trouve dans son propre package. Étant donné que le SDK C# Azure Maps est en préversion publique, vous devez ajouter l’indicateur --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

Services Azure Maps

Créer et authentifier un objet MapsSearchClient

L’objet client utilisé pour accéder aux API de recherche Azure Maps nécessite soit un objet AzureKeyCredential pour s’authentifier en cas d’utilisation d’une clé d’abonnement Azure Maps, soit un objet TokenCredential avec l’ID client Azure Maps en cas d’authentification à l’aide de Microsoft Entra ID. Pour plus d’informations sur l’authentification, consultez Authentification avec Azure Maps.

Utilisation des informations d'identification Microsoft Entra

Vous pouvez vous authentifier auprès de Microsoft Entra ID à l’aide de la bibliothèque Azure Identity. Pour utiliser le fournisseur DefaultAzureCredential, vous devez installer la bibliothèque cliente Azure Identity pour .NET :

dotnet add package Azure.Identity 

Vous devez inscrire la nouvelle application Microsoft Entra et accorder l’accès à Azure Maps en attribuant le rôle nécessaire à votre principal de service. Pour plus d’informations, consultez Héberger un démon sur des ressources non-Azure. L’ID d’application (client), un ID de répertoire (locataire) et une clé secrète client sont retournés. Copiez ces valeurs et stockez-les dans un endroit sécurisé. Vous en aurez besoin dans les étapes qui suivent.

Définissez les valeurs de l’ID d’application (client), de l’ID de répertoire (tenant) et de la clé secrète client de votre application Microsoft Entra, ainsi que l’ID client de la ressource de carte en tant que variables d’environnement :

Vous pouvez maintenant créer des variables d’environnement dans PowerShell pour stocker ces valeurs :

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

Après avoir configuré les variables d'environnement, vous pouvez les utiliser dans votre programme pour instancier le client 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); 

Utilisation d’informations d’identification de clé d’abonnement

Vous pouvez vous authentifier avec votre clé d’abonnement Azure Maps. Votre clé d’abonnement se trouve dans la section Authentification du compte Azure Maps, comme illustré dans la capture d’écran suivante :

Vous pouvez maintenant créer des variables d’environnement dans PowerShell pour stocker la clé d’abonnement :

$Env:SUBSCRIPTION_KEY="your subscription key"

Une fois votre variable d’environnement créée, vous pouvez y accéder dans votre code :

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

Géocoder une adresse

Appelez la méthode GetGeocoding pour obtenir les coordonnées d’une adresse.

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

Géocoder des adresses par lots

Cet exemple montre comment effectuer une recherche d’adresses par lots.

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

Géocodage inverse d’une coordonnée

Vous pouvez traduire les coordonnées en adresses lisibles. Ce processus est également appelé géocodage inverse.

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

Géocoder inverse par lots un ensemble de coordonnées

La Recherche Azure Maps fournit également des méthodes de requête par lots. L’API Batch de géocodage inverse envoie des lots de requêtes à l’API Géocodage inverse à l’aide d’un seul appel d’API. L’API permet à l’appelant de traiter jusqu’à 100 requêtes.

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

Obtenir des polygones pour une localisation donnée

Cet exemple montre comment rechercher dans des polygones.

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

Utilisation des kits SDK V1 pour Search et Render

Pour plus d’informations sur l’utilisation de La recherche v1, consultez Bibliothèque de client Recherche Azure Maps pour .NET. Pour plus d’informations sur l’utilisation de Render v1, consultez Bibliothèque de client De rendu Azure Maps pour .NET.

Informations supplémentaires

Espace de noms Azure.Maps dans la documentation .NET.