Condividi tramite

Trasferire dati con la libreria di Spostamento dati

  • Articolo

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. È 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.

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

Prerequisiti

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.

Installare i pacchetti

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 . 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 seguenteusing:

using Azure.Storage.DataMovement.Files.Shares;

Autorizzazione

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 è 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 TransferManager oggetto per lavorare con un file system locale, un archivio BLOB o un File di Azure.

Nota

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

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 utilizzato per salvare lo stato di trasferimento in modo che i trasferimenti possano essere ripresi.
  • Diagnostica: ottiene le opzioni di diagnostica di Transfer Manager.
  • ErrorHandling: facoltativo. Definisce la modalità di gestione degli errori durante un trasferimento. Il valore predefinito è StopOnAnyFailure.
  • MaximumConcurrency: numero massimo di ruoli di lavoro che possono essere usati in un trasferimento 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 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

È 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

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:

Questo metodo restituisce un oggetto TransferOperation che rappresenta il trasferimento. È 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.

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. 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: dimensioni della prima richiesta di intervallo in byte. Le dimensioni di trasferimento singole 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 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 questo esempio viene impostato CreationMode su OverwriteIfExists per sovrascrivere tutti i BLOB di destinazione già esistenti. 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 questo esempio viene impostato CreationMode su OverwriteIfExists per sovrascrivere il BLOB di destinazione, se già esistente. 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. È possibile utilizzare la ProvidersForResuming proprietà della classe TransferManagerOptions per specificare i provider.

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

Nota

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

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 definisce lo stato del processo di trasferimento. TransferStatus include le proprietà seguenti:

Proprietà Type Descrizione
HasCompletedSuccessfully Boolean Rappresenta se il trasferimento viene completato correttamente senza errori o elementi ignorati.
HasFailedItems Booleano 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 Booleano 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. È possibile non avere mai elementi ignorati se SkipIfExists non è abilitato in TransferOptions.CreationMode.
State TransferState Definisce i tipi di stato che un trasferimento può avere. Per informazioni dettagliate, vedere TransferState .

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

È 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 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

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 si apprenderà come usare i metodi di estensione per eseguire trasferimenti da un BlobContainerClient oggetto .

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

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.

Passaggio successivo