Azure Maps Bibliothèque cliente render pour .NET - version 1.0.0-beta.2

Article
07/20/2023

Azure Maps Render est une bibliothèque qui peut extraire des vignettes d’image et des informations de copyright.

| 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.Rendering --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 MapsRenderingClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsRenderingClient client = new MapsRenderingClient(credential);

Authentification Azure AD

Pour interagir avec le service Azure Maps, vous devez créer une instance de la MapsRenderingClient 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, les variables d’environnement, comme décrit dans le fichier README d’identité Azure, créent un DefaultAzureCredential instance à utiliser avec .MapsRenderingClient

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.

Site web du portail Azure Maps

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

using Azure.Maps.Rendering;

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 à MapsRenderingClient. 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);
MapsRenderingClient client = new MapsRenderingClient(sasCredential);

Concepts clés

MapsRenderingClient est conçu pour :

Communiquer avec Azure Maps point de terminaison pour obtenir des images et des vignettes
Communiquer avec Azure Maps point de terminaison pour obtenir des droits d’auteur pour les images et les vignettes

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. Le rendu des vignettes de carte nécessite des connaissances sur les niveaux de zoom et le système de grille de vignette. Pour plus d’informations, consultez la documentation .

Obtenir des vignettes d’images

Voici un exemple simple de rendu de vignettes d’images :

int zoom = 10, tileSize = 256;

// Get tile X, Y index by coordinate, zoom and tile size information
MapTileIndex tileIndex = MapsRenderingClient.PositionToTileXY(new GeoPosition(13.3854, 52.517), zoom, tileSize);

// Fetch imagery map tiles
GetMapTileOptions GetMapTileOptions = new GetMapTileOptions(
    MapTileSetId.MicrosoftImagery,
    new MapTileIndex(tileIndex.X, tileIndex.Y, zoom)
);
Response<Stream> mapTile = client.GetMapTile(GetMapTileOptions);

// Prepare a file stream to save the imagery
using (FileStream fileStream = File.Create(".\\BerlinImagery.png"))
{
    mapTile.Value.CopyTo(fileStream);
}

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 de status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous essayez d’obtenir une vignette d’imagerie avec un index de vignette incorrect, une erreur est retournée, indiquant « Requête incorrecte » (HTTP 400).

try
{
    var options = new GetMapTileOptions(
        MapTileSetId.MicrosoftBaseHybrid,
        new MapTileIndex(12, 12, 2)
    );

    Response<Stream> imageryTile = client.GetMapTile(options);
    using var imageryStream = new MemoryStream();
    imageryTile.Value.CopyTo(imageryStream);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Étapes suivantes

Pour plus de contexte et d’autres scénarios, consultez : exemples 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