Transférer des données avec la bibliothèque de déplacement de données
Remarque
Cet article contient des conseils pour l’utilisation de la version 2.0.XX de la bibliothèque de déplacement des données du stockage Azure. La version 2.0.XX est actuellement en mode maintenance et la bibliothèque reçoit uniquement des correctifs pour l’intégrité des données et les problèmes de sécurité. Aucune nouvelle fonctionnalité ou fonctionnalité n’est ajoutée, et les nouvelles versions du service de stockage ne seront pas prises en charge par la bibliothèque.
Les versions bêta d’une bibliothèque de déplacement de données moderne sont actuellement en cours de développement. Pour plus d’informations, consultez Bibliothèque de client commune de déplacement des données du stockage Azure pour .NET sur GitHub.
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 définir le nombre d’opérations parallèles, à suivre la progression des transferts, à reprendre facilement un transfert annulé et bien plus encore.
Cette bibliothèque utilise également .NET Core, ce qui signifie que vous pouvez l’utiliser pour créer des applications .NET pour Windows, Linux et macOS. Pour en savoir plus sur .NET Core, consultez la Documentation .NET Core. Cette bibliothèque fonctionne également pour les applications .NET Framework classiques pour Windows.
Ce document montre comment créer une application de console .NET Core qui s’exécute sous Windows, Linux et macOS et effectue les scénarios suivants :
- charger des fichiers et des répertoires vers le Stockage Blob ;
- définir le nombre d’opérations parallèles lors du transfert de données ;
- suivre la progression du transfert de données ;
- reprendre les transferts de données annulés ;
- copier des fichiers de l’URL vers le Stockage Blob ;
- copier d’un Stockage Blob à un autre.
Prérequis
Programme d’installation
- Consultez le Guide d'installation de .NET Core pour installer le kit SDK .NET Core. Lorsque vous sélectionnez votre environnement, choisissez l’option de ligne de commande.
- En ligne de commande, créez un répertoire pour votre projet. Accédez à ce répertoire, puis tapez
dotnet new console -o <sample-project-name>
pour créer un projet de console C#. - Ouvrez ce répertoire dans Visual Studio Code. Vous pouvez effectuer rapidement cette étape en tapant
code .
en ligne de commande dans Windows. - Installez l’extension C# à partir de la Place de marché Visual Studio. Redémarrez Visual Studio Code.
- À ce stade, vous devez voir deux invites. L’une permet d’ajouter les « composants requis pour générer et déboguer ». Sélectionnez « Oui ». L’autre invite permet de restaurer les dépendances non résolues. Sélectionnez « Restaurer ».
- Modifiez
launch.json
sous.vscode
pour utiliser un terminal externe comme console. Ce paramètre doit alors être"console": "externalTerminal"
. - Visual Studio Code vous permet de déboguer les applications .NET Core. Appuyez sur
F5
pour exécuter votre application et vérifier que votre configuration fonctionne. Le texte « Hello World! » doit s’afficher dans la console.
Ajouter la bibliothèque de déplacement des données à votre projet
- Ajoutez la dernière version de la bibliothèque de déplacement des données à la section
dependencies
de votre fichier<project-name>.csproj
. Au moment de la rédaction de cette page, il s’agit de la version"Microsoft.Azure.Storage.DataMovement": "0.6.2"
. - Une invite doit s’afficher pour restaurer votre projet. Sélectionnez le bouton « Restaurer ». Vous pouvez également restaurer votre projet en ligne de commande en tapant la commande
dotnet restore
à la racine du répertoire de votre projet.
Modifiez <project-name>.csproj
:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp2.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Azure.Storage.DataMovement" Version="0.6.2" />
</ItemGroup>
</Project>
Configurer l’infrastructure d’application
La première chose que nous faisons est de configurer l’infrastructure de code pour notre application. Ce code nous demande une clé et un nom de compte de stockage et utilise ces informations d’identification pour créer un objet CloudStorageAccount
. Cet objet est utilisé pour interagir avec notre compte de stockage dans tous les scénarios de transfert. Le code nous invite également à choisir le type d’opération de transfert que nous souhaitons exécuter.
Modifiez Program.cs
:
using System;
using System.Threading;
using System.Threading.Tasks;
using System.Diagnostics;
using Microsoft.Azure.Storage;
using Microsoft.Azure.Storage.Blob;
using Microsoft.Azure.Storage.DataMovement;
namespace DMLibSample
{
public class Program
{
public static void Main()
{
Console.WriteLine("Enter Storage account name:");
string accountName = Console.ReadLine();
Console.WriteLine("\nEnter Storage account key:");
string accountKey = Console.ReadLine();
string storageConnectionString = "DefaultEndpointsProtocol=https;AccountName=" + accountName + ";AccountKey=" + accountKey;
CloudStorageAccount account = CloudStorageAccount.Parse(storageConnectionString);
ExecuteChoice(account);
}
public static void ExecuteChoice(CloudStorageAccount account)
{
Console.WriteLine("\nWhat type of transfer would you like to execute?\n1. Local file --> Azure Blob\n2. Local directory --> Azure Blob directory\n3. URL (e.g. Amazon S3 file) --> Azure Blob\n4. Azure Blob --> Azure Blob");
int choice = int.Parse(Console.ReadLine());
if(choice == 1)
{
TransferLocalFileToAzureBlob(account).Wait();
}
else if(choice == 2)
{
TransferLocalDirectoryToAzureBlobDirectory(account).Wait();
}
else if(choice == 3)
{
TransferUrlToAzureBlob(account).Wait();
}
else if(choice == 4)
{
TransferAzureBlobToAzureBlob(account).Wait();
}
}
public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
}
public static async Task TransferLocalDirectoryToAzureBlobDirectory(CloudStorageAccount account)
{
}
public static async Task TransferUrlToAzureBlob(CloudStorageAccount account)
{
}
public static async Task TransferAzureBlobToAzureBlob(CloudStorageAccount account)
{
}
}
}
Important
Cet exemple de code utilise une chaîne de connexion pour autoriser l’accès à votre compte de stockage. Cette configuration est utilisée à titre d’exemple. Les chaînes de connexion et les clés d’accès au compte doivent être utilisées avec précaution dans le code de l’application. Si votre clé d’accès de compte est perdue ou accidentellement placée dans un emplacement non sécurisé, votre service peut devenir vulnérable. 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.
Charger un fichier local vers un objet blob
Ajoutez les méthodes GetSourcePath
et GetBlob
à Program.cs
:
public static string GetSourcePath()
{
Console.WriteLine("\nProvide path for source:");
string sourcePath = Console.ReadLine();
return sourcePath;
}
public static CloudBlockBlob GetBlob(CloudStorageAccount account)
{
CloudBlobClient blobClient = account.CreateCloudBlobClient();
Console.WriteLine("\nProvide name of Blob container:");
string containerName = Console.ReadLine();
CloudBlobContainer container = blobClient.GetContainerReference(containerName);
container.CreateIfNotExistsAsync().Wait();
Console.WriteLine("\nProvide name of new Blob:");
string blobName = Console.ReadLine();
CloudBlockBlob blob = container.GetBlockBlobReference(blobName);
return blob;
}
Modifiez la méthode TransferLocalFileToAzureBlob
:
public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
string localFilePath = GetSourcePath();
CloudBlockBlob blob = GetBlob(account);
Console.WriteLine("\nTransfer started...");
await TransferManager.UploadAsync(localFilePath, blob);
Console.WriteLine("\nTransfer operation complete.");
ExecuteChoice(account);
}
Ce code nous demande le chemin d’accès à un fichier local, le nom d’un conteneur nouveau ou existant et le nom d’un nouvel objet blob. La méthode TransferManager.UploadAsync
effectue le chargement suivant ces informations.
Appuyez sur F5
pour exécuter votre application. Vous pouvez vérifier que le chargement a bien été effectué en affichant votre compte de Stockage avec l’Explorateur de Stockage Microsoft Azure.
Définir le nombre d’opérations parallèles
La bibliothèque de déplacement des données offre la possibilité de définir le nombre d’opérations parallèles pour augmenter le débit du transfert de données. Par défaut, la bibliothèque de déplacement des données fixe le nombre d’opérations parallèles à 8 * le nombre de cœurs sur votre ordinateur.
Remarque : un grand nombre d’opérations parallèles dans un environnement à faible bande passante peut surcharger la connexion réseau et en réalité entraver le bon déroulement des opérations. Faites des essais avec ce paramètre pour déterminer ce qui fonctionne le mieux en fonction de votre bande passante réseau disponible.
Dans cet exemple, nous ajoutons du code pour pouvoir définir le nombre d’opérations parallèles. Nous ajoutons également du code afin de chronométrer la durée du transfert.
Ajoutez une méthode SetNumberOfParallelOperations
à Program.cs
:
public static void SetNumberOfParallelOperations()
{
Console.WriteLine("\nHow many parallel operations would you like to use?");
string parallelOperations = Console.ReadLine();
TransferManager.Configurations.ParallelOperations = int.Parse(parallelOperations);
}
Modifiez la méthode ExecuteChoice
de sorte qu’elle utilise SetNumberOfParallelOperations
:
public static void ExecuteChoice(CloudStorageAccount account)
{
Console.WriteLine("\nWhat type of transfer would you like to execute?\n1. Local file --> Azure Blob\n2. Local directory --> Azure Blob directory\n3. URL (e.g. Amazon S3 file) --> Azure Blob\n4. Azure Blob --> Azure Blob");
int choice = int.Parse(Console.ReadLine());
SetNumberOfParallelOperations();
if(choice == 1)
{
TransferLocalFileToAzureBlob(account).Wait();
}
else if(choice == 2)
{
TransferLocalDirectoryToAzureBlobDirectory(account).Wait();
}
else if(choice == 3)
{
TransferUrlToAzureBlob(account).Wait();
}
else if(choice == 4)
{
TransferAzureBlobToAzureBlob(account).Wait();
}
}
Modifiez la méthode TransferLocalFileToAzureBlob
de sorte qu’elle utilise un minuteur :
public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
string localFilePath = GetSourcePath();
CloudBlockBlob blob = GetBlob(account);
Console.WriteLine("\nTransfer started...");
Stopwatch stopWatch = Stopwatch.StartNew();
await TransferManager.UploadAsync(localFilePath, blob);
stopWatch.Stop();
Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
ExecuteChoice(account);
}
Suivre la progression des transferts
Vous pouvez suivre la progression du transfert pendant l’opération de transfert en créant un objet TransferContext
. L’objet TransferContext
est fourni sous deux formes : SingleTransferContext
pour les transferts de fichiers uniques et DirectoryTransferContext
pour les transferts d’annuaires.
Ajoutez les méthodes GetSingleTransferContext
et GetDirectoryTransferContext
à Program.cs
:
public static SingleTransferContext GetSingleTransferContext(TransferCheckpoint checkpoint)
{
SingleTransferContext context = new SingleTransferContext(checkpoint);
context.ProgressHandler = new Progress<TransferStatus>((progress) =>
{
Console.Write("\rBytes transferred: {0}", progress.BytesTransferred );
});
return context;
}
public static DirectoryTransferContext GetDirectoryTransferContext(TransferCheckpoint checkpoint)
{
DirectoryTransferContext context = new DirectoryTransferContext(checkpoint);
context.ProgressHandler = new Progress<TransferStatus>((progress) =>
{
Console.Write("\rBytes transferred: {0}", progress.BytesTransferred );
});
return context;
}
Modifiez la méthode TransferLocalFileToAzureBlob
de sorte qu’elle utilise GetSingleTransferContext
:
public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
string localFilePath = GetSourcePath();
CloudBlockBlob blob = GetBlob(account);
TransferCheckpoint checkpoint = null;
SingleTransferContext context = GetSingleTransferContext(checkpoint);
Console.WriteLine("\nTransfer started...\n");
Stopwatch stopWatch = Stopwatch.StartNew();
await TransferManager.UploadAsync(localFilePath, blob, null, context);
stopWatch.Stop();
Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
ExecuteChoice(account);
}
Reprendre un transfert annulé
Une autre fonctionnalité offerte par la bibliothèque de déplacement des données est de pouvoir reprendre un transfert annulé. Ensuite, nous ajoutons du code qui nous permettra d’annuler temporairement le transfert en tapant c
, puis de le reprendre trois secondes plus tard.
Modifiez la méthode TransferLocalFileToAzureBlob
:
public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
string localFilePath = GetSourcePath();
CloudBlockBlob blob = GetBlob(account);
TransferCheckpoint checkpoint = null;
SingleTransferContext context = GetSingleTransferContext(checkpoint);
CancellationTokenSource cancellationSource = new CancellationTokenSource();
Console.WriteLine("\nTransfer started...\nPress 'c' to temporarily cancel your transfer...\n");
Stopwatch stopWatch = Stopwatch.StartNew();
Task task;
ConsoleKeyInfo keyinfo;
try
{
task = TransferManager.UploadAsync(localFilePath, blob, null, context, cancellationSource.Token);
while(!task.IsCompleted)
{
if(Console.KeyAvailable)
{
keyinfo = Console.ReadKey(true);
if(keyinfo.Key == ConsoleKey.C)
{
cancellationSource.Cancel();
}
}
}
await task;
}
catch(Exception e)
{
Console.WriteLine("\nThe transfer is canceled: {0}", e.Message);
}
if(cancellationSource.IsCancellationRequested)
{
Console.WriteLine("\nTransfer will resume in 3 seconds...");
Thread.Sleep(3000);
checkpoint = context.LastCheckpoint;
context = GetSingleTransferContext(checkpoint);
Console.WriteLine("\nResuming transfer...\n");
await TransferManager.UploadAsync(localFilePath, blob, null, context);
}
stopWatch.Stop();
Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
ExecuteChoice(account);
}
Jusqu’à présent, notre checkpoint
avait la valeur null
. Maintenant, si nous annulons le transfert, nous récupérons le dernier point de contrôle de notre transfert, puis nous utilisons ce nouveau point de contrôle dans notre contexte de transfert.
Transférer un répertoire local vers le stockage Blob
La bibliothèque de déplacement des données vous permet de transférer un répertoire de fichiers et tous ses sous-répertoires, comme illustré dans l’exemple suivant.
Tout d’abord, ajoutez la méthode GetBlobDirectory
à Program.cs
:
public static CloudBlobDirectory GetBlobDirectory(CloudStorageAccount account)
{
CloudBlobClient blobClient = account.CreateCloudBlobClient();
Console.WriteLine("\nProvide name of Blob container. This can be a new or existing Blob container:");
string containerName = Console.ReadLine();
CloudBlobContainer container = blobClient.GetContainerReference(containerName);
container.CreateIfNotExistsAsync().Wait();
CloudBlobDirectory blobDirectory = container.GetDirectoryReference("");
return blobDirectory;
}
Ensuite, modifiez TransferLocalDirectoryToAzureBlobDirectory
:
public static async Task TransferLocalDirectoryToAzureBlobDirectory(CloudStorageAccount account)
{
string localDirectoryPath = GetSourcePath();
CloudBlobDirectory blobDirectory = GetBlobDirectory(account);
TransferCheckpoint checkpoint = null;
DirectoryTransferContext context = GetDirectoryTransferContext(checkpoint);
CancellationTokenSource cancellationSource = new CancellationTokenSource();
Console.WriteLine("\nTransfer started...\nPress 'c' to temporarily cancel your transfer...\n");
Stopwatch stopWatch = Stopwatch.StartNew();
Task task;
ConsoleKeyInfo keyinfo;
UploadDirectoryOptions options = new UploadDirectoryOptions()
{
Recursive = true
};
try
{
task = TransferManager.UploadDirectoryAsync(localDirectoryPath, blobDirectory, options, context, cancellationSource.Token);
while(!task.IsCompleted)
{
if(Console.KeyAvailable)
{
keyinfo = Console.ReadKey(true);
if(keyinfo.Key == ConsoleKey.C)
{
cancellationSource.Cancel();
}
}
}
await task;
}
catch(Exception e)
{
Console.WriteLine("\nThe transfer is canceled: {0}", e.Message);
}
if(cancellationSource.IsCancellationRequested)
{
Console.WriteLine("\nTransfer will resume in 3 seconds...");
Thread.Sleep(3000);
checkpoint = context.LastCheckpoint;
context = GetDirectoryTransferContext(checkpoint);
Console.WriteLine("\nResuming transfer...\n");
await TransferManager.UploadDirectoryAsync(localDirectoryPath, blobDirectory, options, context);
}
stopWatch.Stop();
Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
ExecuteChoice(account);
}
Il existe quelques différences entre cette méthode et la méthode de chargement d’un seul fichier. Nous utilisons maintenant TransferManager.UploadDirectoryAsync
et la méthode getDirectoryTransferContext
créée précédemment. En outre, nous fournissons à présent une valeur options
à notre opération de chargement, ce qui nous permet d’indiquer que nous souhaitons inclure les sous-répertoires à notre chargement.
Copier un fichier d’une URL vers un objet blob
À présent, nous allons ajouter du code permettant de copier un fichier à partir d’une URL vers un objet blob Azure.
Modifiez TransferUrlToAzureBlob
:
public static async Task TransferUrlToAzureBlob(CloudStorageAccount account)
{
Uri uri = new Uri(GetSourcePath());
CloudBlockBlob blob = GetBlob(account);
TransferCheckpoint checkpoint = null;
SingleTransferContext context = GetSingleTransferContext(checkpoint);
CancellationTokenSource cancellationSource = new CancellationTokenSource();
Console.WriteLine("\nTransfer started...\nPress 'c' to temporarily cancel your transfer...\n");
Stopwatch stopWatch = Stopwatch.StartNew();
Task task;
ConsoleKeyInfo keyinfo;
try
{
task = TransferManager.CopyAsync(uri, blob, CopyMethod.ServiceSideAsyncCopy, null, context, cancellationSource.Token);
while(!task.IsCompleted)
{
if(Console.KeyAvailable)
{
keyinfo = Console.ReadKey(true);
if(keyinfo.Key == ConsoleKey.C)
{
cancellationSource.Cancel();
}
}
}
await task;
}
catch(Exception e)
{
Console.WriteLine("\nThe transfer is canceled: {0}", e.Message);
}
if(cancellationSource.IsCancellationRequested)
{
Console.WriteLine("\nTransfer will resume in 3 seconds...");
Thread.Sleep(3000);
checkpoint = context.LastCheckpoint;
context = GetSingleTransferContext(checkpoint);
Console.WriteLine("\nResuming transfer...\n");
await TransferManager.CopyAsync(uri, blob, CopyMethod.ServiceSideAsyncCopy, null, context, cancellationSource.Token);
}
stopWatch.Stop();
Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
ExecuteChoice(account);
}
L’un des cas d’utilisation les plus importants de cette fonctionnalité est le déplacement de données d’un autre service cloud vers Azure. Si vous disposez d’une URL qui vous permet d’accéder à la ressource, vous pouvez facilement déplacer cette ressource dans des objets blob Azure à l’aide de la méthode TransferManager.CopyAsync
. Cette méthode introduit également un nouveau paramètre CopyMethod. Le tableau suivant affiche les options disponibles pour ce paramètre :
Nom du membre | Value | Description |
---|---|---|
SyncCopy | 0 | Téléchargez les données de la source vers la mémoire, puis chargez les données de la mémoire vers la destination. Actuellement uniquement disponible pour copier une ressource de Stockage Azure vers une autre. |
ServiceSideAsyncCopy | 1 | Envoyez une demande de copie de démarrage au Stockage Azure pour lui permettre d’effectuer la copie et surveillez la progression de l’opération de copie jusqu’à son terme. |
ServiceSideSyncCopy | 2 | Copiez le contenu de chaque segment avec Put Block From URL, Append Block From URL ou Put Page From URL. |
Copier un objet blob
Une autre fonctionnalité fournie par la bibliothèque de déplacement des données est la possibilité de copier d’une ressource Stockage Azure vers une autre.
Modifiez la méthode TransferAzureBlobToAzureBlob
:
public static async Task TransferAzureBlobToAzureBlob(CloudStorageAccount account)
{
CloudBlockBlob sourceBlob = GetBlob(account);
CloudBlockBlob destinationBlob = GetBlob(account);
TransferCheckpoint checkpoint = null;
SingleTransferContext context = GetSingleTransferContext(checkpoint);
CancellationTokenSource cancellationSource = new CancellationTokenSource();
Console.WriteLine("\nTransfer started...\nPress 'c' to temporarily cancel your transfer...\n");
Stopwatch stopWatch = Stopwatch.StartNew();
Task task;
ConsoleKeyInfo keyinfo;
try
{
task = TransferManager.CopyAsync(sourceBlob, destinationBlob, CopyMethod.SyncCopy, null, context, cancellationSource.Token);
while(!task.IsCompleted)
{
if(Console.KeyAvailable)
{
keyinfo = Console.ReadKey(true);
if(keyinfo.Key == ConsoleKey.C)
{
cancellationSource.Cancel();
}
}
}
await task;
}
catch(Exception e)
{
Console.WriteLine("\nThe transfer is canceled: {0}", e.Message);
}
if(cancellationSource.IsCancellationRequested)
{
Console.WriteLine("\nTransfer will resume in 3 seconds...");
Thread.Sleep(3000);
checkpoint = context.LastCheckpoint;
context = GetSingleTransferContext(checkpoint);
Console.WriteLine("\nResuming transfer...\n");
await TransferManager.CopyAsync(sourceBlob, destinationBlob, CopyMethod.SyncCopy, null, context, cancellationSource.Token);
}
stopWatch.Stop();
Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
ExecuteChoice(account);
}
Dans cet exemple, nous donnons la valeur CopyMethod.SyncCopy
au paramètre booléen TransferManager.CopyAsync
pour indiquer que nous souhaitons effectuer une copie synchrone. Cette configuration signifie que la ressource est d’abord téléchargée sur notre ordinateur local, puis chargée vers Stockage Blob Azure. L’option de copie synchrone est un excellent moyen de veiller à ce que l’opération de copie ait une vitesse constante. À l’inverse, la vitesse de la copie asynchrone côté serveur dépend de la bande passante réseau disponible sur le serveur, qui peut varier. Toutefois, la copie synchrone peut générer des coûts de sortie supplémentaires par rapport à la copie asynchrone. L’approche recommandée consiste à utiliser la copie synchrone dans une machine virtuelle Azure qui se trouve dans la même région que votre compte de stockage source afin d’éviter les frais de sortie.
L’application de déplacement des données est à présent terminée. L’exemple de code complet est disponible sur GitHub.
Étapes suivantes
Documentation de référence de la bibliothèque de déplacement des données du Stockage Azure.
Conseil
Gérer les ressources de Stockage Blob Azure avec l’Explorateur de stockage Azure. Azure Storage Explorer est une application autonome et gratuite qui vous permet de gérer les ressources de stockage Blob Azure. L’Explorateur de stockage Azure vous permet de créer, lire, mettre à jour et supprimer visuellement des objets blob ainsi que les conteneurs d’objets blob, en plus de gérer l’accès à ces derniers.