Compartir vía

Enumeración de blobs con Go

  • Artículo

En este artículo se muestra cómo enumerar blobs mediante el módulo cliente de Azure Storage para Go.

Requisitos previos

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 la instalación del módulo, la adición de rutas de acceso de import y la creación de 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
}

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

Acerca de las opciones de listado 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. 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 un contenedor usando una lista plana, llame al siguiente método:

Para enumerar los blobs de un contenedor usando una lista jerárquica, llame al siguiente método desde un objeto cliente de contenedor:

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. 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 de blobs 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 capturar también los metadatos del blob.

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.

Nota:

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

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)
        }
    }
}

Al pasar una cadena de prefijo de "muestra", la salida es similar a:

List blobs with prefix:
sample-blob1.txt
sample-blob2.txt
sample-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. Por lo tanto, 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 NewListPathsPager.

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:

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, en el ejemplo se llama a la operación de lista de forma recursiva para recorrer la jerarquía de directorios virtuales y los blobs de lista.

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)
        }
    }
}

La salida es parecida a esta:

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

Nota:

Los ejemplos de código de esta guía están diseñados para ayudarle a empezar a trabajar con Azure Blob Storage y Go. Debe modificar el control de errores y los valores de Context para satisfacer las necesidades de la aplicación.

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

Operaciones de API REST

El SDK de Azure para Go contiene bibliotecas que se crean a partir de la API de REST de Azure, lo que le permite interactuar con las operaciones de API de REST a través de paradigmas conocidos de Go. Los métodos de la biblioteca cliente para crear listas de blobs usan esta operación de API de REST:

Recursos del módulo cliente

Consulte también

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.