Enumeración de blobs con Go

Este artículo muestra cómo listar blobs utilizando el módulo cliente de Azure Storage para Go.

Requisitos previos

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• Ir a la versión 1.18+

Configurar el entorno

Si no tiene un proyecto existente, esta sección muestra cómo configurar un proyecto para trabajar con el módulo cliente Azure Blob Storage para Go. Los pasos incluyen instalar el módulo, añadir las rutas import y crear un objeto de cliente autorizado. Para obtener información, consulte Introducción a Azure Blob Storage y Go.

Módulos de instalación

Instale el módulo azblob mediante el siguiente comando:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Para autenticarse con Microsoft Entra ID (recomendado), instale el módulo azidentity mediante el siguiente comando:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Agregar rutas de importación

En el archivo de código, agregue las rutas de importación siguientes:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

Estas rutas de importación representan el mínimo necesario para empezar. Algunos ejemplos de código de este artículo pueden requerir rutas de importación adicionales. Para obtener detalles específicos y ejemplos de uso, consulte Ejemplos de código.

Creación de un objeto de cliente

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

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

Autorización

El mecanismo de autorización debe tener los permisos necesarios para cargar 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 desde el código, puede especificar varias 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. 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 un contenedor mediante una lista plana, llame al siguiente método:

• NewListBlobsFlatPager

Para listar los blobs en un contenedor usando un listado jerárquico, llama al siguiente método desde un objeto cliente contenedor:

• NewListBlobsHierarchyPager

Gestiona cuántos resultados se devuelven

De forma predeterminada, una operación de enumeración devuelve hasta 5000 resultados a la vez. Para devolver un conjunto más pequeño de resultados, proporcione un valor distinto de cero para el campo MaxResults en ListBlobsFlatOptions o ListBlobsHierarchyOptions.

Filtrado de los resultados con un prefijo

Para filtrar la lista de blobs devueltos, especifique una cadena o un carácter para el campo Prefix en ListBlobsFlatOptions o ListBlobsHierarchyOptions. La cadena de prefijo puede incluir uno o varios caracteres. Después, Azure Storage solo devuelve los blobs cuyos nombres empiecen por ese prefijo.

Incluir metadatos del blob u otra información

Para incluir metadatos de blob con los resultados, establezca el campo Metadata en true como parte de ListBlobsInclude. Azure Storage incluye metadatos con cada blob devuelto, por lo que no es necesario recuperar los metadatos del blob por separado.

Consulte ListBlobsInclude para obtener más opciones para incluir instantáneas, versiones, etiquetas de índice de blobs y otra información con los resultados.

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. En este ejemplo se incluyen instantáneas de blobs y versiones de blobs, si existen:

func listBlobsFlat(client *azblob.Client, containerName string) {
    // List the blobs in the container
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
    })

    fmt.Println("List blobs flat:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

La salida es parecida a esta:

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

En el ejemplo siguiente se enumeran los blobs de un contenedor que comienzan con un prefijo específico:

func listBlobsFlatOptions(client *azblob.Client, containerName string, prefix string) {
    // List the blobs in the container with a prefix
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Prefix: to.Ptr(prefix),
    })

    fmt.Println("List blobs with prefix:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

Cuando pasas una cadena de prefijo de "sample", la salida es similar a:

List blobs with prefix:
sample-blob1.txt
sample-blob2.txt
sample-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 enumerar los blobs jerárquicamente, use el método siguiente:

• NewListBlobsHierarchyPager

En el ejemplo siguiente se enumeran los blobs del contenedor especificado mediante una lista jerárquica. En este ejemplo, el parámetro de prefijo se establece inicialmente en una cadena vacía para enumerar todos los blobs del contenedor. A continuación, el ejemplo llama recursivamente a la operación de enumeración para recorrer la jerarquía de directorios virtuales y enumerar los blobs.

func listBlobsHierarchy(client *azblob.Client, containerName string, prefix string) {
    // Reference the container as a client object
    containerClient := client.ServiceClient().NewContainerClient(containerName)

    pager := containerClient.NewListBlobsHierarchyPager("/", &container.ListBlobsHierarchyOptions{
        Prefix:     to.Ptr(prefix),
        MaxResults: to.Ptr(int32(1)), // MaxResults set to 1 for demonstration purposes
    })

    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        if resp.Segment.BlobPrefixes != nil {
            for _, prefix := range resp.Segment.BlobPrefixes {
                fmt.Println("Virtual directory prefix:", *prefix.Name)

                // Recursively list blobs in the prefix
                listBlobsHierarchy(client, containerName, *prefix.Name)
            }
        }

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println("Blob:", *blob.Name)
        }
    }
}

El resultado de ejemplo es similar al siguiente:

Virtual directory prefix: folderA/
Blob: folderA/file1.txt
Blob: folderA/file2.txt
Blob: folderA/file3.txt
Virtual directory prefix: folderA/folderB/
Blob: folderA/folderB/file1.txt
Blob: folderA/folderB/file2.txt
Blob: 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 Go decodifica Apache Arrow detrás de escena y sigue devolviendo los mismos BlobItem valores. 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 de Apache Arrow, configura el ResponseFormat campo de ListBlobsFlatOptions en StorageResponseFormatArrow, y luego pasa las opciones a NewListBlobsFlatPager. Al usar la salida de Apache Arrow, también puedes configurar los campos StartFrom 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:

import (
    "context"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container"
)

pager := client.NewListBlobsFlatPager("sample-container", &azblob.ListBlobsFlatOptions{
    Prefix:         to.Ptr("folderA/"),
    ResponseFormat: container.StorageResponseFormatArrow,
})

for pager.More() {
    resp, err := pager.NextPage(context.TODO())
    handleError(err)

    for _, blob := range resp.Segment.BlobItems {
        fmt.Println(*blob.Name)
    }
}

Recursos

Para más información sobre cómo enumerar blobs con el módulo cliente de Azure Blob Storage para Go, consulte los recursos siguientes.

Ejemplos de código

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

Operaciones de API REST

El SDK de Azure for Go contiene bibliotecas que se construyen sobre la API REST de Azure. Al usar estas librerías, puedes interactuar con operaciones de la API REST mediante paradigmas Go 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 del módulo cliente

• Documentación de referencia del módulo cliente
• Código fuente del módulo cliente
• Paquete (pkg.go.dev)

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