Enumeración de blobs con .NET

  • Artículo

En este artículo se muestra cómo enumerar blobs con la biblioteca cliente de Azure Storage para .NET.

Requisitos previos

  • En este artículo se supone que ya tiene un proyecto configurado para trabajar con la biblioteca cliente de Azure Blob Storage para .NET. Para obtener información sobre cómo configurar el proyecto, incluida la instalación de paquetes, la adición de directivas de using y la autorización de un objeto de cliente, consulte Introducción a Azure Blob Storage y .NET.
  • El mecanismo de autorización debe tener permisos para enumerar blobs. Para obtener más información, consulte la guía de autorización para la siguiente operación de la API de REST:

Acerca de las opciones de listado de blobs

Al enumerar blobs desde el código, puede especificar una serie de opciones para administrar cómo se devuelven los resultados de Azure Storage. 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. También puede enumerar los blobs en una estructura de lista plana o de forma 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:

Administración del número de resultados que 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.

En el ejemplo siguiente se enumeran los blobs del contenedor especificado mediante una lista plana, con un tamaño de segmento opcional especificado, y se 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

Nota:

La salida de ejemplo que se muestra supone que ya tiene una cuenta de almacenamiento con un espacio de nombres plano. Si ha habilitado la característica de espacio de nombres jerárquico en su cuenta de almacenamiento, los directorios no son virtuales. En su lugar, son objetos independientes y concretos. Como resultado, los directorios aparecen en la lista como blobs de longitud cero.

Para obtener una opción de lista alternativa al trabajar con un espacio de nombres jerárquico, consulte Enumerar el contenido del directorio (Azure Data Lake Storage Gen2).

Uso de una lista jerárquica

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

Para enumerar los blobs de forma jerárquica, llame al método BlobContainerClient.GetBlobsByHierarchy o BlobContainerClient.GetBlobsByHierarchyAsync.

En el ejemplo siguiente se enumeran los blobs del contenedor especificado mediante una lista jerárquica, con un tamaño de segmento opcional especificado, y se escribe el nombre del blob en la ventana de 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 es parecida a esta:

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

Nota:

Las instantáneas de blob no se pueden enumerar en una operación de enumeración jerárquica.

Enumeración de versiones o instantáneas de blob

Para enumerar las versiones o instantáneas, especifique el parámetro BlobStates con el campo Version o Snapshot. Las instantáneas y las versiones aparecen ordenadas de más antigua a 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;
    }
}

Recursos

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

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 crear listas de blobs usan esta operación de API de REST:

Recursos de la biblioteca cliente

Consulte también