Démarrage rapide : Bibliothèque de client Stockage Blob Azure v11 pour .NETQuickstart: Azure Blob storage client library v11 for .NET

Familiarisez-vous avec la bibliothèque de client Stockage Blob Azure v11 pour .NET.Get started with the Azure Blob Storage client library v11 for .NET. Le Stockage Blob Azure est la solution de stockage d’objets de Microsoft pour le cloud.Azure Blob Storage is Microsoft's object storage solution for the cloud. Suivez les étapes pour installer le package et essayer l’exemple de code pour les tâches de base.Follow steps to install the package and try out example code for basic tasks. Le stockage Blob est optimisé pour stocker de grandes quantités de données non structurées.Blob storage is optimized for storing massive amounts of unstructured data.

Utilisez la bibliothèque cliente Stockage Blob Azure pour .NET afin de :Use the Azure Blob Storage client library for .NET to:

  • Créez un conteneur.Create a container
  • Définir des autorisations sur un conteneurSet permissions on a container
  • Créer un objet blob dans le stockage AzureCreate a blob in Azure Storage
  • Télécharger l’objet blob sur votre ordinateur localDownload the blob to your local computer
  • Lister tous les objets blob d’un conteneurList all of the blobs in a container
  • Supprimer un conteneurDelete a container

Documentation de référence sur l’API | Code source de la bibliothèque | Package (NuGet) | ExemplesAPI reference documentation | Library source code | Package (NuGet) | Samples

Notes

Les fonctionnalités décrites dans cet article sont désormais disponibles pour les comptes dotés d'un espace de noms hiérarchique.The features described in this article are now available to accounts that have a hierarchical namespace. Pour en savoir plus sur les limitations, consultez l'article Problèmes connus avec Azure Data Lake Storage Gen2.To review limitations, see the Known issues with Azure Data Lake Storage Gen2 article.

PrérequisPrerequisites

ConfigurationSetting up

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.This section walks you through preparing a project to work with the Azure Blob Storage client library for .NET.

Créer le projetCreate the project

Commencez par créer une application .NET Core nommée blob-quickstart.First, create a .NET Core application named blob-quickstart.

  1. Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez la commande dotnet new pour créer une application de console avec le nom blob-quickstart.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name blob-quickstart. Cette commande crée un projet C# « Hello World » simple avec un seul fichier source : Program.cs.This command creates a simple "Hello World" C# project with a single source file: Program.cs.

    dotnet new console -n blob-quickstart
    
  2. Passez au dossier blob-quickstart nouvellement créé et générez l’application pour vérifier que tout va bien.Switch to the newly created blob-quickstart folder and build the app to verify that all is well.

    cd blob-quickstart
    
    dotnet build
    

La sortie attendue de la build doit ressembler à ceci :The expected output from the build should look something like this:

C:\QuickStarts\blob-quickstart> dotnet build
Microsoft (R) Build Engine version 16.0.450+ga8dc7f1d34 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 44.31 ms for C:\QuickStarts\blob-quickstart\blob-quickstart.csproj.
  blob-quickstart -> C:\QuickStarts\blob-quickstart\bin\Debug\netcoreapp2.1\blob-quickstart.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:03.08

Installer le packageInstall the package

Alors que vous êtes toujours dans le répertoire de l’application, installez le package de la bibliothèque cliente Stockage Blob Azure pour .NET à l’aide de la commande dotnet add package.While still in the application directory, install the Azure Blob Storage client library for .NET package by using the dotnet add package command.

dotnet add package Microsoft.Azure.Storage.Blob

Configurer le framework d’applicationSet up the app framework

À partir du répertoire de projet :From the project directory:

  1. Ouvrez le fichier Program.cs dans votre éditeur.Open the Program.cs file in your editor
  2. Supprimez l'instruction Console.WriteLine.Remove the Console.WriteLine statement
  3. Ajoutez des directives using.Add using directives
  4. Créez une méthode ProcessAsync dans laquelle résidera le code principal pour l’exemple.Create a ProcessAsync method where the main code for the example will reside
  5. Appeler la méthode ProcessAsync de façon asynchrone à partir de Main.Asynchronously call the ProcessAsync method from Main

Voici le code :Here's the code:

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Azure.Storage;
using Microsoft.Azure.Storage.Blob;

namespace blob_quickstart
{
    class Program
    {
        public static void Main()
        {
            Console.WriteLine("Azure Blob Storage - .NET quickstart sample\n");

            // Run the examples asynchronously, wait for the results before proceeding
            ProcessAsync().GetAwaiter().GetResult();

            Console.WriteLine("Press any key to exit the sample application.");
            Console.ReadLine();
        }

        private static async Task ProcessAsync()
        {
        }
    }
}

Copier vos informations d’identification depuis le portail AzureCopy your credentials from the Azure portal

Lorsque l’exemple d’application effectue une requête auprès du stockage Azure, il doit être autorisé.When the sample application makes a request to Azure Storage, it must be authorized. Pour autoriser une demande, ajoutez les informations d’identification de votre compte de stockage à l’application sous la forme d’une chaîne de connexion.To authorize a request, add your storage account credentials to the application as a connection string. Affichez les informations d'identification de votre compte de stockage en suivant ces étapes :View your storage account credentials by following these steps:

  1. Accédez au portail Azure.Navigate to the Azure portal.

  2. Recherchez votre compte de stockage.Locate your storage account.

  3. Dans la section Paramètres de la présentation du compte de stockage, sélectionnez Clés d’accès.In the Settings section of the storage account overview, select Access keys. Vos clés d’accès au compte s’affichent, ainsi que la chaîne de connexion complète de chaque clé.Here, you can view your account access keys and the complete connection string for each key.

  4. Recherchez la valeur de Chaîne de connexion sous clé1, puis sélectionnez le bouton Copier pour copier la chaîne de connexion.Find the Connection string value under key1, and select the Copy button to copy the connection string. Vous allez ajouter la valeur de chaîne de connexion dans une variable d’environnement à l’étape suivante.You will add the connection string value to an environment variable in the next step.

    Capture d’écran montrant comment copier une chaîne de connexion à partir du portail Azure

Configurer votre chaîne de connexion de stockageConfigure your storage connection string

Après avoir copié votre chaîne de connexion, écrivez-la dans une variable d’environnement sur l’ordinateur local exécutant l’application.After you have copied your connection string, write it to a new environment variable on the local machine running the application. Pour définir la variable d’environnement, ouvrez une fenêtre de console et suivez les instructions pour votre système d’exploitation.To set the environment variable, open a console window, and follow the instructions for your operating system. Remplacez <yourconnectionstring> par votre chaîne de connexion.Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx CONNECT_STR "<yourconnectionstring>"

Après avoir ajouté la variable d’environnement dans Windows, vous devez démarrer une nouvelle instance de la fenêtre de commande.After you add the environment variable in Windows, you must start a new instance of the command window.

LinuxLinux

export CONNECT_STR="<yourconnectionstring>"

MacOSMacOS

export CONNECT_STR="<yourconnectionstring>"

Après avoir ajouté la variable d’environnement, redémarrez tous les programmes en cours d’exécution qui devront la lire.After you add the environment variable, restart any running programs that will need to read the environment variable. Par exemple, redémarrez votre environnement de développement ou éditeur avant de continuer.For example, restart your development environment or editor before continuing.

Modèle objetObject model

Le Stockage Blob Azure est optimisé pour stocker de grandes quantités de données non structurées.Azure Blob storage is optimized for storing massive amounts of unstructured data. Les données non structurées sont des données qui n’obéissent pas à un modèle ou une définition de données en particulier, comme des données texte ou binaires.Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. Le stockage Blob offre trois types de ressources :Blob storage offers three types of resources:

  • Le compte de stockage.The storage account.
  • Un conteneur dans le compte de stockage.A container in the storage account
  • Un objet blob dans un conteneur.A blob in a container

Le diagramme suivant montre la relation entre ces ressources.The following diagram shows the relationship between these resources.

Diagramme de l’architecture du stockage Blob

Utilisez les classes .NET suivantes pour interagir avec ces ressources :Use the following .NET classes to interact with these resources:

  • CloudStorageAccount : La classe CloudStorageAccount représente votre compte de stockage Azure.CloudStorageAccount: The CloudStorageAccount class represents your Azure storage account. Utilisez cette classe pour autoriser l’accès au Stockage Blob à l’aide des clés d’accès à votre compte.Use this class to authorize access to Blob storage using your account access keys.
  • CloudBlobClient : La classe CloudBlobClient fournit un point d’accès au service blob dans votre code.CloudBlobClient: The CloudBlobClient class provides a point of access to the Blob service in your code.
  • CloudBlobContainer : La classe CloudBlobContainer représente un conteneur d'objet blob dans votre code.CloudBlobContainer: The CloudBlobContainer class represents a blob container in your code.
  • CloudBlockBlob : L’objet CloudBlockBlob représente un objet blob de blocs dans votre code.CloudBlockBlob: The CloudBlockBlob object represents a block blob in your code. Ils sont composés de blocs de données qui peuvent être gérés individuellement.Block blobs are made up of blocks of data that can be managed individually.

Exemples de codeCode examples

Ces exemples d’extraits de code vous montrent comment effectuer les opérations suivantes avec la bibliothèque cliente Stockage Blob Azure pour .NET :These example code snippets show you how to perform the following with the Azure Blob storage client library for .NET:

Authentifier le clientAuthenticate the client

Le code ci-dessous vérifie si la variable d’environnement contient une chaîne de connexion à analyser pour créer un objet CloudStorageAccount pointant vers le compte de stockage.The code below checks that the environment variable contains a connection string that can be parsed to create a CloudStorageAccount object pointing to the storage account. Pour vérifier si la chaîne de connexion est valide, utilisez la méthode TryParse.To check that the connection string is valid, use the TryParse method. Si la méthode TryParse réussit, elle initialise la variable storageAccount et retourne true.If TryParse is successful, it initializes the storageAccount variable and returns true.

Ajoutez ce code dans la méthode ProcessAsync :Add this code inside the ProcessAsync method:

// Retrieve the connection string for use with the application. The storage 
// connection string is stored in an environment variable on the machine 
// running the application called CONNECT_STR. If the 
// environment variable is created after the application is launched in a 
// console or with Visual Studio, the shell or application needs to be closed
// and reloaded to take the environment variable into account.
string storageConnectionString = Environment.GetEnvironmentVariable("CONNECT_STR");

// Check whether the connection string can be parsed.
CloudStorageAccount storageAccount;
if (CloudStorageAccount.TryParse(storageConnectionString, out storageAccount))
{
    // If the connection string is valid, proceed with operations against Blob
    // storage here.
    // ADD OTHER OPERATIONS HERE
}
else
{
    // Otherwise, let the user know that they need to define the environment variable.
    Console.WriteLine(
        "A connection string has not been defined in the system environment variables. " +
        "Add an environment variable named 'CONNECT_STR' with your storage " +
        "connection string as a value.");
    Console.WriteLine("Press any key to exit the application.");
    Console.ReadLine();
}

Notes

Pour effectuer le reste des opérations dans cet article, remplacez // ADD OTHER OPERATIONS HERE dans le code ci-dessus par les extraits de code dans les sections suivantes.To perform the rest of the operations in this article, replace // ADD OTHER OPERATIONS HERE in the code above with the code snippets in the following sections.

Créez un conteneur.Create a container

Pour créer le conteneur, créez d’abord une instance de l’objet CloudBlobClient pointant vers le stockage d’objets blob de votre compte de stockage.To create the container, first create an instance of the CloudBlobClient object, which points to Blob storage in your storage account. Ensuite, créez une instance de l’objet CloudBlobContainer puis le conteneur.Next, create an instance of the CloudBlobContainer object, then create the container.

Dans ce cas, le code appelle la méthode CreateAsync pour créer le conteneur.In this case, the code calls the CreateAsync method to create the container. Une valeur GUID est ajoutée au nom du conteneur pour s’assurer qu’il est unique.A GUID value is appended to the container name to ensure that it is unique. Dans un environnement de production, il est souvent préférable d’utiliser la méthode CreateIfNotExistsAsync pour créer un conteneur uniquement s’il n’existe pas déjà.In a production environment, it's often preferable to use the CreateIfNotExistsAsync method to create a container only if it does not already exist.

Important

Les noms de conteneurs doivent être en minuscules.Container names must be lowercase. 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.For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

// Create the CloudBlobClient that represents the 
// Blob storage endpoint for the storage account.
CloudBlobClient cloudBlobClient = storageAccount.CreateCloudBlobClient();

// Create a container called 'quickstartblobs' and 
// append a GUID value to it to make the name unique.
CloudBlobContainer cloudBlobContainer = 
    cloudBlobClient.GetContainerReference("quickstartblobs" + 
        Guid.NewGuid().ToString());
await cloudBlobContainer.CreateAsync();

Définir des autorisations sur un conteneurSet permissions on a container

Définissez des autorisations sur le conteneur afin que tous les objets blob du conteneur soient publics.Set permissions on the container so that any blobs in the container are public. Si un objet blob est public, n’importe quel client peut y accéder de façon anonyme.If a blob is public, it can be accessed anonymously by any client.

// Set the permissions so the blobs are public.
BlobContainerPermissions permissions = new BlobContainerPermissions
{
    PublicAccess = BlobContainerPublicAccessType.Blob
};
await cloudBlobContainer.SetPermissionsAsync(permissions);

Charger des objets blob sur un conteneurUpload blobs to a container

L’extrait de code suivant obtient une référence à un objet CloudBlockBlob en appelant la méthode GetBlockBlobReference sur le conteneur créé dans la section précédente.The following code snippet gets a reference to a CloudBlockBlob object by calling the GetBlockBlobReference method on the container created in the previous section. Il charge ensuite le fichier local sélectionné sur l’objet blob en appelant la méthode UploadFromFileAsync.It then uploads the selected local file to the blob by calling the UploadFromFileAsync method. Cette méthode crée l’objet blob s’il n’existe pas déjà, et le remplace s’il existe.This method creates the blob if it doesn't already exist, and overwrites it if it does.

// Create a file in your local MyDocuments folder to upload to a blob.
string localPath = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
string localFileName = "QuickStart_" + Guid.NewGuid().ToString() + ".txt";
string sourceFile = Path.Combine(localPath, localFileName);
// Write text to the file.
File.WriteAllText(sourceFile, "Hello, World!");

Console.WriteLine("Temp file = {0}", sourceFile);
Console.WriteLine("Uploading to Blob storage as blob '{0}'", localFileName);

// Get a reference to the blob address, then upload the file to the blob.
// Use the value of localFileName for the blob name.
CloudBlockBlob cloudBlockBlob = cloudBlobContainer.GetBlockBlobReference(localFileName);
await cloudBlockBlob.UploadFromFileAsync(sourceFile);

Créer la liste des objets blob d’un conteneurList the blobs in a container

Listez les objets blob du conteneur avec la méthode ListBlobsSegmentedAsync.List the blobs in the container by using the ListBlobsSegmentedAsync method. Dans ce cas, un seul objet blob a été ajouté au conteneur. Il n’y a donc qu’un objet blob répertorié.In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

S’il y a trop d’objets blob à retourner en un seul appel (par défaut, plus de 5 000), la méthode ListBlobsSegmentedAsync retourne un segment du jeu de résultats total ainsi qu’un jeton de continuation.If there are too many blobs to return in one call (by default, more than 5000), then the ListBlobsSegmentedAsync method returns a segment of the total result set and a continuation token. Pour récupérer le segment d’objets blob suivant, vous devez fournir le jeton de continuation retourné par l’appel précédent, jusqu’à ce que le jeton soit null.To retrieve the next segment of blobs, you provide in the continuation token returned by the previous call, and so on, until the continuation token is null. Un jeton de continuation null indique que tous les objets blob ont été récupérés.A null continuation token indicates that all of the blobs have been retrieved. Le code montre comment utiliser le jeton de continuation, dans l’intérêt des bonnes pratiques.The code shows how to use the continuation token for the sake of best practices.

// List the blobs in the container.
Console.WriteLine("List blobs in container.");
BlobContinuationToken blobContinuationToken = null;
do
{
    var results = await cloudBlobContainer.ListBlobsSegmentedAsync(null, blobContinuationToken);
    // Get the value of the continuation token returned by the listing call.
    blobContinuationToken = results.ContinuationToken;
    foreach (IListBlobItem item in results.Results)
    {
        Console.WriteLine(item.Uri);
    }
} while (blobContinuationToken != null); // Loop while the continuation token is not null.

Télécharger des objets blobDownload blobs

Téléchargez l’objet blob créé précédemment dans votre système de fichiers local avec la méthode DownloadToFileAsync.Download the blob created previously to your local file system by using the DownloadToFileAsync method. L’exemple de code ajoute le suffixe « _DOWNLOADED » au nom de l’objet blob afin que vous puissiez voir les deux fichiers dans votre système de fichiers local.The example code adds a suffix of "_DOWNLOADED" to the blob name so that you can see both files in local file system.

// Download the blob to a local file, using the reference created earlier.
// Append the string "_DOWNLOADED" before the .txt extension so that you 
// can see both files in MyDocuments.
string destinationFile = sourceFile.Replace(".txt", "_DOWNLOADED.txt");
Console.WriteLine("Downloading blob to {0}", destinationFile);
await cloudBlockBlob.DownloadToFileAsync(destinationFile, FileMode.Create);

Supprimer un conteneurDelete a container

Le code suivant nettoie les ressources créées par l’application en supprimant l’ensemble du conteneur avec la méthode CloudBlobContainer.DeleteAsync.The following code cleans up the resources the app created by deleting the entire container using CloudBlobContainer.DeleteAsync. Si vous voulez, vous pouvez aussi supprimer les fichiers locaux.You can also delete the local files if you like.

Console.WriteLine("Press the 'Enter' key to delete the example files, " +
    "example container, and exit the application.");
Console.ReadLine();
// Clean up resources. This includes the container and the two temp files.
Console.WriteLine("Deleting the container");
if (cloudBlobContainer != null)
{
    await cloudBlobContainer.DeleteIfExistsAsync();
}
Console.WriteLine("Deleting the source, and downloaded files");
File.Delete(sourceFile);
File.Delete(destinationFile);

Exécuter le codeRun the code

Cette application crée un fichier de test dans votre dossier local MyDocuments et le charge sur le Stockage Blob.This app creates a test file in your local MyDocuments folder and uploads it to Blob storage. 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.The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.

Accédez au répertoire de l’application, puis générez et exécutez l’application.Navigate to your application directory, then build and run the application.

dotnet build
dotnet run

Le résultat de l’application se présente comme dans l’exemple suivant :The output of the app is similar to the following example:

Azure Blob storage - .NET Quickstart example

Created container 'quickstartblobs33c90d2a-eabd-4236-958b-5cc5949e731f'

Temp file = C:\Users\myusername\Documents\QuickStart_c5e7f24f-a7f8-4926-a9da-96
97c748f4db.txt
Uploading to Blob storage as blob 'QuickStart_c5e7f24f-a7f8-4926-a9da-9697c748f
4db.txt'

Listing blobs in container.
https://storagesamples.blob.core.windows.net/quickstartblobs33c90d2a-eabd-4236-
958b-5cc5949e731f/QuickStart_c5e7f24f-a7f8-4926-a9da-9697c748f4db.txt

Downloading blob to C:\Users\myusername\Documents\QuickStart_c5e7f24f-a7f8-4926
-a9da-9697c748f4db_DOWNLOADED.txt

Press any key to delete the example files and example container.

Quand vous appuyez sur la touche Entrée,l’application supprime le conteneur de stockage et les fichiers.When you press the Enter key, the application deletes the storage container and the files. Avant de les supprimer, consultez les deux fichiers dans votre dossier MyDocuments.Before you delete them, check your MyDocuments folder for the two files. Vous pouvez les ouvrir et constater qu’ils sont identiques.You can open them and observe that they are identical. Copiez l’URL de l’objet blob depuis la fenêtre de console et collez-la dans un navigateur pour afficher son contenu.Copy the blob's URL from the console window and paste it into a browser to view the contents of the blob.

Une fois que vous avez vérifié les fichiers, appuyez sur n’importe quelle touche pour terminer la démonstration et supprimer les fichiers de test.After you've verified the files, hit any key to finish the demo and delete the test files.

Étapes suivantesNext steps

Dans ce démarrage rapide, vous avez appris à charger, télécharger et répertorier des objets blob avec .NET.In this quickstart, you learned how to upload, download, and list blobs using .NET.

Pour savoir comment créer une application web qui charge une image dans le stockage Blob, consultez :To learn how to create a web app that uploads an image to Blob storage, continue to: