Partage via

Démarrage rapide : Bibliothèque de client Stockage Blob Azure pour .NET

  • Article

Remarque

L’option Générer à partir de zéro vous guide pas à pas dans le processus de création d’un projet, d’installation de packages, d’écriture du code et d’exécution d’une application console de base. Cette approche est recommandée si vous souhaitez comprendre tous les détails impliqués dans la création d’une application qui se connecte au service Stockage Blob Azure. Si vous préférez automatiser les tâches de déploiement et commencer par un projet terminé, choisissez Commencer avec un modèle.

Remarque

L’option Commencer avec un modèle utilise Azure Developer CLI pour automatiser les tâches de déploiement et commencer par un projet terminé. Cette approche est recommandée si vous souhaitez explorer le code le plus rapidement possible sans passer par les tâches de configuration. Si vous préférez suivre des instructions pas à pas pour générer l’application, choisissez Générer à partir de zéro.

Commencez à utiliser la bibliothèque cliente Stockage Blob Azure pour .NET. Stockage Blob Azure est la solution de stockage d’objets de Microsoft pour le cloud, optimisée pour stocker de grandes quantités de données non structurées.

Dans cet article, vous suivez les étapes pour installer le package et essayer l’exemple de code pour les tâches de base.

Dans cet article, vous utilisez Azure Developer CLI pour déployer des ressources Azure et exécuter une application console terminée en quelques commandes seulement.

Documentation de référence sur l’API | Code source de la bibliothèque | Package (NuGet) | Exemples

Cette vidéo vous montre comment commencer à utiliser la bibliothèque cliente Stockage Blob Azure pour .NET.

Les étapes de la vidéo sont également décrites dans les sections suivantes.

Prérequis

Configuration

Cette section vous guide tout au long de la préparation d’un projet à utiliser avec la bibliothèque cliente Stockage Blob Azure pour .NET.

Créer le projet

Créez une application console .NET à l’aide de l’interface CLI .NET ou de Visual Studio 2022.

  1. En haut de Visual Studio, accédez à Fichier>Nouveau>Projet..

  2. Dans la fenêtre de boîte de dialogue, entrez application console dans la zone de recherche du modèle de projet et sélectionnez le premier résultat. Choisissez Suivant en bas de la boîte de dialogue.

    Capture d’écran montrant comment créer un nouveau projet à l’aide de Visual Studio.

  3. Pour le nom du projet, entrez BlobQuickstart. Conservez les valeurs par défaut pour le reste des champs, puis sélectionnez Suivant.

  4. Pour le Framework, vérifiez que la dernière version installée de .NET est sélectionnée. Choisissez ensuite Créer. Le nouveau projet s’ouvre dans l’environnement Visual Studio.

Installer le package

Pour interagir avec Stockage Blob Azure, installez la bibliothèque cliente Stockage Blob Azure pour .NET.

  1. Dans Explorateur de solutions, cliquez avec le bouton droit sur le nœud Dépendances de votre projet. Sélectionnez Gérer les packages NuGet.

  2. Dans la fenêtre résultante, recherchez Azure.Storage.Blobs. Sélectionnez le résultat approprié, puis sélectionnez Installer.

    Capture d’écran montrant comment ajouter un nouveau packagr à l’aide de Visual Studio.

Configurer le code d’application

Remplacez le code de départ dans le fichier Program.cs afin qu’il corresponde à l’exemple suivant, qui inclut les instructions using nécessaires pour cet exercice.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Avec Azure Developer CLI installé, vous pouvez créer un compte de stockage et exécuter l’exemple de code en quelques commandes seulement. Vous pouvez exécuter le projet dans votre environnement de développement local ou dans un DevContainer.

Initialiser le modèle Azure Developer CLI et déployer des ressources

À partir d’un répertoire vide, procédez comme suit pour initialiser le modèle azd, approvisionner des ressources Azure et commencer à utiliser le code :

  • Clonez les ressources du référentiel de démarrage rapide à partir de GitHub et initialisez le modèle localement :

    azd init --template blob-storage-quickstart-dotnet

    Les informations suivantes vous sont demandées :

    • Nom de l’environnement : cette valeur est utilisée comme préfixe pour toutes les ressources Azure créées par Azure Developer CLI. Le nom doit être unique dans l’ensemble des abonnements Azure et il doit contenir entre 3 et 24 caractères. Le nom peut contenir uniquement des chiffres et des lettres minuscules.

  • Connexion à Azure :

    azd auth login

  • Approvisionnez et déployez les ressources sur Azure :

    azd up

    Les informations suivantes vous sont demandées :

    • Abonnement : abonnement Azure sur lequel vos ressources sont déployées.
    • Emplacement : région Azure où vos ressources sont déployées.

    Le déploiement peut prendre quelques minutes. La sortie de la commande azd up inclut le nom du compte de stockage nouvellement créé, dont vous aurez besoin ultérieurement pour exécuter le code.

Exécuter l’exemple de code

À ce stade, les ressources sont déployées sur Azure et le projet est prêt à être exécuté. Pour mettre à jour le nom du compte de stockage dans le code et exécuter l’exemple d’application console, procédez comme suit :

  • Mettez à jour le nom du compte de stockage : accédez au répertoire src et modifiez Program.cs. Recherchez l’espace réservé <storage-account-name> et remplacez-le par le nom réel du compte de stockage créé par la commande azd up. Enregistrez les modifications.
  • Exécutez le projet : si vous utilisez Visual Studio, appuyez sur F5 pour générer et exécuter le code et interagir avec l’application console. Si vous utilisez l’interface CLI .NET, accédez au répertoire de votre application, générez le projet en utilisant dotnet build, puis exécutez l’application avec dotnet run.
  • Observez la sortie : cette application crée un fichier de test dans votre dossier local data et le charge dans un conteneur du compte de stockage. L’exemple liste ensuite les objets blob du conteneur et télécharge le fichier avec un nouveau nom pour que vous puissiez comparer les deux fichiers.

Pour en savoir plus sur le fonctionnement de l’exemple de code, consultez la section Exemples de code.

Une fois que vous avez terminé de tester le code, consultez la section Nettoyer les ressources pour supprimer les ressources créées par la commande azd up.

Modèle objet

Stockage Blob Azure est optimisé pour stocker des quantités massives de données non structurées. Les données non structurées n’obéissent pas à un modèle ou une définition de données en particulier, comme des données texte ou binaires. Le stockage Blob offre trois types de ressources :

  • Le compte de stockage
  • Un conteneur dans le compte de stockage.
  • Un blob dans le conteneur

Le diagramme suivant montre la relation entre ces ressources.

Diagramme de l’architecture de Stockage Blob

Utilisez les classes .NET suivantes pour interagir avec ces ressources :

  • BlobServiceClient: La classe BlobServiceClient vous permet de manipuler les ressources de stockage Azure et les conteneurs blob.
  • BlobContainerClient : La classe BlobContainerClient vous permet de manipuler des conteneurs de stockage Azure et leurs blobs.
  • BlobClient : La classe BlobClient vous permet de manipuler des blobs de stockage Azure.

Exemples de code

Les exemples d’extraits de code présentés dans les sections suivantes vous montrent comment effectuer les tâches suivantes sur les données avec la bibliothèque de client Stockage Blob Azure pour .NET :

Important

Vérifiez que vous avez installé les packages NuGet corrects et ajouté les instructions d’utilisation nécessaires pour que les exemples de code fonctionnent, comme décrit dans la section configuration.

Remarque

Le modèle Azure Developer CLI inclut un projet contenant déjà un exemple de code. Les exemples suivants fournissent des détails pour chaque partie de l’exemple de code. Le modèle implémente la méthode d’authentification sans mot de passe recommandée, comme décrit dans la section S’authentifier auprès d’Azure. La méthode de chaîne de connexion est présentée comme une alternative, mais elle n’est pas utilisée dans le modèle et n’est pas recommandée pour le code de production.

S’authentifier auprès d’Azure et autoriser l’accès aux données blob

Les demandes d’application vers le Stockage Blob Azure doivent être autorisées. L’utilisation de la classe DefaultAzureCredential fournie par la bibliothèque de client Azure Identity est l’approche recommandée pour implémenter des connexions sans mot de passe aux services Azure dans votre code, y compris le Stockage Blob.

Vous pouvez également autoriser les demandes vers le Stockage Blob Azure à l’aide de la clé d’accès au compte. Toutefois, cette approche doit être utilisée avec prudence. Les développeurs doivent être vigilants pour ne jamais exposer la clé d’accès dans un emplacement non sécurisé. Toute personne disposant de la clé d’accès est en mesure d’autoriser les demandes sur le compte de stockage et a accès efficacement à toutes les données. DefaultAzureCredential offre des avantages améliorés en matière de gestion et de sécurité par rapport à la clé de compte pour autoriser l’authentification sans mot de passe. Les deux options sont illustrées dans l’exemple suivant.

DefaultAzureCredential est une classe fournie par la bibliothèque de client Azure Identity pour .NET. Pour en savoir plus, consultez la vue d’ensemble de DefaultAzureCredential. DefaultAzureCredential prend en charge plusieurs méthodes d’authentification et détermine quelle méthode doit être utilisée au moment de l’exécution. Cette approche permet à votre application d’utiliser différentes méthodes d’authentification dans différents environnements (local ou production) sans implémenter de code spécifique à l’environnement.

L’ordre et les emplacements dans lesquels DefaultAzureCredential les informations d’identification sont disponibles dans la vue d’ensemble de la bibliothèque d’identités Azure.

Par exemple, votre application peut s’authentifier à l’aide de vos informations d’identification de connexion Visual Studio lors du développement local. Votre application peut ensuite utiliser une identité managée une fois qu’elle a été déployée sur Azure. Aucune modification du code n’est requise pour cette transition.

Attribuer des rôles à votre compte d’utilisateur Microsoft Entra

Lors du développement local, assurez-vous que le compte d’utilisateur qui accède aux données blob dispose des autorisations appropriées. Vous aurez besoin du Contributeur aux données Blob de stockage pour lire et écrire des données blob. Pour vous attribuer ce rôle, vous aurez besoin du rôle Administrateur de l’accès utilisateur ou d’un autre rôle qui inclut l’action Microsoft.Authorization/roleAssignments/write. Vous pouvez attribuer des rôles RBAC Azure à un utilisateur à l’aide du Portail Azure, Azure CLI ou Azure PowerShell. Vous pouvez en savoir plus sur les étendues disponibles pour les attributions de rôles dans la page vue d’ensemble de l’étendue .

Dans ce scénario, vous allez attribuer des autorisations à votre compte d’utilisateur, étendues au compte de stockage, pour suivre le Principe des privilèges minimum. Cette pratique offre aux utilisateurs uniquement les autorisations minimales nécessaires et crée des environnements de production plus sécurisés.

L’exemple suivant affecte le rôle Contributeur aux données Blob du stockage à votre compte d’utilisateur, qui fournit à la fois un accès en lecture et en écriture aux données d’objet blob dans votre compte de stockage.

Important

Dans la plupart des cas, la propagation de l’attribution de rôle dans Azure peut prendre une ou deux minutes, mais dans de rares cas, cela peut prendre jusqu’à huit minutes. Si vous recevez des erreurs d’authentification lorsque vous exécutez votre code pour la première fois, patientez quelques instants et réessayez.

  1. Dans le Portail Azure, recherchez votre compte de stockage à l’aide de la barre de recherche principale ou de la navigation gauche.

  2. Dans la page vue d’ensemble du compte de stockage, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.

  3. Sur la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôles.

  4. Sélectionnez + Ajouter dans le menu supérieur, puis Ajouter une attribution de rôle dans le menu déroulant résultant.

    Capture d’écran montrant comment attribuer un rôle.

  5. Utilisez la zone de recherche pour filtrer les résultats sur le rôle souhaité. Pour cet exemple, recherchez Contributeur aux données Blob du stockage, sélectionnez le résultat correspondant, puis choisissez Suivant.

  6. Sous Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal de service, puis sélectionnez + Sélectionner des membres.

  7. Dans la boîte de dialogue, recherchez votre nom d’utilisateur Microsoft Entra (généralement votre adresse e-mail utilisateur@domaine), puis choisissez Sélectionner en bas de la boîte de dialogue.

  8. Sélectionnez Vérifier + affecter pour accéder à la page finale, puis Vérifier + attribuer à nouveau pour terminer le processus.

Se connecter et connecter le code d’application à Azure à l’aide de DefaultAzureCredential

Vous pouvez autoriser l’accès aux données dans votre compte de stockage en procédant comme suit :

  1. Pour le développement local, vérifiez que vous êtes authentifié avec le même compte Microsoft Entra auquel vous avez attribué le rôle. Vous pouvez vous authentifier au moyen d’outils de développement populaires, comme Azure CLI ou Azure PowerShell. Les outils de développement avec lesquels vous pouvez vous authentifier dépendent de la langue.

    Connectez-vous à Azure via Azure CLI à l’aide de la commande suivante :

    az login

  2. Pour utiliser DefaultAzureCredential, ajoutez le package Azure.Identity à votre application.

    1. Dans Explorateur de solutions, cliquez avec le bouton droit sur le nœud Dépendances de votre projet. Sélectionnez Gérer les packages NuGet.

    2. Dans la fenêtre résultante, recherchez Azure.Identity. Sélectionnez le résultat approprié, puis sélectionnez Installer.

      Capture d’écran montrant comment ajouter un package d’identité.

  3. Mettez à jour votre code Program.cs pour le faire correspondre à l’exemple suivant : Lorsque le code est exécuté sur votre station de travail locale pendant le développement, il utilise les informations d’identification du développeur de l’outil hiérarchisé auquel vous êtes connecté pour vous authentifier auprès d’Azure, comme Azure CLI ou Visual Studio.

    using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

  4. Veillez à mettre à jour le nom du compte de stockage dans l’URI de votre BlobServiceClient. Le nom du compte de stockage se trouve sur la page vue d’ensemble du Portail Azure.

    Capture d’écran montrant comment trouver le nom du compte de stockage.

    Notes

    Lorsqu’il est déployé sur Azure, ce même code peut être utilisé pour autoriser les demandes adressées à Stockage Azure à partir d’une application s’exécutant dans Azure. Toutefois, vous devez activer l’identité managée sur votre application dans Azure. Configurez ensuite votre compte de stockage pour autoriser cette identité managée à se connecter. Pour obtenir des instructions détaillées sur la configuration de cette connexion entre les services Azure, consultez le didacticiel d’authentification à partir d’applications hébergées sur Azure .

Créez un conteneur.

Créez un nouveau conteneur dans votre compte de stockage en appelant la méthode CreateBlobContainerAsync sur l’objet blobServiceClient. Dans cet exemple, le code ajoute une valeur GUID au nom du conteneur pour s’assurer qu’il est unique.

Ajoutez le code suivant à la fin du fichier Program.cs :

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Pour en savoir plus sur la création d’un conteneur et explorer d’autres exemples de code, consultez Créer un conteneur d’objets blob avec .NET.

Important

Les noms de conteneurs doivent être en minuscules. Pour plus d’informations sur l’affectation de noms aux conteneurs et objets blob, consultez Affectation de noms et références aux conteneurs, objets blob et métadonnées.

Charger un objet blob dans un conteneur

Charger un objet blob dans un conteneur en utilisant UploadAsync. L’exemple de code crée un fichier texte dans le répertoire de données local à charger dans le conteneur.

Ajoutez le code suivant à la fin du fichier Program.cs :

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

Pour en savoir plus sur le chargement d’objets blob et explorer d’autres exemples de code, consultez Charger un objet blob avec ,NET.

Lister les objets blob d’un conteneur

Répertoriez les objets Blob dans le conteneur en appelant la méthode GetBlobsAsync.

Ajoutez le code suivant à la fin du fichier Program.cs :

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Pour en savoir plus sur les listings d’objets blob et explorer d’autres exemples de code, consultez Répertorier les objets blob avec .NET.

Télécharger un objet blob

Téléchargez l’objet blob que nous avons créé précédemment en appelant la méthode DownloadToAsync. L’exemple de code ajoute la chaîne « DOWNLOADED » au nom de fichier afin que vous puissiez voir les deux fichiers dans votre système de fichiers local.

Ajoutez le code suivant à la fin du fichier Program.cs :

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Pour en savoir plus sur le téléchargement d’objets blob et explorer d’autres exemples de code, consultez Télécharger un objet blob avec .NET.

Supprimer un conteneur

Le code suivant nettoie les ressources créées par l’application en supprimant le conteneur en utilisant DeleteAsync. L’exemple de code supprime également les fichiers locaux créés par l’application.

L’application s’interrompt pour une entrée de l’utilisateur en appelant Console.ReadLine avant de supprimer l’objet blob, le conteneur et les fichiers locaux. C’est l’occasion de vérifier que les ressources ont été créées correctement, avant d’être supprimées.

Ajoutez le code suivant à la fin du fichier Program.cs :

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Pour en savoir plus sur la suppression d’un conteneur et explorer d’autres exemples de code, consultez Supprimer et restaurer un conteneur d’objets blob avec .NET.

Code terminé

Une fois ces étapes effectuées, le code de votre fichier Program.cs doit maintenant ressembler à ce qui suit :

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Exécuter le code

Cette application crée un fichier de test dans votre dossier local data et le charge sur Stockage Blob. L’exemple liste ensuite les objets blob du conteneur et télécharge le fichier avec un nouveau nom pour que vous puissiez comparer les deux fichiers.

Si vous utilisez Visual Studio, appuyez sur F5 pour générer et exécuter le code et interagir avec l’application console. Si vous utilisez l’interface CLI .NET, accédez à votre répertoire d’application, puis générez et exécutez l’application.

dotnet build

dotnet run

La sortie de l’application est similaire à l’exemple suivant (valeurs GUID omises pour une meilleure lisibilité) :

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Avant de commencer le processus de nettoyage, vérifiez la présence des deux fichiers dans votre dossier data. Vous pouvez les ouvrir et constater qu’ils sont identiques.

Nettoyer les ressources

Après avoir vérifié les fichiers et terminé le test, appuyez sur la touche Entrée pour supprimer les fichiers de test avec le conteneur que vous avez créé dans le compte de stockage. Vous pouvez également utiliser Azure CLI pour supprimer des ressources.

Lorsque vous avez terminé avec le démarrage rapide, vous pouvez nettoyer les ressources créées en exécutant la commande suivante :

azd down

Il vous sera demandé de confirmer la suppression des ressources. Entrez y pour confirmer.

Étape suivante

Exemples Stockage Azure et guides de développement pour .NET