Partager via

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 d’autres problèmes connus lors de la décision d’utiliser 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

Prerequisites

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;

Authorization

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 :

Créer un objet TransferManager

TransferManager est la classe principale pour démarrer et contrôler 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.

Note

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.
  • ErrorMode : 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 travailleurs pouvant être utilisés dans un transfert parallèle.
  • ProvidersForResuming : fournisseurs de ressources pour le 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 StorageResource instances 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 StorageResource des instances pour un fichier ou un répertoire.
  • LocalFilesStorageResourceProvider : utilisez cette classe pour créer StorageResource des instances 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 à l’aide d’un StorageResource objet client à partir d’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 :

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 vers 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 : 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 téléchargés ou téléversé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 afin d'écraser les objets blob de destination qui existent 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 configurons CreationMode sur OverwriteIfExists pour écraser 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 ProvidersForResuming propriété 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 :

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);

Note

L’emplacement des données de transfert persistantes est différent de l’emplacement par défaut si TransferCheckpointStoreOptions est défini dans le cadre 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 énumérer tous les transferts d’un TransferManager objet.

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 :

Property 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 qu'aucun élément ne soit ignoré 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 du transfert en écoutant les événements fournis par la classe TransferOptions . L’instance TransferOptions est passée à la StartTransferAsync méthode et fournit des événements déclenchés lorsqu’un transfert se termine, échoue, est ignoré ou modifie l’é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 BlobContainerClient classe à partir d’Azure.Storage.Blobs, vous pouvez utiliser des méthodes d’extension pour démarrer les transferts directement à partir d’un BlobContainerClient objet. Les méthodes d’extension sont fournies dans la classe BlobContainerClientExtensions (ou ShareDirectoryClientExtensions pour Azure Files) et offrent certains des avantages de l’utilisation 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à :

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

  • Last updated on