Condividi tramite

Trasferire dati con la libreria di Spostamento dati

La libreria di spostamento dati Archiviazione di Azure è una libreria open source multipiattaforma progettata per caricamento, download e copia di BLOB e file ad alte prestazioni. La libreria di spostamento dati fornisce metodi pratici che non sono disponibili nella libreria client Archiviazione di Azure per .NET. Questi metodi consentono di impostare il numero di operazioni parallele, tenere traccia dello stato di avanzamento del trasferimento, riprendere un trasferimento annullato e altro ancora.

La libreria di spostamento dati è disponibile solo per .NET e supporta solo Archiviazione BLOB di Azure e File di Azure. You should consider these limitations and other known issues when deciding whether to use the Data Movement library.

If you're migrating code from the older Microsoft.Azure.Storage.DataMovement library (version 2.X.X) to the current Azure.Storage.DataMovement library (version 12.X.X), see the Migration guide.

Documentazione di | riferimento api Pacchetto del codice | sorgente (NuGet) | Esempi: Blob / Files.Shares

Prerequisites

Configurazione dell'ambiente

Se non si ha un progetto esistente, questa sezione spiega come configurare un progetto per l'uso con la libreria client di Archiviazione BLOB di Azure per .NET. I passaggi includono l'installazione del pacchetto, l'aggiunta di direttive using e la creazione di un oggetto client autorizzato.

Install packages

Nella directory del progetto installare i pacchetti per la libreria client di spostamento dati Archiviazione di Azure e la libreria client di Identità di Azure usando il dotnet add package comando . The Azure.Identity package is needed for passwordless connections to Azure services.

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

To work with extension library for Azure Files, install the Azure.Storage.DataMovement.Files.Shares package:

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

Aggiungere le direttive using

Per eseguire gli esempi di codice in questo articolo, aggiungere le direttive seguenti using :

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

Se si usa la libreria di estensioni per File di Azure, aggiungere la direttiva seguenteusing:

using Azure.Storage.DataMovement.Files.Shares;

Authorization

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per eseguire operazioni di caricamento, download o copia. Per l'autorizzazione con Microsoft Entra ID (scelta consigliata), è necessario disporre del ruolo predefinito di Controllo degli accessi in base al ruolo di Azure Collaboratore ai dati del BLOB di archiviazione o ruolo superiore.

Informazioni sulla libreria di spostamento dati

La libreria di spostamento dati Archiviazione di Azure è costituita da una libreria client comune e librerie di estensioni per Archiviazione BLOB di Azure e File di Azure. La libreria comune offre la funzionalità di base per il trasferimento dei dati, mentre le librerie di estensioni forniscono funzionalità specifiche dell'archiviazione BLOB e File di Azure. Per altre informazioni, vedere le risorse seguenti:

Creare un oggetto TransferManager

TransferManager is the main class for starting and controlling all types of transfers, including upload, download, and copy. In questa sezione viene illustrato come creare un TransferManager oggetto per lavorare con un file system locale, un archivio BLOB o un File di Azure.

Note

Una procedura consigliata per la gestione client di Azure SDK consiste nel considerare un client come singleton, vale a dire che una classe ha un solo oggetto alla volta. Non è necessario mantenere più di un'istanza di un client per un determinato set di parametri del costruttore o di opzioni del client.

Il codice seguente illustra come creare un TransferManager oggetto :

TransferManager transferManager = new(new TransferManagerOptions());

You can optionally provide an instance of TransferManagerOptions to the constructor, which applies certain configuration options to all transfers started by the TransferManager object. Sono disponibili le opzioni di configurazione seguenti:

  • CheckpointStoreOptions: Optional. Definisce le opzioni per la creazione di un checkpoint utilizzato per salvare lo stato di trasferimento in modo che i trasferimenti possano essere ripresi.
  • Diagnostics: Gets the transfer manager diagnostic options.
  • Definisce la modalità di gestione degli errori durante un trasferimento. Il valore predefinito è StopOnAnyFailure. Default is StopOnAnyFailure.
  • MaximumConcurrency: The maximum number of workers that can be used in a parallel transfer.
  • ProvidersForResuming: Resource providers for the transfer manager to use in resuming a transfer. Prevede un provider per ogni provider di archiviazione in uso. Per altre informazioni, vedere Riprendere un trasferimento esistente.

Creare un oggetto StorageResource

StorageResource is the base class for all storage resources, including blobs and files. Per creare un StorageResource oggetto, utilizzare una delle classi di provider seguenti:

Creare un StorageResource oggetto per l'archiviazione BLOB

Il codice seguente illustra come creare un StorageResource oggetto per contenitori BLOB e BLOB usando :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

You can also create a StorageResource object using a client object from 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

Avviare un nuovo trasferimento

Tutti i trasferimenti devono specificare un'origine e una destinazione. Sia l'origine che la destinazione sono di tipo StorageResource, che può essere StorageResourceContainer o StorageResourceItem. Per un determinato trasferimento, l'origine e la destinazione devono essere dello stesso tipo. Ad esempio, se l'origine è un contenitore BLOB, la destinazione deve essere un contenitore BLOB.

È possibile avviare un nuovo trasferimento chiamando il metodo seguente:

This method returns a TransferOperation object that represents the transfer. È possibile utilizzare l'oggetto TransferOperation per monitorare lo stato di avanzamento del trasferimento o ottenere l'ID di trasferimento. L'ID trasferimento è un identificatore univoco per il trasferimento necessario per riprendere un trasferimento o sospendere un trasferimento.

You can optionally provide an instance of TransferOptions to StartTransferAsync or ResumeTransferAsync, which applies certain configuration options to a specific transfer. Sono disponibili le opzioni di configurazione seguenti:

  • CreationMode: Configures the behavior when a transfer encounters a resource that already exists. L'impostazione predefinita è quando FailIfExists si avvia un nuovo trasferimento. Quando si riprende un trasferimento, le impostazioni predefinite possono variare. Per tutte le risorse enumerate correttamente all'avvio del trasferimento, CreationMode per impostazione predefinita viene usato il valore iniziale. Per le risorse rimanenti, viene applicato il valore predefinito normale.
  • InitialTransferSize: The size of the first range request in bytes. Le dimensioni di trasferimento singole inferiori a questo limite vengono caricate o scaricate in una singola richiesta. Transfers larger than this limit continue being downloaded or uploaded in chunks of size MaximumTransferChunkSize. Il valore predefinito è 32 MiB. Quando si riprende un trasferimento, il valore predefinito è il valore specificato al primo avvio del trasferimento.
  • MaximumTransferChunkSize: The maximum size to use for each chunk when transferring data in chunks. Il valore predefinito è 4 MiB. Quando si riprende un trasferimento, il valore predefinito è il valore specificato al primo avvio del trasferimento.
  • ProgressHandlerOptions: Optional. Opzioni per la modifica del comportamento di ProgressHandler.

Esempio: Caricare una directory locale in un contenitore BLOB

L'esempio di codice seguente illustra come avviare un nuovo trasferimento per caricare una directory locale in un contenitore 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();

Esempio: Copiare un contenitore o un BLOB

È possibile usare la libreria di spostamento dati per copiare tra due StorageResource istanze. Per le risorse BLOB, il trasferimento usa l'operazione Put BLOB From URL , che esegue una copia da server a server.

Nell'esempio di codice seguente viene illustrato come avviare un nuovo trasferimento per copiare tutti i BLOB in un contenitore BLOB di origine in un contenitore BLOB di destinazione. Il contenitore di destinazione deve esistere già. In this example, we set CreationMode to OverwriteIfExists to overwrite any destination blobs that already exist. Puoi modificare la CreationMode proprietà in base alle esigenze della tua app.

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

Nell'esempio di codice seguente viene illustrato come avviare un nuovo trasferimento per copiare un BLOB di origine in un BLOB di destinazione. In this example, we set CreationMode to OverwriteIfExists to overwrite the destination blob if it already exists. Puoi modificare la CreationMode proprietà in base alle esigenze della tua app.

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

Riprendere un trasferimento esistente

Salvando in modo permanente lo stato di avanzamento del trasferimento su disco, la libreria di spostamento dati consente di riprendere un trasferimento non riuscito prima del completamento o di essere altrimenti annullato o sospeso. Per riprendere un trasferimento, l'oggetto TransferManager deve essere configurato con StorageResourceProvider istanze in grado di riassemblare il trasferimento dai dati persistenti. You can use the ProvidersForResuming property of the TransferManagerOptions class to specify the providers.

L'esempio di codice seguente illustra come inizializzare un TransferManager oggetto in grado di riprendere un trasferimento tra il file system locale e l'archiviazione BLOB:

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

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

Per riprendere un trasferimento, chiamare il metodo seguente:

Specificare l'ID di trasferimento del trasferimento che si desidera riprendere. L'ID trasferimento è un identificatore univoco per il trasferimento restituito come parte dell'oggetto all'avvio TransferOperation del trasferimento. If you don't know the transfer ID value, you can call TransferManager.GetTransfersAsync to find the transfer and its corresponding ID.

L'esempio di codice seguente illustra come riprendere un trasferimento:

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

Note

The location of the persisted transfer data is different than the default location if TransferCheckpointStoreOptions is set as part of TransferManagerOptions. Per riprendere i trasferimenti registrati con un archivio checkpoint personalizzato, è necessario fornire le stesse opzioni dell'archivio checkpoint per l'oggetto TransferManager che riprende il trasferimento.

Monitorare lo stato di avanzamento del trasferimento

I trasferimenti possono essere monitorati e osservati tramite diversi meccanismi, a seconda delle esigenze dell'app. In questa sezione viene illustrato come monitorare lo stato di avanzamento del trasferimento usando l'oggetto TransferOperation e come monitorare un trasferimento usando TransferOptions eventi.

Esempio: Monitorare lo stato di avanzamento del trasferimento usando l'oggetto TransferOperation

È possibile monitorare lo stato di avanzamento del trasferimento usando l'oggetto TransferOperation restituito dal StartTransferAsync metodo . You can also call TransferManager.GetTransfersAsync to enumerate all transfers for a TransferManager object.

L'esempio di codice seguente illustra come scorrere tutti i trasferimenti e scrivere lo stato di ogni trasferimento in un file di log:

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 defines the status of the transfer job. TransferStatus include le proprietà seguenti:

Property Type Description
HasCompletedSuccessfully Boolean Rappresenta se il trasferimento viene completato correttamente senza errori o elementi ignorati.
HasFailedItems Boolean Rappresenta se il trasferimento contiene elementi di errore. Se impostato su true, il trasferimento ha almeno un elemento di errore. Se impostato su false, il trasferimento non presenta errori.
HasSkippedItems Boolean Rappresenta se il trasferimento contiene elementi ignorati. Se impostato su true, il trasferimento ha almeno un elemento ignorato. Se impostato su false, il trasferimento non ha attualmente elementi ignorati. It's possible to never have any items skipped if SkipIfExists isn't enabled in TransferOptions.CreationMode.
State TransferState Definisce i tipi di stato che un trasferimento può avere. See TransferState for details.

Esempio: Monitorare lo stato di avanzamento del trasferimento usando TransferOptions eventi

You can monitor transfer progress by listening for events provided by the TransferOptions class. The TransferOptions instance is passed to the StartTransferAsync method and provides events that are triggered when a transfer completes, fails, is skipped, or changes status.

Nell'esempio di codice seguente viene illustrato come restare in ascolto di un evento di completamento del trasferimento usando 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);
}

Usare i metodi di estensione per BlobContainerClient

For applications with existing code that uses the BlobContainerClient class from Azure.Storage.Blobs, you can use extension methods to start transfers directly from a BlobContainerClient object. The extension methods are provided in the BlobContainerClientExtensions class (or ShareDirectoryClientExtensions for Azure Files), and provide some of the benefits of using TransferManager with minimal code changes. In questa sezione si apprenderà come usare i metodi di estensione per eseguire trasferimenti da un BlobContainerClient oggetto .

Install the Azure.Storage.Blobs package if you don't have it already:

dotnet add package Azure.Storage.Blobs

Aggiungere le direttive seguenti using all'inizio del file di codice:

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

L'esempio di codice seguente illustra come creare un'istanza di per BlobContainerClient un contenitore BLOB denominato 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");

Nell'esempio di codice seguente viene illustrato come caricare il contenuto sample-container della directory locale in usando UploadDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Nell'esempio di codice seguente viene illustrato come scaricare il contenuto di sample-container in una directory locale usando DownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Per altre informazioni sui metodi di estensione per BlobContainerClient, vedere Estensioni in BlobContainerClient.

Next step