Condividi tramite

Trasferire dati con la libreria di Spostamento dati

La libreria Spostamento dati Archiviazione di Azure è una libreria open source multipiattaforma progettata per il caricamento, il download e la copia di BLOB e file con prestazioni elevate. La libreria Spostamento dati fornisce metodi pratici che non sono disponibili nella libreria client di 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. È consigliabile prendere in considerazione queste limitazioni e altri problemi noti quando si decide se usare la libreria di spostamento dati.

Se si esegue la migrazione del codice dalla libreria Microsoft.Azure.Storage.DataMovement precedente (versione 2.X.X) alla libreria Azure.Storage.DataMovement corrente (versione 12.X.X), vedere la guida alla migrazione.

Pacchetto (NuGet) | codice sorgente | documentazione di riferimento API | Esempi: BLOB / Files.Shares

Prerequisites

Configurare l'ambiente

Se non è disponibile 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.

Installare i pacchetti

Dalla directory del progetto installare i pacchetti per la libreria client di spostamento dati di Archiviazione di Azure e la libreria client di Identità di Azure usando il comando dotnet add package. Il pacchetto Azure.Identity è necessario per le connessioni senza password ai servizi di Azure.

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

Per usare la libreria di estensioni per File di Azure, installare il pacchetto Azure.Storage.DataMovement.Files.Shares :

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 seguente using:

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 Spostamento dati di Archiviazione di Azure è costituita da una libreria client comune e da librerie di estensione per Archiviazione BLOB di Azure e File di Azure. La libreria comune fornisce la funzionalità di base per il trasferimento dei dati, mentre le librerie di estensione forniscono funzionalità specifiche per Archiviazione BLOB e File di Azure. Per altre informazioni, vedere le risorse seguenti:

Creare un oggetto TransferManager

TransferManager è la classe principale per l'avvio e il controllo di tutti i tipi di trasferimenti, tra cui caricamento, download e copia. In questa sezione viene illustrato come creare un oggetto TransferManager da usare con un file system locale, un'archiviazione BLOB o un File di Azure.

Note

Una procedura consigliata per la gestione client di Azure SDK consiste nel trattare 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 oggetto TransferManager:

TransferManager transferManager = new(new TransferManagerOptions());

Facoltativamente, è possibile specificare un'istanza di TransferManagerOptions al costruttore, che applica determinate opzioni di configurazione a tutti i trasferimenti avviati dall'oggetto TransferManager . Sono disponibili le opzioni di configurazione seguenti:

  • CheckpointStoreOptions: facoltativo. Definisce le opzioni per la creazione di un checkpoint usato per salvare lo stato di trasferimento in modo che i trasferimenti possano essere ripresi.
  • Diagnostica: ottiene le opzioni di diagnostica di Transfer Manager.
  • ErrorMode: facoltativo. Definisce la modalità di gestione degli errori durante un trasferimento. Il valore predefinito è StopOnAnyFailure.
  • MaximumConcurrency: numero massimo di lavoratori che possono essere usati in un trasferimento in parallelo.
  • ProvidersForResuming: provider di risorse che il gestore di trasferimento deve usare per riprendere un trasferimento. Prevede un provider per ogni provider di archiviazione in uso. Per altre informazioni, vedere Riprendere un trasferimento esistente.

Creare un oggetto StorageResource

StorageResource è la classe di base per tutte le risorse di archiviazione, inclusi BLOB e file. Per creare un oggetto StorageResource, usare una delle classi di provider seguenti:

Creare un oggetto StorageResource per l'archiviazione BLOB

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

È anche possibile creare un StorageResource oggetto usando un oggetto client da 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

Avvia 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:

Questo metodo restituisce un oggetto TransferOperation che rappresenta il trasferimento. È possibile usare l'oggetto TransferOperation per monitorare lo stato di avanzamento del trasferimento o ottenere l'ID trasferimento. L'ID trasferimento è un identificatore univoco per il trasferimento necessario per riprendere o sospendere un trasferimento.

Facoltativamente, è possibile specificare un'istanza di TransferOptions a StartTransferAsync o ResumeTransferAsync, che applica determinate opzioni di configurazione a un trasferimento specifico. Sono disponibili le opzioni di configurazione seguenti:

  • CreationMode: configura il comportamento quando un trasferimento rileva una risorsa già esistente. Per impostazione predefinita, FailIfExists viene avviato quando 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 tutte le risorse rimanenti, viene applicato il valore predefinito normale.
  • InitialTransferSize: dimensioni della prima richiesta di intervallo in byte. Le dimensioni di trasferimento singolo inferiori a questo limite vengono caricate o scaricate in una singola richiesta. I trasferimenti superiori a questo limite continuano a essere scaricati o caricati in blocchi di dimensioni MaximumTransferChunkSize. Il valore predefinito è 32 MiB. Quando si riprende un trasferimento, il valore predefinito è il valore specificato al primo avvio del trasferimento.
  • MaximumTransferChunkSize: dimensione massima da usare per ogni blocco durante il trasferimento dei dati in blocchi. Il valore predefinito è 4 MiB. Quando si riprende un trasferimento, il valore predefinito è il valore specificato al primo avvio del trasferimento.
  • ProgressHandlerOptions: facoltativo. 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 eseguire la copia tra due istanze StorageResource. 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 questo esempio viene impostato CreationMode su OverwriteIfExists per sovrascrivere tutti i BLOB di destinazione già esistenti. È possibile modificare la proprietà CreationMode in base alle esigenze dell'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();

L'esempio di codice seguente illustra come avviare un nuovo trasferimento per copiare un BLOB di origine in un BLOB di destinazione. In questo esempio, impostiamo CreationMode su OverwriteIfExists per sovrascrivere il BLOB di destinazione se esiste già. È possibile modificare la proprietà CreationMode in base alle esigenze dell'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 che è stato annullato o sospeso in altro modo. Per riprendere un trasferimento, l'oggetto TransferManager deve essere configurato con istanze StorageResourceProvider in grado di riassemblare il trasferimento dai dati persistenti. È possibile utilizzare la ProvidersForResuming proprietà della classe TransferManagerOptions per specificare i provider.

L'esempio di codice seguente illustra come inizializzare un oggetto TransferManagerin 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 TransferOperation all'avvio del trasferimento. Se non si conosce il valore dell'ID di trasferimento, è possibile chiamare TransferManager.GetTransfersAsync per trovare il trasferimento e il relativo ID corrispondente.

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

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

Note

Il percorso dei dati di trasferimento permanente è diverso dal percorso predefinito se TransferCheckpointStoreOptions è impostato come parte di TransferManagerOptions. Per riprendere i trasferimenti registrati con un archivio checkpoint personalizzato, è necessario specificare 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 tramite gli eventi TransferOptions.

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 metodo StartTransferAsync. È anche possibile chiamare TransferManager.GetTransfersAsync per enumerare tutti i trasferimenti per un TransferManager oggetto .

Nell'esempio di codice seguente viene illustrato come eseguire l'iterazione su 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 definisce lo stato del processo di trasferimento. 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 contiene almeno un elemento di errore. Se impostato su false, il trasferimento per il momento non presenta errori.
HasSkippedItems Boolean Rappresenta se il trasferimento contiene elementi ignorati. Se impostato su true, per il trasferimento è stato ignorato almeno un elemento. Se impostato su false, il trasferimento per il momento non contiene elementi ignorati. È possibile non avere mai elementi ignorati se SkipIfExists non è abilitato in TransferOptions.CreationMode.
State TransferState Definisce i tipi dello stato che può avere un trasferimento. Per informazioni dettagliate, vedere TransferState .

Esempio: monitorare lo stato di avanzamento del trasferimento usando gli eventi TransferOptions

È possibile monitorare lo stato di avanzamento del trasferimento ascoltando gli eventi forniti dalla classe TransferOptions . L'istanza TransferOptions viene passata al StartTransferAsync metodo e fornisce eventi che vengono attivati quando un trasferimento viene completato, ha esito negativo, viene ignorato o cambia lo stato.

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

Per le applicazioni con codice esistente che usa la BlobContainerClient classe di Azure.Storage.Blobs, è possibile usare i metodi di estensione per avviare i trasferimenti direttamente da un BlobContainerClient oggetto . I metodi di estensione vengono forniti nella classe BlobContainerClientExtensions (o ShareDirectoryClientExtensions per File di Azure) e offrono alcuni dei vantaggi dell'uso TransferManager con modifiche minime al codice. In questa sezione viene illustrato come usare i metodi di estensione per eseguire trasferimenti da un oggetto BlobContainerClient.

Installare il pacchetto Azure.Storage.Blobs se non è già disponibile:

dotnet add package Azure.Storage.Blobs

Aggiungere le direttive using seguenti 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 BlobContainerClient per 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 con 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 tramite DownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Per altre informazioni sui metodi di estensione per BlobContainerClient, vedere Extensions on BlobContainerClient.

Passo successivo

  • Last updated on