Blobs mit Go auflisten

Dieser Artikel zeigt, wie man Blobs mit dem Azure Storage-Client-Modul für Go auflistet.

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• Azure Storage-Konto – Erstellen eines Speicherkontos
• Go 1.18+

Richten Sie Ihre Umgebung ein

Wenn Sie nicht über ein vorhandenes Projekt verfügen, wird in diesem Abschnitt gezeigt, wie Sie ein Projekt für die Arbeit mit dem Azure Blob Storage-Clientmodul für Go einrichten. Die Schritte umfassen die Modulinstallation, das Hinzufügen von import-Pfaden und das Erstellen eines autorisierten Clientobjekts. Ausführlichere Informationen finden Sie unter Erste Schritte mit Azure Blob Storage und Go.

Installieren von Modulen

Verwenden Sie den folgenden Befehl, um das Modul azblob zu installieren:

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

Um sich mit Microsoft Entra ID zu authentifizieren (empfohlen), installieren Sie das azidentity-Modul mit dem folgenden Befehl:

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

Hinzufügen von Importpfaden

Fügen Sie in der Codedatei die folgenden Importpfade hinzu:

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

Dies sind die Importpfade, die mindestens für die ersten Schritte erforderlich sind. Einige Codebeispiele in diesem Artikel erfordern möglicherweise zusätzliche Importpfade. Spezifische Details und eine Beispielverwendung finden Sie unter Codebeispiele.

Erstellen eines Clientobjekts

Um eine App mit Blob Storage zu verbinden, erstellen Sie ein Clientobjekt mithilfe von azblob.NewClient. Das folgende Beispiel zeigt, wie Sie ein Clientobjekt mithilfe von DefaultAzureCredential für die Autorisierung erstellen:

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
}

Autorisierung

Der Autorisierungsmechanismus muss über die erforderlichen Berechtigungen zum Hochladen eines Blobs verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) benötigen Sie die integrierte Azure RBAC-Rolle Storage Blob Data Reader oder höher. Weitere Informationen finden Sie im Autorisierungsleitfaden für List Blobs (REST API).

Informationen über Optionen für das Auflisten von Blobs

Wenn Sie Blobs über Ihren Code auflisten, können Sie viele Optionen angeben, um zu steuern, wie Ergebnisse von Azure Storage zurückgegeben werden. Sie können die Anzahl der Ergebnisse festlegen, die in den einzelnen Ergebnissätzen zurückgegeben werden sollen, und dann die nachfolgenden Sätze abrufen. Sie können ein Präfix angeben, um Blobs zurückzugeben, deren Namen mit dem jeweiligen Zeichen oder der Zeichenfolge beginnen. Du kannst Blobs in einer flachen Listenstruktur oder hierarchisch auflisten. Bei einer hierarchischen Auflistung werden Blobs so zurückgegeben, als wären sie in Ordnern organisiert.

Um die Blobs in einem Container mithilfe einer flachen Auflistung aufzulisten, rufen Sie die folgende Methode auf:

• NewListBlobsFlatPager

Um die Blobs in einem Container mittels einer hierarchischen Auflistung aufzulisten, ruft man folgende Methode aus einem Container-Client-Objekt auf:

• NewListBlobsHierarchyPager

Festlegen der Anzahl der zurückgegebenen Ergebnisse

Standardmäßig werden durch einen einzelnen Auflistungsvorgang bis zu 5.000 Ergebnisse zurückgegeben. Um einen kleineren Satz von Ergebnissen zurückzugeben, geben Sie einen Wert ungleich Null für das Feld MaxResults in ListBlobsFlatOptions oder ListBlobsHierarchyOptions an.

Filtern von Ergebnissen mit einem Präfix

Um die Liste der zurückgegebenen Blobs zu filtern, geben Sie eine Zeichenfolge oder ein Zeichen für das Feld Prefix in ListBlobsFlatOptions oder ListBlobsHierarchyOptions an. Die Präfixzeichenfolge kann ein oder mehrere Zeichen enthalten. Dann gibt Azure Storage nur die Blobs zurück, deren Namen mit diesem Präfix beginnen.

Blobmetadaten oder andere Informationen einbeziehen

Um Blobmetadaten in die Ergebnisse einzuschließen, setzen Sie das Feld Metadata als Teil von ListBlobsInclude auf true. Da Azure Storage für jedes zurückgegebene Blob Metadaten enthält, müssen Sie diese nicht separat abrufen.

Unter ListBlobsInclude finden Sie weitere Optionen, um Momentaufnahmen, Versionen, Blobindextags und andere Informationen in die Ergebnisse einzuschließen.

Flache Auflistung und hierarchische Auflistung im Vergleich

Blobs in Azure Storage sind in einem flachen Paradigma organisiert statt in einem hierarchischen Paradigma (wie ein klassisches Dateisystem). Sie können Blobs jedoch in virtuellen Verzeichnissen organisieren, um eine Ordnerstruktur zu imitieren. Ein virtuelles Verzeichnis bildet einen Teil des Blobnamens und wird durch das Trennzeichen angezeigt.

Wenn Sie also Blobs in virtuellen Verzeichnissen organisieren möchten, verwenden Sie ein Trennzeichen im Blobnamen. Das Standardtrennzeichen ist ein Schrägstrich (/), doch können Sie ein beliebiges Zeichen als Trennzeichen angeben.

Wenn Sie Ihre Blobs mithilfe eines Trennzeichens benennen, können Sie sie hierarchisch auflisten. Bei einem hierarchischen Auflistungsvorgang gibt Azure Storage alle virtuellen Verzeichnisse und Blobs unter dem übergeordneten Objekt zurück. Sie können den Auflistungsvorgang rekursiv aufrufen, um die Hierarchie zu durchlaufen – ähnlich wie beim programmgesteuerten Durchlaufen eines klassischen Dateisystems.

Verwenden einer flachen Auflistung

Ein Auflistungsvorgang gibt Blobs standardmäßig in einer flachen Auflistung zurück. In einer flachen Auflistung werden Blobs nicht nach virtuellem Verzeichnis organisiert.

Im folgenden Beispiel werden die Blobs im angegebenen Container mithilfe einer flachen Auflistung aufgelistet. Dieses Beispiel enthält Blob-Snapshots und Blobversionen, sofern vorhanden:

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

Die Beispielausgabe sieht in etwa so aus:

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

Im folgenden Beispiel werden Blobs in einem Container aufgelistet, die mit einem bestimmten Präfix beginnen:

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

Wenn Sie eine Präfixzeichenfolge „sample“ übergeben, ähnelt die Ausgabe etwa Folgendem:

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

Verwenden einer hierarchischen Auflistung

Wenn Sie einen Auflistungsvorgang hierarchisch aufrufen, gibt Azure Storage die virtuellen Verzeichnisse und Blobs auf der ersten Hiearchieebene zurück.

Verwenden Sie zum hierarchischen Auflisten von Blobs die folgende Methode:

• NewListBlobsHierarchyPager

Im folgenden Beispiel werden die Blobs im angegebenen Container mithilfe einer hierarchischen Auflistung aufgelistet. In diesem Beispiel wird der Präfixparameter zunächst auf eine leere Zeichenfolge festgelegt, um alle Blobs im Container aufzulisten. Anschließend ruft das Beispiel den Auflistungsvorgang rekursiv auf, um die virtuelle Verzeichnishierarchie zu durchlaufen und Blobs aufzulisten.

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

Die Beispielausgabe sieht in etwa so aus:

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

Liste der Blobs im Apache Arrow-Format (Vorschau)

Diese Funktion basiert auf der bestehenden List Blobs API. Anstatt das Standard-XML zu verwenden, verwendet es das kompakte, spaltenartige Apache Arrow-Format als Antwortformat auf dem Draht. Du aktivierst es, indem du eine einzige Option im Container-Listing-Call einlegst. Das Go SDK decodiert Apache Arrow im Hintergrund und liefert weiterhin die gleichen BlobItem Werte zurück. Dieser Ansatz verbessert den Listdurchsatz und reduziert die clientseitige CPU beim Aufzählen großer Container. Sie bewahrt den Antwortvertrag, auf den Anwendungen angewiesen sind.

Um Apache Arrow-formatierte Ergebnisse anzufordern, setzen Sie das ResponseFormatFeld ListBlobsFlatOptions auf StorageResponseFormatArrow und geben Sie die Optionen dann an NewListBlobsFlatPager weiter. Wenn Sie die Apache Arrow-Ausgabe verwenden, können Sie auch die Felder StartFrom und EndBefore festlegen, um den Bereich der zurückgegebenen Pfade zu steuern.

Das folgende Beispiel listet die Blobs in einem Container auf und fordert die Ergebnisse im Apache Arrow-Format an:

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

Ressourcen

Weitere Informationen zum Auflisten von Blobs mithilfe des Azure Blob Storage-Clientmoduls für Go finden Sie in den folgenden Ressourcen.

Codebeispiele

• Codebeispiele aus diesem Artikel anzeigen (GitHub)

REST-API-Vorgänge

Das Azure SDK für Go enthält Bibliotheken, die auf der Azure REST API aufbauen. Durch die Nutzung dieser Bibliotheken können Sie mit REST-API-Operationen über vertraute Go-Paradigmen interagieren. Die Methoden der Clientbibliothek zum Auflisten von Blobs verwenden den folgenden REST-API-Vorgang:

• Blobs auflisten (REST-API)

Clientmodulressourcen

• Referenzdokumentation zum Clientmodul
• Quellcode des Clientmoduls
• Paket (pkg.go.dev)

Siehe auch

• Aufzählen von Blobressourcen
• Blobversionsverwaltung

Zugehöriger Inhalt

• Dieser Artikel ist Teil des Blob Storage-Entwicklerleitfadens für Go. Weitere Informationen finden Sie in der vollständigen Liste der Entwicklerleitfadenartikel unter Erstellen Ihrer Go-App.