Biblioteca cliente de blobs de movimiento de datos de Azure Storage para .NET: versión 12.0.0-beta.3

  • Artículo

Versión del servidor: 2020-04-08, 2020-02-10, 2019-12-12, 2019-07-07 y 2020-02-02-02

Azure Storage es un servicio administrado por Microsoft que proporciona almacenamiento en la nube altamente disponible, seguro, duradero, escalable y redundante. Azure Storage incluye blobs de Azure (objetos), Azure Data Lake Storage Gen2, Azure Files y colas de Azure.

La biblioteca de movimiento de datos de Azure Storage está optimizada para cargar, descargar y copiar datos de los clientes.

La biblioteca Azure.Storage.DataMovement.Blobs proporciona infraestructura compartida por las otras bibliotecas cliente de Azure Storage.

Código | fuentePaquete (NuGet) | Documentación | de referencia de APIDocumentación | de la API RESTDocumentación del producto

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Storage para .NET que le gustaría usar con NuGet y se incluirá la Azure.Storage.DataMovement.Blobs biblioteca cliente:

dotnet add package Azure.Storage.DataMovement --prerelease
dotnet add package Azure.Storage.DataMovement.Blobs --prerelease

Requisitos previos

Necesita una suscripción de Azure y una cuenta de almacenamiento para usar este paquete.

Para crear una cuenta de almacenamiento, puede usar Azure Portal, Azure PowerShell o la CLI de Azure. A continuación se facilita un ejemplo mediante el uso de la CLI de Azure:

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

Autenticar el cliente

La biblioteca Azure.Storage.DataMovement.Blobs usa clientes del paquete Azure.Storage.Blobs para comunicarse con el servicio Azure Blob Storage. Para más información, consulte la documentación de autenticación Azure.Storage.Blobs.

Conceptos clave

La biblioteca cliente común de Azure Storage contiene una infraestructura compartida como [credenciales de autenticación][auth_credentials] y RequestFailedException.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de clienteAcceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

Ejemplos de uso de métodos de extensión BlobContainerClient para cargar y descargar directorios.

Creación de instancias de BlobContainerClient

BlobServiceClient service = new BlobServiceClient(serviceUri, credential);

BlobContainerClient container = service.GetBlobContainerClient(containerName);

Carga de un directorio local en la raíz del contenedor

DataTransfer transfer = await container.StartUploadDirectoryAsync(localPath);

await transfer.AwaitCompletion();

Carga de un directorio local en un directorio virtual en el contenedor especificando un prefijo de directorio

DataTransfer transfer = await container.StartUploadDirectoryAsync(localPath, blobDirectoryPrefix);

await transfer.AwaitCompletion();

Carga de un directorio local en un directorio virtual en el contenedor que especifica opciones más avanzadas

BlobContainerClientTransferOptions options = new BlobContainerClientTransferOptions
{
    BlobContainerOptions = new BlobStorageResourceContainerOptions
    {
        DirectoryPrefix = blobDirectoryPrefix
    },
    TransferOptions = new TransferOptions()
    {
        CreateMode = StorageResourceCreateMode.Overwrite,
    }
};

DataTransfer transfer = await container.StartUploadDirectoryAsync(localPath, options);

await transfer.AwaitCompletion();

Descarga del contenedor completo en un directorio local

DataTransfer transfer = await container.StartDownloadToDirectoryAsync(localDirectoryPath);

await transfer.AwaitCompletion();

Descargar un directorio en el contenedor especificando un prefijo de directorio

DataTransfer tranfer = await container.StartDownloadToDirectoryAsync(localDirectoryPath2, blobDirectoryPrefix);

await tranfer.AwaitCompletion();

Descarga desde el contenedor que especifica opciones más avanzadas

BlobContainerClientTransferOptions options = new BlobContainerClientTransferOptions
{
    BlobContainerOptions = new BlobStorageResourceContainerOptions
    {
        DirectoryPrefix = blobDirectoryPrefix
    },
    TransferOptions = new TransferOptions()
    {
        CreateMode = StorageResourceCreateMode.Overwrite,
    }
};

DataTransfer tranfer = await container.StartDownloadToDirectoryAsync(localDirectoryPath2, options);

await tranfer.AwaitCompletion();

Ejemplos de uso de métodos de extensión BlobContainerClient para cargar y descargar directorios.

Creación de una instancia de TransferManager con opciones

// Create BlobTransferManager with event handler in Options bag
TransferManagerOptions transferManagerOptions = new TransferManagerOptions();
TransferOptions options = new TransferOptions()
{
    MaximumTransferChunkSize = 4 * Constants.MB,
    CreateMode = StorageResourceCreateMode.Overwrite,
};
TransferManager transferManager = new TransferManager(transferManagerOptions);

Inicio de la carga desde el archivo local al blob en bloques

DataTransfer dataTransfer = await transferManager.StartTransferAsync(
    sourceResource: new LocalFileStorageResource(sourceLocalPath),
    destinationResource: new BlockBlobStorageResource(destinationBlob));
await dataTransfer.AwaitCompletion();

Aplicar opciones a la descarga de blobs en bloques

await transferManager.StartTransferAsync(
    sourceResource: new BlockBlobStorageResource(sourceBlob, new BlockBlobStorageResourceOptions()
    {
        DestinationConditions = new BlobRequestConditions(){ LeaseId = "xyz" }
    }),
    destinationResource: new LocalFileStorageResource(downloadPath2));

Iniciar carga de directorios

// Create simple transfer directory upload job which uploads the directory and the contents of that directory
DataTransfer dataTransfer = await transferManager.StartTransferAsync(
    sourceResource: new LocalDirectoryStorageResourceContainer(sourcePath),
    destinationResource: new BlobStorageResourceContainer(
        container,
        new BlobStorageResourceContainerOptions() { DirectoryPrefix = "sample-directory2" }),
    transferOptions: options);

Iniciar descarga de directorios

DataTransfer downloadDirectoryJobId2 = await transferManager.StartTransferAsync(
    sourceDirectory2,
    destinationDirectory2);

Ejemplo de registrador simple para opciones del administrador de transferencia

// Create BlobTransferManager with event handler in Options bag
TransferManagerOptions options = new TransferManagerOptions();
TransferOptions transferOptions = new TransferOptions();
transferOptions.SingleTransferCompleted += (SingleTransferCompletedEventArgs args) =>
{
    using (StreamWriter logStream = File.AppendText(logFile))
    {
        logStream.WriteLine($"File Completed Transfer: {args.SourceResource.Path}");
    }
    return Task.CompletedTask;
};

Delegación de eventos con errores simple para las opciones de transferencia de contenedores

transferOptions.TransferFailed += (TransferFailedEventArgs args) =>
{
    using (StreamWriter logStream = File.AppendText(logFile))
    {
        // Specifying specific resources that failed, since its a directory transfer
        // maybe only one file failed out of many
        logStream.WriteLine($"Exception occured with TransferId: {args.TransferId}," +
            $"Source Resource: {args.SourceResource.Path}, +" +
            $"Destination Resource: {args.DestinationResource.Path}," +
            $"Exception Message: {args.Exception.Message}");
    }
    return Task.CompletedTask;
};

Solución de problemas

Todos los servicios de Azure Storage producirán una excepción RequestFailedException con s útilesErrorCode.

Pasos siguientes

Empiece a trabajar con nuestros ejemplos de Blob DataMovement.

Contribuciones

Consulte storage CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a estas bibliotecas.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones