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

  • Article
  • 19 minutes de lecture

Commencez à utiliser la bibliothèque cliente Stockage Blob Azure pour .NET. Le Stockage Blob Azure est la solution de stockage d’objets de Microsoft pour le cloud. Suivez les étapes suivantes pour installer le package et essayer un exemple de code pour les tâches de base. Le stockage Blob est optimisé pour stocker de grandes quantités de données non structurées.

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

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

Pour les étapes à suivre, vous devez créer 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 l’Infrastructure, vérifiez que .NET 6.0 est sélectionné. 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!");

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 Azure AD

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 Azure AD (généralement votre adresse e-mail user@domain ), 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.

Connectez-vous et connectez votre 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. Vérifiez que vous êtes authentifié avec le même compte Azure AD auquel vous avez attribué le rôle. Vous pouvez vous authentifier via Azure CLI, Visual Studio ou Azure PowerShell.

    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 .

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 des opérations de base 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.

  • Azure.Identity (si vous utilisez l’approche sans mot de passe)
  • Azure.Storage.Blobs

Créez un conteneur.

Choisissez un nom pour le nouveau conteneur. Le code ci-dessous ajoute une valeur GUID au nom du conteneur pour s’assurer qu’il est unique.

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.

Vous pouvez appeler la méthode CreateBlobContainerAsync pour blobServiceClient créer un conteneur dans votre compte de stockage.

Ajoutez ce code à la fin de la classe 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.

Charger un objet blob dans un conteneur

Ajoutez le code suivant à la fin de la classe 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
await blobClient.UploadAsync(localFilePath, true);

L’extrait de code effectue les étapes suivantes :

  1. Crée un fichier texte dans le répertoire data local.
  2. Obtient une référence à un objet BlobClient en appelant la méthode GetBlobClient sur le conteneur à partir de la section Créer un conteneur.
  3. Charge le fichier texte local dans l’objet Blob en appelant la méthode UploadAsync. Cette méthode crée l’objet blob s’il n’existe pas déjà, et le remplace s’il existe.

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. Dans ce cas, un seul objet blob a été ajouté au conteneur. Il n’y a donc qu’un objet blob répertorié.

Ajoutez le code suivant à la fin de la classe 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 créé précédemment en appelant la méthode DownloadToAsync. L’exemple de code ajoute le suffixe « 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 de la classe 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 l’ensemble du conteneur avec DeleteAsync. Il 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 bien été créées avant d’être supprimées.

Ajoutez le code suivant à la fin de la classe 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 ressemble à l’exemple suivant :

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.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.

Une fois les fichiers vérifiés, appuyez sur Entrée pour supprimer les fichiers de test et terminer la démonstration.

Étapes suivantes

Dans ce démarrage rapide, vous avez appris à charger, télécharger et répertorier des objets blob avec .NET.

Pour afficher des exemples d’applications de stockage blob, passez à :

Exemples de bibliothèque Stockage Blob Azure pour .NET