Enumeración de blobs con Java

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

Requisitos previos

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• Kit de desarrollo de Java (JDK) versión 8 o posterior (se recomienda la versión 17 para obtener la mejor experiencia)
• Apache Maven se usa para la administración de proyectos en este ejemplo

Configurar el entorno

Si no tiene un proyecto existente, en esta sección, se muestra cómo configurar un proyecto para que funcione con la biblioteca cliente de Azure Blob Storage para Java. Para más información, consulte Introducción a Azure Blob Storage y Java.

Para trabajar con los ejemplos de código de este artículo, siga los pasos siguientes a fin de configurar el proyecto.

Instalar paquetes

Abra el archivo pom.xml en el editor de texto. Instale los paquetes mediante la inclusión del archivo BOM o la inclusión de una dependencia directa.

Adición de instrucciones de importación

Agregue las instrucciones siguientes import:

import com.azure.core.http.rest.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;

Authorization

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 más información, consulte la guía de autorización para la Enumeración de blobs (API de REST).

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 usa BlobServiceClientBuilder para crear un objeto BlobServiceClient mediante DefaultAzureCredential, y se muestra cómo crear clientes de contenedores y blobs, si es necesario:

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

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.

Acerca de las opciones de lista de blobs

Al enumerar blobs desde el código, puede especificar 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:

• listBlobs
• listBlobsByHierarchy

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

Filtrado de los resultados con un prefijo

Para filtrar la lista de blobs, pase una cadena como prefix parámetro a ListBlobsOptions.setPrefix(String 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.

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:

public void listBlobsFlat(BlobContainerClient blobContainerClient) {
    System.out.println("List blobs flat:");

    blobContainerClient.listBlobs()
            .forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
}

La salida es parecida a esta:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

También puedes especificar opciones para filtrar los resultados de la lista o mostrar más información. En el ejemplo siguiente se enumeran los blobs con un prefijo especificado y también se enumeran los blobs eliminados:

public void listBlobsFlatWithOptions(BlobContainerClient blobContainerClient) {
    ListBlobsOptions options = new ListBlobsOptions()
            .setMaxResultsPerPage(2) // Low number for demonstration purposes
            .setDetails(new BlobListDetails()
                    .setRetrieveDeletedBlobs(true));

    System.out.println("List blobs flat:");

    int i = 0;
    Iterable<PagedResponse<BlobItem>> blobPages = blobContainerClient.listBlobs(options, null).iterableByPage();
    for (PagedResponse<BlobItem> page : blobPages) {
        System.out.printf("Page %d%n", ++i);
        page.getElements().forEach(blob -> {
            System.out.printf("Name: %s, Is deleted? %b%n",
                    blob.getName(),
                    blob.isDeleted());
        });
    }
}

La salida es parecida a esta:

List blobs flat:
Page 1
Name: file4.txt, Is deleted? false
Name: file5-deleted.txt, Is deleted? true
Page 2
Name: folderA/file1.txt, Is deleted? false
Name: folderA/file2.txt, Is deleted? false
Page 3
Name: folderA/folderB/file3.txt, Is deleted? false

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 jerárquicamente, use el método siguiente:

• listBlobsByHierarchy

En el ejemplo siguiente se enumeran los blobs del contenedor especificado mediante una lista jerárquica:

public void listBlobsHierarchicalListing(BlobContainerClient blobContainerClient, String prefix/* ="" */) {
    String delimiter = "/";
    ListBlobsOptions options = new ListBlobsOptions()
            .setPrefix(prefix);

    blobContainerClient.listBlobsByHierarchy(delimiter, options, null)
            .forEach(blob -> {
                if (blob.isPrefix()) {
                    System.out.printf("Virtual directory prefix: %s%n", delimiter + blob.getName());
                    listBlobsHierarchicalListing(blobContainerClient, blob.getName());
                } else {
                    System.out.printf("Blob name: %s%n", blob.getName());
                }
            });
}

La salida es parecida a esta:

List blobs hierarchical:
Blob name: file4.txt
Virtual directory prefix: /folderA/
Blob name: folderA/file1.txt
Blob name: folderA/file2.txt
Virtual directory prefix: /folderA/folderB/
Blob name: folderA/folderB/file3.txt

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 Java decodifica Apache Arrow entre bastidores y sigue devolviendo los mismos BlobItem objetos. 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 el formato de serialización de respuesta en ListBlobsOptions como StorageResponseSerializationFormat.ARROW llamando setStorageResponseSerializationFormata , y luego pasa las opciones a BlobContainerClient.listBlobs. Al usar la salida de Apache Arrow, también puedes llamar a setStartFrom y setEndBefore para controlar el rango de rutas devueltas.

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

ListBlobsOptions options = new ListBlobsOptions()
    .setPrefix("folderA/")
    .setStorageResponseSerializationFormat(StorageResponseSerializationFormat.ARROW);

for (BlobItem blobItem : containerClient.listBlobs(options, null)) {
    System.out.println("Blob name: " + blobItem.getName());
}

Recursos

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

Ejemplos de código

• Visualización de ejemplos de código de este artículo (GitHub)

Operaciones de API REST

El SDK de Azure para Java 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 Java familiares. Los métodos de la biblioteca cliente para enumerar blobs usan la siguiente operación de API 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 (Maven)

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 Java. Para más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación Java.