Partilhar via

Transferir dados com a biblioteca do Movimento de Dados

  • Artigo

A biblioteca de Movimentação de Dados de Armazenamento do Azure é uma biblioteca de código aberto multiplataforma projetada para upload, download e cópia de blobs e arquivos de alto desempenho. A biblioteca de Movimentação de Dados fornece métodos convenientes que não estão disponíveis na biblioteca de cliente do Armazenamento do Azure para .NET. Esses métodos permitem que você defina o número de operações paralelas, acompanhe o progresso da transferência, retome uma transferência cancelada e muito mais.

A biblioteca de Movimentação de Dados só está disponível para .NET e suporta apenas o Armazenamento de Blobs do Azure e os Arquivos do Azure. Você deve considerar essas limitações e outros problemas conhecidos ao decidir se deseja usar a biblioteca de movimentação de dados.

Se você estiver migrando código da biblioteca Microsoft.Azure.Storage.DataMovement mais antiga (versão 2.X.X) para a biblioteca atual Azure.Storage.DataMovement (versão 12.X.X), consulte o Guia de migração.

Documentos de referência da API Pacote de código-fonte | | (NuGet) | Exemplos: Blobs / Files.Shares

Pré-requisitos

Configurar o ambiente

Se você não tiver um projeto existente, esta seção mostra como configurar um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para .NET. As etapas incluem a instalação do pacote, a adição de using diretivas e a criação de um objeto de cliente autorizado.

Instalar pacotes

No diretório do projeto, instale pacotes para a biblioteca de cliente do Movimento de Dados de Armazenamento do Azure e a biblioteca de cliente do Azure Identity usando o dotnet add package comando. O pacote Azure.Identity é necessário para conexões sem senha com os serviços do Azure.

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

Para trabalhar com a biblioteca de extensões para Arquivos do Azure, instale o pacote Azure.Storage.DataMovement.Files.Shares :

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

Adicionar using diretivas

Para executar os exemplos de código neste artigo, adicione as seguintes using diretivas:

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

Se você estiver usando a biblioteca de extensões para Arquivos do Azure, adicione a seguinte using diretiva:

using Azure.Storage.DataMovement.Files.Shares;

Autorização

O mecanismo de autorização deve ter as permissões necessárias para executar operações de upload, download ou cópia. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna do RBAC do Azure RBAC Storage Blob Data Contributor ou superior.

Sobre a biblioteca Data Movement

A biblioteca de Movimentação de Dados do Armazenamento do Azure consiste em uma biblioteca de cliente comum e bibliotecas de extensão para o Armazenamento de Blobs do Azure e Arquivos do Azure. A biblioteca comum fornece a funcionalidade principal para transferir dados, enquanto as bibliotecas de extensão fornecem funcionalidade específica para Armazenamento de Blob e Arquivos do Azure. Para saber mais, consulte os seguintes recursos:

Criar um TransferManager objeto

TransferManager é a classe principal para iniciar e controlar todos os tipos de transferências, incluindo upload, download e cópia. Nesta seção, você aprenderá a criar um TransferManager objeto para trabalhar com um sistema de arquivos local, Armazenamento de Blob ou Arquivos do Azure.

Nota

Uma prática recomendada para o gerenciamento de clientes do SDK do Azure é tratar um cliente como um singleton, o que significa que uma classe tem apenas um objeto de cada vez. Não há necessidade de manter mais de uma instância de um cliente para um determinado conjunto de parâmetros do construtor ou opções do cliente.

O código a seguir mostra como criar um TransferManager objeto:

TransferManager transferManager = new(new TransferManagerOptions());

Opcionalmente, você pode fornecer uma instância de TransferManagerOptions para o construtor, que aplica determinadas opções de configuração a todas as transferências iniciadas pelo TransferManager objeto. As seguintes opções de configuração estão disponíveis:

Criar um StorageResource objeto

StorageResource é a classe base para todos os recursos de armazenamento, incluindo blobs e arquivos. Para criar um StorageResource objeto, use uma das seguintes classes de provedor:

Criar um StorageResource objeto para o Armazenamento de Blobs

O código a seguir mostra como criar um StorageResource objeto para contêineres de blob e blobs usando um 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

Você também pode criar um StorageResource objeto usando um objeto cliente de 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

Iniciar uma nova transferência

Todas as transferências precisam especificar uma origem e um destino. Tanto a origem quanto o destino são do tipo StorageResource, que pode ser um ou StorageResourceContainerStorageResourceItem. Para uma dada transferência, a origem e o destino devem ser da mesma natureza. Por exemplo, se a origem for um contêiner de blob, o destino deverá ser um contêiner de blob.

Você pode iniciar uma nova transferência chamando o seguinte método:

Esse método retorna um objeto TransferOperation que representa a transferência. Você pode usar o TransferOperation objeto para monitorar o progresso da transferência ou obter o ID da transferência. O ID de transferência é um identificador exclusivo para a transferência necessária para retomar uma transferência ou pausar uma transferência.

Opcionalmente, você pode fornecer uma instância de TransferOptions para StartTransferAsync ou ResumeTransferAsync, que aplica determinadas opções de configuração a uma transferência específica. As seguintes opções de configuração estão disponíveis:

  • CreationMode: Configura o comportamento quando uma transferência encontra um recurso que já existe. O padrão é ao FailIfExists iniciar uma nova transferência. Quando você retoma uma transferência, os padrões podem variar. Para todos os recursos enumerados com êxito quando a transferência foi iniciada, CreationMode o padrão é o valor inicial usado. Para quaisquer recursos restantes, aplica-se o valor padrão regular.
  • InitialTransferSize: O tamanho da primeira solicitação de intervalo em bytes. Tamanhos de transferência únicos menores que esse limite são carregados ou baixados em uma única solicitação. Transferências maiores que esse limite continuam sendo baixadas ou carregadas em partes de tamanho MaximumTransferChunkSize. O valor padrão é 32 MiB. Quando você retoma uma transferência, o valor padrão é o valor especificado quando a transferência foi iniciada pela primeira vez.
  • MaximumTransferChunkSize: O tamanho máximo a ser usado para cada bloco ao transferir dados em partes. O valor padrão é 4 MiB. Quando você retoma uma transferência, o valor padrão é o valor especificado quando a transferência foi iniciada pela primeira vez.
  • ProgressHandlerOptions: Opcional. Opções para alterar o comportamento do ProgressHandler.

Exemplo: carregar um diretório local para um contêiner de blob

O exemplo de código a seguir mostra como iniciar uma nova transferência para carregar um diretório local para um contêiner de 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();

Exemplo: Copiar um contêiner ou blob

Você pode usar a biblioteca de movimentação de dados para copiar entre duas StorageResource instâncias. Para recursos de blob, a transferência usa a operação Put Blob From URL , que executa uma cópia de servidor para servidor.

O exemplo de código a seguir mostra como iniciar uma nova transferência para copiar todos os blobs em um contêiner de blob de origem para um contêiner de blob de destino. O contêiner de destino já deve existir. Neste exemplo, definimos CreationMode para OverwriteIfExists substituir quaisquer blobs de destino que já existam. Você pode ajustar a CreationMode propriedade com base nas necessidades do seu aplicativo.

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

O exemplo de código a seguir mostra como iniciar uma nova transferência para copiar um blob de origem para um blob de destino. Neste exemplo, definimos CreationMode para OverwriteIfExists substituir o blob de destino se ele já existir. Você pode ajustar a CreationMode propriedade com base nas necessidades do seu aplicativo.

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

Retomar uma transferência existente

Ao persistir o progresso da transferência para o disco, a biblioteca de Movimentação de Dados permite retomar uma transferência que falhou antes da conclusão ou que foi cancelada ou pausada. Para retomar uma transferência, o TransferManager objeto deve ser configurado com StorageResourceProvider instâncias capazes de remontar a transferência a partir dos dados persistentes. Você pode usar a ProvidersForResuming propriedade da classe TransferManagerOptions para especificar os provedores.

O exemplo de código a seguir mostra como inicializar um TransferManager objeto capaz de retomar uma transferência entre o sistema de arquivos local e o Armazenamento de Blob:

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

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

Para retomar uma transferência, chame o seguinte método:

Forneça o ID de transferência da transferência que você deseja retomar. O ID de transferência é um identificador exclusivo para a transferência que é retornada como parte do TransferOperation objeto quando a transferência é iniciada. Se você não souber o valor da ID de transferência, poderá ligar para TransferManager.GetTransfersAsync para encontrar a transferência e sua ID correspondente.

O exemplo de código a seguir mostra como retomar uma transferência:

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

Nota

O local dos dados de transferência persistentes será diferente do local padrão se TransferCheckpointStoreOptions estiver definido como parte do TransferManagerOptions. Para retomar as transferências registradas com um armazenamento de ponto de verificação personalizado, você deve fornecer as mesmas opções de armazenamento de ponto de verificação para o TransferManager objeto que retoma a transferência.

Monitorar o progresso da transferência

As transferências podem ser monitoradas e observadas por meio de vários mecanismos, dependendo das necessidades do seu aplicativo. Nesta seção, você aprenderá como monitorar o progresso da transferência usando o TransferOperation objeto e como monitorar uma transferência usando TransferOptions eventos.

Exemplo: monitorar o progresso da transferência usando o TransferOperation objeto

Você pode monitorar o progresso da transferência usando o TransferOperationStartTransferAsync objeto retornado pelo método. Você também pode chamar TransferManager.GetTransfersAsync para enumerar todas as transferências de um TransferManager objeto.

O exemplo de código a seguir mostra como iterar em todas as transferências e gravar o estado de cada transferência em um arquivo de 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 define o status do trabalho de transferência. TransferStatus Inclui as seguintes propriedades:

Propriedade Type Descrição
HasCompletedSuccessfully Booleano Representa se a transferência for concluída com êxito sem qualquer falha ou itens ignorados.
HasFailedItems Boolean Representa se a transferência tem algum item de falha. Se definido como true, a transferência tem pelo menos um item de falha. Se definido como false, a transferência atualmente não tem falhas.
HasSkippedItems Boolean Representa se a transferência tem itens ignorados. Se definido como true, a transferência tem pelo menos um item ignorado. Se definido como false, a transferência atualmente não tem itens ignorados. É possível nunca ter nenhum item ignorado se SkipIfExists não estiver ativado em TransferOptions.CreationMode.
State Estado de transferência Define os tipos de estado que uma transferência pode ter. Consulte TransferState para obter detalhes.

Exemplo: Monitorar o progresso da transferência usando TransferOptions eventos

Você pode monitorar o progresso da transferência ouvindo os eventos fornecidos pela classe TransferOptions . A TransferOptions instância é passada para o método e fornece eventos que são acionados quando uma transferência é concluída, falha, ignorada ou altera o StartTransferAsync status.

O exemplo de código a seguir mostra como escutar um evento de conclusão de transferência 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);
}

Use métodos de extensão para BlobContainerClient

Para aplicativos com código existente que usa a BlobContainerClient classe de Azure.Storage.Blobs, você pode usar métodos de extensão para iniciar transferências diretamente de um BlobContainerClient objeto. Os métodos de extensão são fornecidos na classe BlobContainerClientExtensions (ou ShareDirectoryClientExtensions para Arquivos do Azure) e fornecem alguns dos benefícios do uso TransferManager com alterações mínimas de código. Nesta seção, você aprenderá a usar os métodos de extensão para executar transferências de um BlobContainerClient objeto.

Instale o pacote Azure.Storage.Blobs se ainda não o tiver:

dotnet add package Azure.Storage.Blobs

Adicione as seguintes using diretivas à parte superior do arquivo de código:

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

O exemplo de código a seguir mostra como instanciar um BlobContainerClient para um contêiner de blob chamado 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");

O exemplo de código a seguir mostra como carregar o conteúdo do diretório local para sample-container usar UploadDirectoryAsynco :

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

await transfer.WaitForCompletionAsync();

O exemplo de código a seguir mostra como baixar o conteúdo de sample-container para um diretório local usando DownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Para saber mais sobre os métodos de extensão do BlobContainerClient, consulte Extensões em BlobContainerClient.

Próximo passo