Enumeración de blobs con .NET

Este artículo muestra cómo listar blobs utilizando la biblioteca cliente de Azure Storage para .NET.

Requisitos previos

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• El SDK de .NET más reciente para su sistema operativo. Asegúrese de obtener el SDK y no el entorno de ejecución.

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

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

Autorización

El mecanismo de autorización debe tener los permisos necesarios para enumerar un blob. Para autorizar con Microsoft Entra ID (recomendado), necesitas el rol integrado de Azure RBAC Storage Blob Data Reader o superior. Para obtener más información, consulte la guía de autorización para List Blobs (API REST).

Información sobre las opciones de enumeración de blobs

Al enumerar blobs en el código, puede especificar varias opciones para controlar cómo Azure Storage devuelve los resultados. Puede especificar el número de resultados que se van a devolver en cada conjunto de resultados y luego recuperar los conjuntos subsiguientes. Puede especificar un prefijo para devolver los blobs cuyos nombres comienzan por ese carácter o cadena. Puedes listar los blobs en una estructura plana o jerárquica. Una lista jerárquica devuelve los blobs como si estuvieran organizados en carpetas.

Para enumerar los blobs de una cuenta de almacenamiento, llame a uno de estos métodos:

• BlobContainerClient.GetBlobs
• BlobContainerClient.GetBlobsAsync
• BlobContainerClient.GetBlobsByHierarchy
• BlobContainerClient.GetBlobsByHierarchyAsync

Gestiona cuántos resultados se devuelven

De forma predeterminada, una operación de enumeración devuelve hasta 5000 resultados a la vez, pero puede especificar el número de resultados que quiere que devuelva. En los ejemplos que se presentan en este artículo muestran cómo devolver resultados por páginas. Para más información sobre los conceptos de paginación, consulte Paginación con el SDK de Azure para .NET.

Filtrado de los resultados con un prefijo

Para filtrar la lista de blobs, especifique una cadena para el parámetro prefix. La cadena de prefijo puede incluir uno o varios caracteres. Después, Azure Storage solo devuelve los blobs cuyos nombres empiecen por ese prefijo.

Devolución de metadatos

Puede devolver metadatos de blob con los resultados especificando el valor Metadata para la enumeración BlobTraits.

Lista plana frente a lista jerárquica

Los blobs de Azure Storage están organizados en un paradigma plano, en lugar de un paradigma jerárquico (como un sistema de archivos clásico). Sin embargo, los blobs se pueden organizar en directorios virtuales para imitar una estructura de carpetas. Un directorio virtual forma parte del nombre del blob y se indica mediante el carácter delimitador.

Para organizar los blobs en directorios virtuales, use un carácter delimitador en el nombre del blob. El carácter delimitador predeterminado es una barra diagonal (/), pero puede especificar cualquier carácter como delimitador.

Si usa un delimitador para asignar nombres a los blobs, puede optar por enumerar los blobs de forma jerárquica. En el caso de una operación de enumeración jerárquica, Azure Storage devuelve los directorios virtuales y los blobs que hay debajo del objeto primario. Puede llamar a la operación de enumeración de forma recursiva para recorrer la jerarquía, de manera similar a como se haría con un sistema de archivos clásico mediante programación.

Uso de una lista plana

De forma predeterminada, una operación de enumeración devuelve los blobs en una lista plana. En una lista plana, los blobs no se organizan por directorio virtual.

El siguiente ejemplo lista los blobs en el contenedor especificado usando una lista plana, con un tamaño de segmento opcional especificado, y escribe el nombre del blob en una ventana de consola.

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

La salida es parecida a esta:

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Uso de una lista jerárquica

Cuando se realiza una operación de enumeración de forma jerárquica, Azure Storage devuelve los directorios virtuales y los blobs en el primer nivel de la jerarquía.

Para listar los blobs jerárquicamente, llama al método BlobContainerClient.GetBlobsByHierarchy o al método BlobContainerClient.GetBlobsByHierarchyAsync .

El siguiente ejemplo lista los blobs en el contenedor especificado usando un listado jerárquico, con un tamaño de segmento opcional especificado, y escribe el nombre del blob en la ventana de la consola.

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobHierarchyItem> blobPage in resultSegment)
        {
            // A hierarchical listing may return both virtual directories and blobs.
            foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
            {
                if (blobhierarchyItem.IsPrefix)
                {
                    // Write out the prefix of the virtual directory.
                    Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                    // Call recursively with the prefix to traverse the virtual directory.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

La salida de ejemplo es similar a:

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Listar versiones o instantáneas de blobs

Para enumerar las versiones o instantáneas, especifique el parámetro BlobStates con el campo Version o Snapshot. El servicio devuelve versiones y instantáneas de la más antigua a la más reciente.

En el ejemplo de código siguiente se muestra cómo enumerar las versiones de blob.

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Lista de blobs en formato Apache Arrow (vista previa)

Esta capacidad se basa en la API existente List Blobs . En lugar de usar el XML por defecto, utiliza el formato compacto y columnar Apache Arrow como formato de respuesta en el cable. Lo activas configurando una única opción en la llamada para listar contenedores. El SDK de .NET decodifica Apache Arrow entre bastidores y sigue devolviendo los mismos objetos BlobItem. Este enfoque mejora el rendimiento de listados y reduce la CPU del lado del cliente al enumerar contenedores grandes. Preserva el contrato de respuesta en el que dependen las solicitudes.

Para solicitar resultados con formato Apache Arrow, configura la propiedad ResponseFormat de GetBlobsOptions en StorageResponseFormat.Arrow, luego pasa las opciones al BlobContainerClient.GetBlobs overload que acepta GetBlobsOptions. Al usar la salida de Apache Arrow, también puedes configurar las StartFrom propiedades y EndBefore para controlar el rango de rutas devueltas.

El siguiente ejemplo lista los blobs en un contenedor y solicita los resultados en formato Apache Arrow:

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

GetBlobsOptions options = new GetBlobsOptions
{
    Prefix = "FolderA/",
    ResponseFormat = StorageResponseFormat.Arrow
};

foreach (BlobItem blobItem in containerClient.GetBlobs(options))
{
    Console.WriteLine("Blob name: " + blobItem.Name);
}

Recursos

Para saber más sobre cómo listar blobs utilizando la biblioteca cliente de Azure Blob Storage para .NET, consulta los siguientes recursos.

Operaciones de API REST

El SDK de Azure para .NET contiene bibliotecas que se construyen sobre la API REST de Azure. Al utilizar estas librerías, puedes interactuar con operaciones de la API REST mediante paradigmas .NET familiares. Los métodos de la biblioteca cliente para crear listas de blobs usan esta operación de API de REST:

• Enumeración de blobs (API de REST)

Recursos de la biblioteca cliente

• Documentación de referencia de la biblioteca cliente
• Código fuente de la biblioteca del cliente
• Paquete (NuGet)

Consulte también

• Enumeración de recursos de blob
• Control de versiones de blobs

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.