Compartir a través de

Cargar un blob con .NET

  • Artículo

En este artículo se muestra cómo cargar un blob mediante la biblioteca de cliente Azure Storage para .NET. Puede cargar datos en un blob en bloques desde una ruta de acceso de archivo, una secuencia, un objeto binario o una cadena de texto. También puede abrir un flujo de blobs y escribir en él, o cargar blobs grandes en bloques.

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. Para más información, consulte Introducción a Azure Blob Storage y .NET.

Instalar paquetes

En el directorio del proyecto, instale los paquetes para las bibliotecas cliente de Azure Blob Storage y Azure Identity mediante 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.Blobs
dotnet add package Azure.Identity

Agregue directivas using.

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

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Algunos ejemplos de código de este artículo pueden requerir directivas using adicionales.

Creación de un objeto de cliente

Para conectar una aplicación a Blob Storage, cree una instancia de BlobServiceClient. En el ejemplo siguiente se muestra cómo crear un objeto de cliente mediante DefaultAzureCredential para la autorización:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Puede registrar un cliente de servicio para la inserción de dependencias en una aplicación .NET.

También puede crear objetos de cliente para contenedores o blobs específicos. Para obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Authorization

El mecanismo de autorización debe tener los permisos necesarios para actualizar un blob. 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. Para más información, consulte la guía de autorización para Put Blob (API REST) y Put Block (API REST).

Carga de datos en un blob en bloques

Puede usar cualquiera de los siguientes métodos para cargar datos en un blob de bloques:

Cuando se utilizan estos métodos de carga, la biblioteca cliente puede llamar a Put Blob o una serie de llamadas Put Block seguidas de Put Block List. Este comportamiento depende del tamaño total del objeto y de cómo se establezcan las opciones de transferencia de datos.

Para abrir un flujo en Blob Storage y escribir en ese flujo, use cualquiera de los siguientes métodos:

Carga de un blob en bloques desde una ruta de acceso de archivo local

El siguiente ejemplo carga un blob de bloque desde una ruta de archivo local:

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

Carga de un blob en bloques desde una secuencia

El siguiente ejemplo carga un blob de bloque mediante la creación de un objeto Stream y la carga del flujo.

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

Cargar un blob en bloques desde un objeto BinaryData

El siguiente ejemplo carga un blob de bloque desde un objeto BinaryData.

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

Carga de un blob en bloques desde una cadena

El siguiente ejemplo carga un blob de bloque desde una cadena:

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

Carga de una secuencia en Blob Storage

¿Puede abrir un flujo en Blob Storage y escribir en él. El siguiente ejemplo crea un archivo zip en el Blob Storage y escribe archivos en él. En lugar de compilar un archivo ZIP en la memoria local, solo un archivo a la vez está en memoria.

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

Carga de un blob en bloques con opciones de configuración

Puede definir las opciones de configuración de la biblioteca cliente al cargar un blob. Estas opciones se pueden ajustar para mejorar el rendimiento, mejorar la confiabilidad y optimizar los costes. En los ejemplos de código siguientes se muestra cómo usar BlobUploadOptions para definir opciones de configuración al llamar a un método de carga.

Especificación de opciones de transferencia de datos al cargar

Puede configurar los valores de StorageTransferOptions para mejorar el rendimiento de las operaciones de transferencia de datos. En el ejemplo de código siguiente se muestra cómo establecer valores para StorageTransferOptions e incluir las opciones como parte de una instancia de BlobUploadOptions. Los valores proporcionados en este ejemplo no están diseñados para ser una recomendación. Para ajustar correctamente estos valores, debe tener en cuenta las necesidades específicas de la aplicación.

public static async Task UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Para obtener más información sobre cómo ajustar las opciones de transferencia de datos, consulte Ajuste del rendimiento para cargas y descargas con .NET.

Especificar opciones de validación de transferencia en la carga

Puede especificar opciones de validación de transferencia para ayudar a garantizar que los datos se cargan correctamente y no se han alterado durante el tránsito. Las opciones de validación de transferencia se pueden definir en el nivel de cliente mediante BlobClientOptions, que aplica opciones de validación a todos los métodos a los que se llama desde una instancia de BlobClient.

También puede invalidar las opciones de validación de transferencia en el nivel de método mediante BlobUploadOptions. En el ejemplo de código siguiente se muestra cómo crear un objeto BlobUploadOptions y especificar un algoritmo para generar una suma de comprobación. A continuación, el servicio usa la suma de comprobación para comprobar la integridad de los datos del contenido cargado.

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

En la tabla siguiente se muestran las opciones disponibles para el algoritmo de suma de comprobación, tal y como se define en StorageChecksumAlgorithm:

Nombre valor Descripción
Auto 0 Se recomienda su uso. Permite que la biblioteca elija un algoritmo. Diferentes versiones de biblioteca pueden elegir algoritmos diferentes.
None 1 No hay ningún algoritmo seleccionado. No calcule ni solicite sumas de comprobación.
MD5 2 Algoritmo hash MD5 estándar.
StorageCrc64 3 CRC de 64 bits personalizado de Azure Storage.

Nota:

Si la suma de comprobación especificada en la solicitud no coincide con la suma de comprobación calculada por el servicio, se produce un error en la operación de carga. La operación no se reintenta cuando se usa una directiva de reintento predeterminada. En .NET, se produce un elemento RequestFailedException con el código de estado 400 y el código de error Md5Mismatch o Crc64Mismatch, en función del algoritmo que se use.

Carga con etiquetas de índice

Las etiquetas de índice de blobs clasifican los datos de la cuenta de almacenamiento mediante atributos de etiqueta clave-valor. Estas etiquetas se indexan y se exponen automáticamente como un índice multidimensional que se puede buscar para encontrar fácilmente los datos. Puede agregar etiquetas a una instancia de BlobUploadOptions y pasar esa instancia al método UploadAsync.

En el ejemplo siguiente se carga un blob en bloques con etiquetas de índice:

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

Establecimiento del nivel de acceso de un blob durante la carga

Puede establecer el nivel de acceso de un blob en la carga mediante la clase BlobUploadOptions. En el ejemplo de código siguiente se muestra cómo establecer el nivel de acceso al cargar un blob:

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Solo se permite establecer el nivel de acceso en los blobs en bloques. Puede establecer el nivel de acceso de un blob en bloques en Hot, Cool, Cold o Archive. Para establecer el nivel de acceso en Cold, debe usar la versión mínima de la biblioteca cliente 12.15.0.

Si desea obtener más información sobre los niveles de acceso, consulte Información general sobre los niveles de acceso.

Cargar un blob en bloques mediante la preparación de bloques y la confirmación

Puede tener un mayor control sobre cómo dividir las cargas en bloques si pone en escena manualmente bloques individuales de datos. Cuando todos los bloques que son un blob se han almacenado de manera provisional, puede confirmarlos en Blob Storage. Puede usar este método para mejorar el rendimiento cargando bloques en paralelo.

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

Recursos

Para más información sobre cómo cargar listas de blobs con la biblioteca cliente de Azure Blob Storage para .NET, consulte los recursos siguientes.

Ejemplos de código

Operaciones de API REST

El SDK de Azure para .NET contiene bibliotecas que se crean a partir de la API REST de Azure, lo que le permite interactuar con las operaciones de API REST a través de paradigmas conocidos de .NET. Los métodos de la biblioteca cliente para cargar blobs usan las siguientes operaciones de API REST:

Consulte también

Contenido relacionado

  • Este artículo forma parte de la guía para desarrolladores de Blob Storage para .NET. Para obtener más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación .NET.