Elencare BLOB con Go

Questo articolo mostra come elencare i blob utilizzando il client module Archiviazione di Azure per Go.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Account di archiviazione di Azure: creare un account di archiviazione
• Go 1.18+

Configurazione dell'ambiente

Se non si ha un progetto esistente, questa sezione illustra come configurare un progetto per l'uso con il modulo client di Archiviazione BLOB di Azure per Go. I passaggi includono l'installazione del modulo, l'aggiunta di percorsi import e la creazione di un oggetto client autorizzato. Per informazioni dettagliate, vedere Introduzione all'archiviazione BLOB di Azure e Go.

Installare i moduli

Installare il modulo azblob usando il comando seguente:

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

Per eseguire l'autenticazione con Microsoft Entra ID (scelta consigliata), installare il modulo azidentity usando il comando seguente:

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

Aggiungere percorsi di importazione

Nel file di codice aggiungere i percorsi di importazione seguenti:

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

Questi percorsi di importazione rappresentano il minimo necessario per iniziare. Alcuni esempi di codice in questo articolo potrebbero richiedere percorsi di importazione aggiuntivi. Per informazioni dettagliate specifiche e utilizzo di esempio, vedere Esempi di codice.

Creare un oggetto client

Per connettere un'app all'archiviazione BLOB, creare un oggetto client usando azblob. NewClient. Nell'esempio seguente viene illustrato come creare un oggetto client usando DefaultAzureCredential per l'autorizzazione:

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
}

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per caricare un BLOB. Per l'autorizzazione tramite Microsoft Entra ID (consigliata), è necessario il ruolo predefinito di Azure RBAC Storage Blob Data Reader o un ruolo superiore. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per List Blobs (API REST).

Informazioni su opzioni di elenco dei BLOB

Quando elenchi i blob dal codice, puoi specificare molte opzioni per gestire il modo in cui i risultati vengono restituiti da Archiviazione di Azure. È possibile specificare il numero di risultati da restituire in ogni set di risultati e quindi recuperare i set successivi. È possibile specificare un prefisso per restituire i BLOB i cui nomi iniziano con tale carattere o stringa. Puoi elencare i blob in una struttura di elenco piatto o gerarchica. Un elenco gerarchico restituisce i BLOB come se fossero organizzati in cartelle.

Per elencare i blob in un contenitore usando un'elencazione semplice, chiamare il metodo seguente:

• NewListBlobsFlatPager

Per elencare i blob in un container usando un elenco gerarchico, si richiama il seguente metodo da un oggetto client container:

• NewListBlobsHierarchyPager

Gestire il numero di risultati restituiti

Per impostazione predefinita, un'operazione di elenco restituisce fino a 5.000 risultati alla volta. Per restituire un set di risultati più piccolo, specificare un valore diverso da zero nel campo MaxResults in ListBlobsFlatOptions o ListBlobsHierarchyOptions.

Filtrare i risultati con un prefisso

Per filtrare l'elenco dei BLOB restituiti, specificare una stringa o un carattere nel campo Prefix in ListBlobsFlatOptions o ListBlobsHierarchyOptions. La stringa di prefisso può includere uno o più caratteri. Archiviazione di Azure restituisce quindi solo i blob i cui nomi iniziano con quel prefisso.

Includi i metadati del blob o altre informazioni

Per includere i metadati BLOB con i risultati, impostare il campo Metadata su true nell'ambito di ListBlobsInclude. Archiviazione di Azure include i metadati per ogni BLOB restituito, quindi non è necessario recuperare separatamente i metadati del BLOB.

Vedere ListBlobsInclude per ulteriori opzioni che consentono di includere snapshot, versioni, tag di indice dei BLOB e altre informazioni nei risultati.

Confronto tra elenco semplice e gerarchico

I BLOB in Archiviazione di Azure sono organizzati secondo un paradigma semplice, anziché gerarchico (come un file system classico). Tuttavia, è possibile organizzare i BLOB in directory virtuali per simulare una struttura di cartelle. Una directory virtuale costituisce parte del nome del BLOB ed è indicata dal carattere di delimitazione.

Per organizzare i BLOB in directory virtuali, usare un carattere di delimitazione nel nome del BLOB. Il delimitatore predefinito è la barra (/), ma è possibile specificare qualsiasi carattere.

Se i BLOB vengono denominati usando un delimitatore, è possibile scegliere un elenco gerarchico. Durante un'operazione di elenco gerarchico, Archiviazione di Azure restituisce tutte le eventuali directory virtuali e i blob presenti sotto l'oggetto padre. È possibile chiamare l'operazione di elenco in modo ricorsivo per attraversare la gerarchia in modo analogo a come si attraverserebbe un file system classico a livello di codice.

Usare un elenco semplice

Per impostazione predefinita, un'operazione di enumerazione restituisce i blob in un elenco non gerarchico. In un elenco semplice, i BLOB non sono organizzati in base alla directory virtuale.

L'esempio seguente elenca i blob nel contenitore specificato con un elenco semplice. Questo esempio comprende snapshot dei BLOB e versioni dei BLOB, se esistono:

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

Un risultato di esempio è simile al seguente:

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

L'esempio seguente elenca i BLOB in un contenitore che iniziano con un prefisso specifico:

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

Quando si passa una stringa di prefisso pari a "sample", l'output è simile a:

List blobs with prefix:
sample-blob1.txt
sample-blob2.txt
sample-blob3.txt

Usare un elenco gerarchico

Quando si chiama un'operazione di elencazione in modo gerarchico, Archiviazione di Azure restituisce le directory virtuali e i blob al primo livello della gerarchia.

Per elencare i BLOB in modo gerarchico, usare il metodo seguente:

• NewListBlobsHierarchyPager

L'esempio seguente elenca i BLOB nel contenitore specificato usando un elenco gerarchico. In questo esempio, il parametro prefix viene inizialmente impostato su una stringa vuota per elencare tutti i BLOB nel contenitore. L'esempio richiama quindi ricorsivamente l'operazione di enumerazione per scorrere la gerarchia di directory virtuali ed elencare i blob.

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

L'esempio di output è simile al seguente:

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

Elenco dei blob in formato Apache Arrow (anteprima)

Questa funzionalità è costruita sull'API esistente List Blobs . Invece di usare l'XML predefinito, utilizza il formato compatto e columnare Apache Arrow come formato di risposta sul filo. Lo si abilita impostando una singola opzione nella chiamata di elenco dei contenitori. Il Go SDK decodifica Apache Arrow dietro le quinte e restituisce comunque gli stessi BlobItem valori. Questo approccio migliora la velocità di elencazione e riduce l'utilizzo della CPU lato client durante l'enumerazione di contenitori di grandi dimensioni. Preserva il contratto di risposta su cui si basano le domande.

Per richiedere risultati formattati con Apache Arrow, imposta il ResponseFormat campo ListBlobsFlatOptions su StorageResponseFormatArrow, poi passa le opzioni a NewListBlobsFlatPager. Quando si usa l'output di Apache Arrow, puoi anche impostare i StartFrom campi e EndBefore per controllare l'intervallo di percorsi restituiti.

Il seguente esempio elenca i blob in un contenitore e richiede i risultati in 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)
    }
}

Risorse

Per altre informazioni su come elencare i BLOB tramite il modulo client di Archiviazione BLOB di Azure per Go, vedere le risorse seguenti.

Esempi di codice

• Vedere gli esempi di codice di questo articolo (GitHub)

Operazioni dell'API REST

L'Azure SDK for Go contiene librerie che si costruiscono sopra l'API Azure REST. Utilizzando queste librerie, puoi interagire con le operazioni dell'API REST attraverso i familiari paradigmi Go. I metodi della libreria client per elencare i BLOB usano l'operazione API REST seguente:

• List Blobs (API REST)

Risorse del modulo client

• Documentazione di riferimento del modulo client
• Codice sorgente del modulo client
• Pacchetto (pkg.go.dev)

Vedi anche

• Elencare le risorse Blob
• Controllo delle versioni per i BLOB

Contenuto correlato

• Questo articolo fa parte della Guida per sviluppatori di Archiviazione BLOB per Go. Per altre informazioni, vedere l’elenco completo degli articoli della Guida per sviluppatori inCreare la propria app Go.