Compartir a través de

Transferencia de datos con la biblioteca de movimiento de datos

  • Artículo

La biblioteca de movimiento de datos de Azure Storage es una biblioteca multiplataforma de código abierto que se ha diseñado para carga, descarga y copia de alto rendimiento de blobs y archivos. La biblioteca de movimiento de datos proporciona métodos útiles que no están disponibles en la biblioteca de cliente de Azure Storage para .NET. Estos métodos permiten establecer el número de operaciones paralelas, realizar un seguimiento del progreso de la transferencia, reanudar una transferencia cancelada, etc.

La biblioteca de movimiento de datos solo está disponible para .NET y solo admite Azure Blob Storage y Azure Files. Debe tener en cuenta estas limitaciones y otros problemas conocidos al decidir si usar la biblioteca de movimiento de datos.

Si está migrando código de la antigua biblioteca Microsoft.Azure.Storage.DataMovement (versión 2.X.X) a la actual biblioteca Azure.Storage.DataMovement (versión 12.X.X), consulte la Guía de migración.

Documentos de referencia de API | Código fuente | Paquete (NuGet) | Ejemplos: Blobs / Files.Shares

Requisitos previos

Configurar el entorno

Si no tiene un proyecto existente, esta sección le muestra cómo configurar un proyecto para que funcione con la biblioteca de clientes Azure Blob Storage para .NET. Los pasos incluyen la instalación del paquete, la adición de directivas using y la creación de un objeto cliente autorizado.

Instalar paquetes

Desde el directorio de su proyecto, instale los paquetes para la biblioteca cliente de movimiento de datos de Azure Storage y la biblioteca cliente Azure Identity utilizando el comando dotnet add package. El paquete Azure.Identity es necesario para las conexiones sin contraseña a los servicios de Azure.

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

Para trabajar con la biblioteca de extensión para Azure Files, instale el paquete Azure.Storage.DataMovement.Files.Shares:

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

Agregue directivas using.

Para ejecutar los ejemplos de código de este artículo, agregue las siguientes directivas using:

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

Si usa la biblioteca de extensiones para Azure Files, agregue la siguiente directiva using:

using Azure.Storage.DataMovement.Files.Shares;

Authorization

El mecanismo de autorización debe tener los permisos necesarios para realizar operaciones de carga, descarga o copia. Para la autorización con Microsoft Entra ID (recomendado) se necesita el rol integrado de RBAC de Azure de Colaborador de datos de Storage Blob o superior.

Acerca de la biblioteca de movimiento de datos

La biblioteca de movimiento de datos de Azure Storage consta de una biblioteca cliente común y bibliotecas de extensiones para Azure Blob Storage y Azure Files. La biblioteca común proporciona la funcionalidad básica para transferir datos, mientras que las bibliotecas de extensión proporcionan funcionalidad específica para Blob Storage y Azure Files. Para obtener más información, consulte los siguientes recursos:

Cree un objeto TransferManager

TransferManager es la clase principal para iniciar y controlar todos los tipos de transferencias, incluida la carga, la descarga y la copia. En esta sección, aprenderá a crear un objeto TransferManager para trabajar con un sistema de archivos local, Blob Storage o Azure Files.

Nota:

Uno de los procedimientos recomendados para la administración de clientes del SDK de Azure es tratar a los clientes como singleton, lo que significa que una clase solo tiene un objeto a la vez. No es necesario mantener más de una instancia de un cliente para un conjunto determinado de parámetros de constructor u opciones de cliente.

En el siguiente código se muestra cómo crear un objeto TransferManager:

TransferManager transferManager = new(new TransferManagerOptions());

Opcionalmente, puede proporcionar una instancia de TransferManagerOptions al constructor, que aplica ciertas opciones de configuración a todas las transferencias iniciadas por el objeto TransferManager. Existen las siguientes opciones de configuración:

  • CheckpointStoreOptions: opcional. Define las opciones para crear un punto de control usado para guardar el estado de transferencia para que se puedan reanudar las transferencias.
  • Diagnostics: obtiene las opciones de diagnóstico del administrador de transferencias.
  • ErrorHandling: opcional. Define cómo se administran los errores durante una transferencia. El valor predeterminado es StopOnAnyFailure.
  • MaximumConcurrency: el número máximo de trabajos que se pueden usar en una transferencia paralela.
  • ProvidersForResuming: proveedores de recursos para que el administrador de transferencias los utilice al reanudar una transferencia. Espera un proveedor por cada proveedor de almacenamiento en uso. Para más información, consulte Reanudar una transferencia existente.

Cree un objeto StorageResource

StorageResource es la clase base para todos los recursos de almacenamiento, incluidos los blobs y los archivos. Para crear un objeto StorageResource, utilice una de las siguientes clases de proveedor:

Crear un objeto StorageResource para Blob Storage

El siguiente código muestra cómo crear un objeto StorageResource para contenedores de blobs y blobs mediante 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

También puede crear un objeto StorageResource utilizando un 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 una nueva transferencia

Todas las transferencias deben especificar un origen y un destino. Tanto el origen como el destino son de tipo StorageResource, que puede ser StorageResourceContainer o StorageResourceItem. Para una transferencia determinada, el origen y el destino deben ser del mismo tipo. Por ejemplo, si el origen es un contenedor de blobs, el destino debe ser un contenedor de blobs.

Puede iniciar una nueva transferencia llamando al siguiente método:

Este método devuelve un objeto TransferOperation que representa la transferencia. Puede usar el objeto TransferOperation para supervisar el progreso de la transferencia u obtener el id. de transferencia. El id. de transferencia es un identificador único para la transferencia necesaria para reanudar o pausar una transferencia.

Opcionalmente, puede proporcionar una instancia de TransferOptions a StartTransferAsync o ResumeTransferAsync, que aplica ciertas opciones de configuración a una transferencia específica. Existen las siguientes opciones de configuración:

  • CreationMode: configura el comportamiento cuando una transferencia encuentra un recurso que ya existe. El valor predeterminado es FailIfExists al iniciar una nueva transferencia. Al reanudar una transferencia, los valores predeterminados pueden variar. Para todos los recursos enumerados correctamente cuando se inició la transferencia, el valor predeterminado CreationMode es el valor inicial usado. Para los recursos restantes, se aplica el valor predeterminado normal.
  • InitialTransferSize: tamaño de la primera solicitud de intervalo en bytes. Los tamaños de transferencia únicos menores que este límite se cargan o descargan en una sola solicitud. Las transferencias superiores a este límite siguen descargándose o cargándose en fragmentos de tamaño MaximumTransferChunkSize. El valor predeterminado es 32 MiB. Cuando reanuda una transferencia, el valor predeterminado es el valor especificado cuando se inició la transferencia por primera vez.
  • MaximumTransferChunkSize: tamaño máximo que se va a usar para cada fragmento al transferir datos en fragmentos. El valor predeterminado es 4 MiB. Cuando reanuda una transferencia, el valor predeterminado es el valor especificado cuando se inició la transferencia por primera vez.
  • ProgressHandlerOptions: opcional. Opciones para cambiar el comportamiento de ProgressHandler.

Ejemplo: Cargar un directorio local en un contenedor de blobs

El siguiente ejemplo de código muestra cómo iniciar una nueva transferencia para cargar un directorio local en un contenedor de blobs:

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

Ejemplo: Copiar un contenedor o un blob

Puede usar la biblioteca de movimiento de datos para copiar entre dos instancias StorageResource. Para los recursos blob, la transferencia utiliza la operación Put Blob From URL, que realiza una copia de servidor a servidor.

El siguiente ejemplo de código muestra cómo iniciar una nueva transferencia para copiar todos los blobs de un contenedor de blobs de origen a un contenedor de blobs de destino. El contenedor de destino ya debe existir. En este ejemplo, establecemos CreationMode en OverwriteIfExists para sobrescribir los blobs de destino que ya existen. Puedes ajustar la propiedad CreationMode en función de las necesidades de la aplicación.

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

El siguiente ejemplo de código muestra cómo iniciar una nueva transferencia para copiar un blob de origen a un blob de destino. En este ejemplo, establecemos CreationMode en OverwriteIfExists para sobrescribir el blob de destino si ya existe. Puedes ajustar la propiedad CreationMode en función de las necesidades de la aplicación.

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

Reanudar una transferencia existente

Al conservar el progreso de la transferencia en el disco, la biblioteca de movimiento de datos permite reanudar una transferencia que falló antes de completarse, o que se canceló o se puso en pausa. Para reanudar una transferencia, el objeto TransferManager debe configurarse con instancias StorageResourceProvider que puedan volver a ensamblar la transferencia de los datos persistentes. Puede usar la propiedad ProvidersForResuming de la clase TransferManagerOptions para especificar los proveedores.

El siguiente ejemplo de código muestra cómo inicializar un objeto TransferManager capaz de reanudar una transferencia entre el sistema de archivos local y Blob Storage:

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

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

Para reanudar una transferencia, llame al siguiente método:

Proporcione el id. de transferencia de la transferencia que desea reanudar. El id. de la transferencia es un identificador único para la transferencia que se devuelve como parte del objeto TransferOperation cuando se inicia la transferencia. Si no conoce el valor del id. de transferencia, puede llamar a TransferManager.GetTransfersAsync para buscar la transferencia y su id. correspondiente.

El siguiente ejemplo de código muestra cómo reanudar una transferencia:

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

Nota:

La ubicación de los datos de transferencia persistentes es diferente de la ubicación predeterminada si TransferCheckpointStoreOptions se establece como parte de TransferManagerOptions. Para reanudar las transferencias registradas con un almacén de puntos de control personalizado, debe proporcionar las mismas opciones de almacén de puntos de control para el objeto TransferManager que reanuda la transferencia.

Supervisar el progreso de la transferencia

Las transferencias pueden supervisarse y observarse a través de varios mecanismos, en función de las necesidades de su aplicación. En esta sección, aprenderá a supervisar el progreso de la transferencia mediante el objeto TransferOperation y a supervisar una transferencia mediante eventos de TransferOptions.

Ejemplo: Supervisión del progreso de la transferencia mediante el objeto TransferOperation

Puede supervisar el progreso de la transferencia mediante el objeto TransferOperation devuelto por el método StartTransferAsync. También puede llamar a TransferManager.GetTransfersAsync para enumerar todas las transferencias de un objeto TransferManager.

El siguiente ejemplo de código muestra cómo iterar sobre todas las transferencias y escribir el estado de cada transferencia en un archivo de registro:

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 el estado del trabajo de transferencia. TransferStatus incluye las siguientes propiedades:

Propiedad Tipo Descripción
HasCompletedSuccessfully Booleano Representa si la transferencia se completa correctamente sin errores ni elementos omitidos.
HasFailedItems Booleano Representa si la transferencia tiene algún elemento de error. Si se establece en true, la transferencia tiene al menos un elemento de error. Si se establece en false, la transferencia no tiene errores actualmente.
HasSkippedItems Booleano Representa si la transferencia tiene elementos omitidos. Si se establece en true, la transferencia tiene al menos un elemento omitido. Si se establece en false, la transferencia no tiene actualmente elementos omitidos. Es posible que nunca se omita ningún elemento si SkipIfExists no está habilitado en TransferOptions.CreationMode.
State TransferState Define los tipos del estado que puede tener una transferencia. Consulte TransferState para obtener más información.

Ejemplo: Supervisión del progreso de la transferencia mediante eventos TransferOptions

Puede supervisar el progreso de la transferencia escuchando los eventos proporcionados por la clase TransferOptions. La instancia TransferOptions se pasa al método StartTransferAsync y proporciona eventos que se desencadenan cuando una transferencia se completa, produce un error, se omite o cambia de estado.

El siguiente ejemplo de código muestra cómo escuchar un evento de finalización de transferencia utilizando 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);
}

Uso de métodos de extensión para BlobContainerClient

En el caso de las aplicaciones con código existente que usa la clase BlobContainerClient de Azure.Storage.Blobs, puede usar métodos de extensión para iniciar transferencias directamente desde un objeto BlobContainerClient. Los métodos de extensión se proporcionan en la clase BlobContainerClientExtensions (o ShareDirectoryClientExtensions para Azure Files), y proporcionan algunas de las ventajas del uso de TransferManager con cambios mínimos en el código. En esta sección, aprenderá a usar los métodos de extensión para realizar transferencias desde un objeto BlobContainerClient.

Instale el paquete Azure.Storage.Blobs si aún no lo tiene:

dotnet add package Azure.Storage.Blobs

Agregue las siguientes directivas using al principio del archivo de código:

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

El siguiente ejemplo de código muestra cómo instanciar un BlobContainerClient para un contenedor de blobs llamado 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");

El siguiente ejemplo de código muestra cómo cargar el contenido de un directorio local a sample-container utilizando UploadDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

En el ejemplo de código siguiente se muestra cómo descargar el contenido de sample-container en un directorio local mediante DownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Para más información sobre los métodos de extensión para BlobContainerClient, consulte Extensiones en BlobContainerClient.

Paso siguiente