Transférer des données avec la bibliothèque de déplacement de données

La bibliothèque de déplacement des données Stockage Azure est une bibliothèque multiplateforme open source conçue pour charger, télécharger et copier des objets blob et des fichiers avec des performances élevées. La bibliothèque de déplacement des données fournit des méthodes utiles qui ne sont pas disponibles dans la bibliothèque de client Stockage Azure pour .NET. Ces méthodes vous permettent de définir le nombre d’opérations parallèles, de suivre la progression des transferts, de reprendre un transfert annulé et bien plus encore.

La bibliothèque de déplacement des données n’est disponible que pour .NET et prend uniquement en charge le Stockage Blob Azure et Azure Files. Vous devez prendre en compte ces limitations et les autres problèmes connus lorsque vous décidez de l’utilisation de la bibliothèque de déplacement des données.

Si vous migrez du code de l’ancienne bibliothèque Microsoft.Azure.Storage.DataMovement (version 2.X.X) vers la bibliothèque Azure.Storage.DataMovement actuelle (version 12.X.X), consultez le Guide de migration.

Documentation de référence sur l’API | Code source | Package (NuGet) | Exemples : Blobs / Files.Shares

Prérequis

• Abonnement Azure : créez-en un gratuitement
• Compte de stockage Azure : créez un compte de stockage
• Dernière version du Kit de développement logiciel (SDK) .NET pour votre système d’exploitation. Veillez à disposer du Kit de développement logiciel (SDK), et non du runtime.

Paramétrer votre environnement

Si vous n’avez pas de projet existant, cette section vous montre comment configurer un projet pour travailler avec la bibliothèque de client Stockage Blob Azure pour .NET. Les étapes comprennent l’installation du package, l’ajout de directives using et la création d’un objet client autorisé.

Installer des packages

Depuis votre répertoire de projet, installez les packages pour la bibliothèque de client de déplacement des données Stockage Azure et la bibliothèque de client Azure Identity en utilisant la commande dotnet add package. Le package Azure.Identity est nécessaire pour les connexions sans mot de passe aux services Azure.

dotnet add package Azure.Storage.DataMovement
dotnet add package Azure.Storage.DataMovement.Blobs
dotnet add package Azure.Identity

Pour utiliser la bibliothèque d’extensions pour Azure Files, installez le package Azure.Storage.DataMovement.Files.Shares :

dotnet add package Azure.Storage.DataMovement.Files.Shares

Ajoutez des directives using.

Pour exécuter les exemples de code de cet article, ajoutez les directives using suivantes :

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.Storage.DataMovement;
using Azure.Storage.DataMovement.Blobs;

Si vous utilisez la bibliothèque d’extensions pour Azure Files, ajoutez la directive using suivante :

using Azure.Storage.DataMovement.Files.Shares;

Autorisation

Le mécanisme d’autorisation doit disposer des autorisations d’accès nécessaires pour effectuer des opérations de chargement, de téléchargement ou de copie. Pour l’autorisation avec Microsoft Entra ID (recommandé), vous devez disposer au minimum du rôle RBAC Azure intégré Contributeur aux données Blob du stockage.

À propos de la bibliothèque de déplacement de données

La bibliothèque de déplacement des données Stockage Azure se compose d’une bibliothèque de client commune et de bibliothèques d’extensions pour Stockage Blob Azure et Azure Files. La bibliothèque commune fournit les fonctionnalités principales pour le transfert de données, tandis que les bibliothèques d’extensions fournissent des fonctionnalités spécifiques au Stockage Blob et à Azure Files. Pour en savoir plus, consultez les ressources suivantes :

• Azure.Storage.DataMovement
• Azure.Storage.DataMovement.Blobs
• Azure.Storage.DataMovement.Files.Shares

Créer un objet TransferManager

TransferManager est la classe principale pour le démarrage et le contrôle de tous les types de transferts, notamment le chargement, le téléchargement et la copie. Dans cette section, vous apprenez à créer un objet TransferManager à utiliser avec un système de fichiers local, Stockage Blob ou Azure Files.

Remarque

Une bonne pratique pour la gestion des clients du kit de développement logiciel (SDK) Azure consiste à traiter un client comme un singleton, ce qui signifie qu’une classe n’a qu’un seul objet à la fois. Il n’est pas nécessaire de conserver plusieurs instances d’un client pour un ensemble donné de paramètres de constructeur ou d’options client.

Le code suivant montre comment créer un objet TransferManager :

TransferManager transferManager = new(new TransferManagerOptions());

Vous pouvez éventuellement fournir une instance de TransferManagerOptions au constructeur, qui applique certaines options de configuration à tous les transferts démarrés par l’objet TransferManager. Les options de configuration suivantes sont disponibles :

• CheckpointStoreOptions : facultatif. Définit les options de création d’un point de contrôle utilisé pour enregistrer l’état de transfert, afin que les transferts puissent être repris.
• Diagnostics : obtient les options de diagnostic du gestionnaire de transfert.
• ErrorHandling : facultatif. Définit la façon dont les erreurs sont gérées pendant un transfert. La valeur par défaut est StopOnAnyFailure.
• MaximumConcurrency : le nombre maximal de workers qui peuvent être utilisés dans un transfert parallèle.
• ProvidersForResuming: fournisseurs de ressources du gestionnaire de transfert à utiliser pour reprendre un transfert. Attend un fournisseur pour chaque fournisseur de stockage en cours d’utilisation. Pour plus d’informations, consultez Reprendre un transfert existant.

Créer un objet StorageResource

StorageResource est la classe de base pour toutes les ressources de stockage, y compris les objets blob et les fichiers. Pour créer un objet StorageResource, utilisez l’une des classes de fournisseur suivantes :

• BlobsStorageResourceProvider : utilisez cette classe pour créer des instances StorageResource pour un conteneur d’objets blob, un objet blob de blocs, un objet blob d’ajout ou un objet blob de pages.
• ShareFilesStorageResourceProvider : utilisez cette classe pour créer des instances StorageResource pour un fichier ou un répertoire.
• LocalFilesStorageResourceProvider : utilisez cette classe pour créer des instances StorageResource pour un système de fichiers local.

Créer un objet StorageResource pour Stockage Blob

Le code suivant montre comment créer un objet StorageResource pour les conteneurs d’objets blob et les objets blob utilisant un Uri :

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobsStorageResourceProvider blobsProvider = new(tokenCredential);

// Get a container resource
StorageResource container = await blobsProvider.FromContainerAsync(
    new Uri("http://<storage-account-name>.blob.core.windows.net/sample-container"));

// Get a block blob resource - default is block blob
StorageResource blockBlob = await blobsProvider.FromBlobAsync(
    new Uri("http://<storage-account-name>.blob.core.windows.net/sample-container/sample-block-blob"),
    new BlockBlobStorageResourceOptions());

// Use a similar approach to get a page blob or append blob resource

Vous pouvez également créer un objet StorageResource en utilisant un objet client depuis Azure.Storage.Blobs.

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobContainerClient blobContainerClient = new(
    new Uri("https://<storage-account-name>.blob.core.windows.net/sample-container"),
    tokenCredential);
StorageResource containerResource = BlobsStorageResourceProvider.FromClient(blobContainerClient);

BlockBlobClient blockBlobClient = blobContainerClient.GetBlockBlobClient("sample-block-blob");
StorageResource blockBlobResource = BlobsStorageResourceProvider.FromClient(blockBlobClient);

// Use a similar approach to get a page blob or append blob resource

Démarrer un nouveau transfert

Tous les transferts doivent spécifier une source et une destination. La source et la destination sont de type StorageResource, qui peut être soit StorageResourceContainer ou StorageResourceItem. Pour un transfert donné, la source et la destination doivent être du même type. Par exemple, si la source est un conteneur d’objets blob, la destination doit être un conteneur d’objets blob.

Vous pouvez démarrer un nouveau transfert en appelant la méthode suivante :

• TransferManager.StartTransferAsync

Cette méthode retourne un objet TransferOperation qui représente le transfert. Vous pouvez utiliser l’objet TransferOperation pour surveiller la progression du transfert ou obtenir l’ID de transfert. L’ID de transfert est un identificateur unique du transfert nécessaire pour reprendre un transfert ou suspendre un transfert.

Vous pouvez éventuellement fournir une instance de TransferOptions à StartTransferAsync ou ResumeTransferAsync, qui applique certaines options de configuration à un transfert spécifique. Les options de configuration suivantes sont disponibles :

• CreationMode : configure le comportement lorsqu’un transfert rencontre une ressource qui existe déjà. Est FailIfExists par défaut lors du démarrage d’un nouveau transfert. Lorsque vous reprenez un transfert, les valeurs par défaut peuvent varier. Pour toutes les ressources correctement listées lorsque le transfert a démarré, CreationMode est par défaut la valeur initiale utilisée. Pour toutes les ressources restantes, la valeur par défaut normale s’applique.
• InitialTransferSize : la taille de la première requête de plage en octets. Les tailles de transfert uniques inférieures à cette limite sont chargées ou téléchargées dans une seule requête. Les transferts supérieurs à cette limite continuent d’être chargés ou téléchargés en blocs de taille MaximumTransferChunkSize. La valeur par défaut est 32 Mio. Lorsque vous reprenez un transfert, la valeur par défaut est la valeur spécifiée lors du premier démarrage du transfert.
• MaximumTransferChunkSize : taille maximale à utiliser pour chaque bloc lors du transfert de données en blocs. La valeur par défaut est 4 Mio. Lorsque vous reprenez un transfert, la valeur par défaut est la valeur spécifiée lors du premier démarrage du transfert.
• ProgressHandlerOptions : facultatif. Options de modification du comportement du ProgressHandler.

Exemple : charger un répertoire local dans un conteneur d’objets blob

L’exemple de code suivant montre comment démarrer un nouveau transfert pour charger un répertoire local vers un conteneur d’objets blob :

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

TransferManager transferManager = new(new TransferManagerOptions());

BlobsStorageResourceProvider blobsProvider = new(tokenCredential);

string localDirectoryPath = "C:/path/to/directory";
Uri blobContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/sample-container");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: LocalFilesStorageResourceProvider.FromDirectory(localDirectoryPath),
    destinationResource: await blobsProvider.FromContainerAsync(blobContainerUri));
await transferOperation.WaitForCompletionAsync();

Exemple : copier un conteneur ou un objet blob

Vous pouvez utiliser la bibliothèque de déplacement des données pour copier entre deux instances StorageResource. Pour les ressources d’objet blob, le transfert utilise l’opération Put Blob From URL, qui effectue une copie de serveur à serveur.

L’exemple de code suivant montre comment démarrer un nouveau transfert pour copier tous les objets blob d’un conteneur d’objets blob source vers un conteneur d’objets blob de destination. Il doit déjà exister. Dans cet exemple, nous définissons CreationMode sur OverwriteIfExists pour remplacer tout objet blob de destination qui existe déjà. Vous pouvez ajuster la propriété CreationMode en fonction des besoins de votre application.

Uri sourceContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/source-container");
Uri destinationContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/dest-container");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: await blobsProvider.FromContainerAsync(
        sourceContainerUri,
        new BlobStorageResourceContainerOptions()
        {
            BlobPrefix = "source/directory/prefix"
        }),
    destinationResource: await blobsProvider.FromContainerAsync(
        destinationContainerUri,
        new BlobStorageResourceContainerOptions()
        {
            // All source blobs are copied as a single type of destination blob
            // Defaults to block blob, if not specified
            BlobType = BlobType.Block,
            BlobPrefix = "destination/directory/prefix"
        }),
    transferOptions: new TransferOptions()
    {
        CreationMode = StorageResourceCreationMode.OverwriteIfExists,
    }
);
await transferOperation.WaitForCompletionAsync();

L’exemple de code suivant montre comment démarrer un nouveau transfert pour copier un objet blob source vers un objet blob de destination. Dans cet exemple, nous définissons CreationMode sur OverwriteIfExists pour remplacer l’objet blob de destination s’il existe déjà. Vous pouvez ajuster la propriété CreationMode en fonction des besoins de votre application.

Uri sourceBlobUri = new Uri(
    "https://<storage-account-name>.blob.core.windows.net/source-container/source-blob");
Uri destinationBlobUri = new Uri(
    "https://<storage-account-name>.blob.core.windows.net/dest-container/dest-blob");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: await blobsProvider.FromBlobAsync(sourceBlobUri),
    destinationResource: await blobsProvider.FromBlobAsync(destinationBlobUri, new BlockBlobStorageResourceOptions()),
    transferOptions: new TransferOptions()
    {
        CreationMode = StorageResourceCreationMode.OverwriteIfExists,
    }
);
await transferOperation.WaitForCompletionAsync();

Reprendre un transfert existant

En conservant la progression du transfert sur le disque, la bibliothèque de déplacement des données vous permet de reprendre un transfert qui a échoué avant la fin, ou qui a été annulé ou suspendu. Pour reprendre un transfert, l’objet TransferManager doit être configuré avec des instances StorageResourceProvider capables de réassembler le transfert à partir des données conservées. Vous pouvez utiliser la propriété ProvidersForResuming de la classe TransferManagerOptions pour spécifier les fournisseurs.

L’exemple de code suivant montre comment initialiser un objet TransferManager capable de reprendre un transfert entre le système de fichiers local et Stockage Blob :

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

TransferManager transferManager = new(new TransferManagerOptions()
{
    ProvidersForResuming = new List<StorageResourceProvider>()
    {
        new BlobsStorageResourceProvider(tokenCredential)
    }
});

Pour reprendre un transfert, appelez la méthode suivante :

• TransferManager.ResumeTransferAsync

Indiquez l’ID de transfert du transfert que vous souhaitez reprendre. L’ID de transfert est un identificateur unique du transfert, retourné en tant qu’élément de l’objet TransferOperation au démarrage du transfert. Si vous ne connaissez pas la valeur de l’ID de transfert, vous pouvez appeler TransferManager.GetTransfersAsync pour rechercher le transfert et son ID correspondant.

L’exemple de code suivant montre comment reprendre un transfert :

TransferOperation resumedTransfer = await transferManager.ResumeTransferAsync(transferId: ID);

Remarque

L’emplacement des données de transfert conservées est différent de l’emplacement par défaut si TransferCheckpointStoreOptions est défini comme élément de TransferManagerOptions. Pour reprendre les transferts enregistrés avec un magasin de points de contrôle personnalisé, vous devez fournir les mêmes options de magasin de points de contrôle à l’objet TransferManager qui reprend le transfert.

Surveiller la progression du transfert

Les transferts peuvent être surveillés et observés par le biais de plusieurs mécanismes, en fonction des besoins de votre application. Dans cette section, vous apprenez à surveiller la progression d’un transfert en utilisant l’objet TransferOperation et à surveiller un transfert en utilisant des événements TransferOptions.

Exemple : surveiller la progression d’un transfert en utilisant l’objet TransferOperation

Vous pouvez surveiller la progression d’un transfert en utilisant l’objet TransferOperation retourné par la méthode StartTransferAsync. Vous pouvez également appeler TransferManager.GetTransfersAsync pour lister tous les transferts d’un objet TransferManager.

L’exemple de code suivant montre comment itérer sur tous les transferts et écrire l’état de chaque transfert dans un fichier journal :

async Task CheckTransfersAsync(TransferManager transferManager)
{
    await foreach (TransferOperation transfer in transferManager.GetTransfersAsync())
    {
        using StreamWriter logStream = File.AppendText("path/to/log/file");
        logStream.WriteLine(Enum.GetName(typeof(TransferState), transfer.Status.State));
    }
}

TransferStatus définit l’état du travail de transfert. TransferStatus inclut les propriétés suivantes :

Propriété	Type	Description
HasCompletedSuccessfully	Boolean	Indique si le transfert se termine correctement sans échec ni éléments ignorés.
HasFailedItems	Boolean	Indique si le transfert a des éléments d’échec. Si défini sur true, le transfert a au moins un élément d’échec. Si défini sur false, le transfert n’a actuellement aucun échec.
HasSkippedItems	Boolean	Indique si le transfert a des éléments ignorés. Si défini sur true, le transfert a au moins un élément ignoré. Si défini sur false, le transfert n’a actuellement aucun élément ignoré. Il est possible de ne jamais avoir d’éléments ignorés si SkipIfExists n’est pas activé dans TransferOptions.CreationMode.
State	TransferState	Définit les types d’état qu’un transfert peut avoir. Pour plus d’informations, consultez TransferState.

Exemple : surveiller la progression d’un transfert en utilisant des événements TransferOptions

Vous pouvez surveiller la progression d’un transfert en écoutant les événements fournis par la classe TransferOptions. L’instance TransferOptions est passée à la méthode StartTransferAsync et fournit des événements, déclenchés lorsqu’un transfert se termine, échoue, est ignoré ou change d’état.

L’exemple de code suivant montre comment écouter un événement d’achèvement de transfert en utilisant TransferOptions :

async Task<TransferOperation> ListenToTransfersAsync(
    TransferManager transferManager,
    StorageResource source,
    StorageResource destination)
{
    TransferOptions transferOptions = new();
    transferOptions.ItemTransferCompleted += (TransferItemCompletedEventArgs args) =>
    {
        using (StreamWriter logStream = File.AppendText("path/to/log/file"))
        {
            logStream.WriteLine($"File Completed Transfer: {args.Source.Uri.AbsoluteUri}");
        }
        return Task.CompletedTask;
    };
    return await transferManager.StartTransferAsync(
        source,
        destination,
        transferOptions);
}

Utiliser des méthodes d'extension pour BlobContainerClient

Pour les applications avec du code existant qui utilise la classe BlobContainerClient depuis Azure.Storage.Blobs , vous pouvez utiliser des méthodes d’extension pour démarrer les transferts directement depuis un objet BlobContainerClient. Les méthodes d’extension sont fournies dans la classe BlobContainerClientExtensions (ou ShareDirectoryClientExtensions pour Azure Files) et offrent certains des avantages de l’utilisation de TransferManager avec des modifications de code minimales. Dans cette section, apprenez à utiliser les méthodes d’extension pour effectuer des transferts depuis un objet BlobContainerClient.

Installez le package Azure.Storage.Blobs si vous ne l’avez pas déjà fait :

dotnet add package Azure.Storage.Blobs

Ajoutez les directives using suivantes en haut de votre fichier code :

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

L’exemple de code suivant montre comment instancier un BlobContainerClient pour un conteneur d’objets blob nommé sample-container :

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobServiceClient client = new BlobServiceClient(
    new Uri("https://<storage-account-name>.blob.core.windows.net"),
    tokenCredential);

BlobContainerClient containerClient = client.GetBlobContainerClient("sample-container");

L’exemple de code suivant montre comment charger le contenu du répertoire local sur sample-container en utilisant UploadDirectoryAsync :

TransferOperation transfer = await containerClient
    .UploadDirectoryAsync(WaitUntil.Started, "local/directory/path");

await transfer.WaitForCompletionAsync();

L’exemple de code suivant montre comment télécharger le contenu d’un sample-container vers un répertoire local en utilisant DownloadToDirectoryAsync :

TransferOperation transfer = await containerClient
    .DownloadToDirectoryAsync(WaitUntil.Started, "local/directory/path");

await transfer.WaitForCompletionAsync();

Pour en savoir plus sur les méthodes d’extension pour BlobContainerClient, consultez Extensions sur BlobContainerClient.

Étape suivante

• Les exemples de code pour DataMovement.Blobs et DataMovement.Files.Shares sont disponibles dans le référentiel GitHub du kit de développement logiciel (SDK) Azure pour .NET.