Blobs mit .NET auflisten

Dieser Artikel zeigt, wie man Blobs mit der Azure Storage Client-Bibliothek für .NET auflistet.

Voraussetzungen

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 der Azure Blob Storage-Clientbibliothek für .NET einrichten. Die Schritte umfassen die Paketinstallation, das Hinzufügen von using-Anweisungen und das Erstellen eines autorisierten Clientobjekts. Ausführlichere Informationen finden Sie unter Erste Schritte mit Azure Blob Storage und .NET.

Installieren von Paketen

Installieren Sie in Ihrem Projektverzeichnis mithilfe des Befehls dotnet add package Pakete für die Azure Blob Storage- und Azure Identity-Clientbibliotheken. Für kennwortlose Verbindungen mit Azure-Diensten wird das Azure.Identity-Paket benötigt.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Fügen Sie Anweisungen vom Typ using hinzu.

Fügen Sie diese using-Anweisungen am Anfang der Codedatei hinzu:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Einige Codebeispiele in diesem Artikel erfordern möglicherweise zusätzliche using-Anweisungen.

Erstellen eines Clientobjekts

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

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Sie können einen Dienstclient für die Abhängigkeitsinjektion in einer .NET-App registrieren.

Sie können auch Clientobjekte für bestimmte Container oder Blobs erstellen. Weitere Informationen zum Erstellen und Verwalten von Clientobjekten finden Sie unter Erstellen und Verwalten von Clientobjekten, die mit Datenressourcen interagieren.

Autorisierung

Der Autorisierungsmechanismus muss über die erforderlichen Berechtigungen zum Auflisten 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 eine Reihe von 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.

Rufen Sie zum Auflisten der Blobs in einem Speicherkonto eine der folgenden Methoden auf:

Festlegen der Anzahl der zurückgegebenen Ergebnisse

Standardmäßig gibt ein Auflistungsvorgang bis zu 5000 Ergebnisse in einem Durchgang zurück, Sie können jedoch die Anzahl der Ergebnisse angeben, die von jedem Auflistungsvorgang zurückgegeben werden soll. Die Beispiele in diesem Artikel zeigen Ihnen, wie Ergebnisse in Seiten zurückgegeben werden. Weitere Informationen zu Paginierungskonzepten finden Sie unter Paginierung mit dem Azure SDK für .NET.

Filtern von Ergebnissen mit einem Präfix

Um die Liste der Blobs zu filtern, geben Sie für den prefix-Parameter eine Zeichenfolge 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.

Zurückgeben von Metadaten

Sie können Blobmetadaten mit den Ergebnissen zurückgeben, indem Sie den Metadatenwert für die BlobTraits-Enumeration angeben.

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.

Das folgende Beispiel listet die Blobs im angegebenen Container mit einer flachen Auflistung auf, mit einer optionalen Segmentgröße, und schreibt den Blob-Namen in ein Konsolenfenster.

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Die Beispielausgabe sieht etwa wie folgt aus:

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Hinweis

In der gezeigten Beispielausgabe wird davon ausgegangen, dass Sie über ein Speicherkonto mit einem flachen Namespace verfügen. Wenn Sie für Ihr Speicherkonto das Feature für den hierarchischen Namespace aktivieren, sind Verzeichnisse nicht virtuell. Stattdessen sind sie konkrete, unabhängige Objekte. Daher werden Verzeichnisse in der Liste als Blobs der Länge Null angezeigt.

Eine alternative Auflistungsoption für die Arbeit mit einem hierarchischen Namespace finden Sie unter Auflisten von Verzeichnisinhalten (Azure Data Lake Storage).

Verwenden einer hierarchischen Auflistung

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

Um Blobs hierarchisch aufzulisten, rufen Sie die BlobContainerClient.GetBlobsByHierarchy oder die BlobContainerClient.GetBlobsByHierarchyAsync-Methode auf.

Das folgende Beispiel listet die Blobs im angegebenen Container mithilfe einer hierarchischen Auflistung mit einer optionalen Segmentgröße auf und schreibt den Blob-Namen ins Konsolenfenster.

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobHierarchyItem> blobPage in resultSegment)
        {
            // A hierarchical listing may return both virtual directories and blobs.
            foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
            {
                if (blobhierarchyItem.IsPrefix)
                {
                    // Write out the prefix of the virtual directory.
                    Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                    // Call recursively with the prefix to traverse the virtual directory.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Die Beispielausgabe sieht ähnlich wie hier aus:

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Hinweis

Blob-Snapshots können nicht in einer hierarchischen Auflistungsoperation aufgeführt werden.

Blob-Versionen oder Momentaufnahmen auflisten

Geben Sie zum Auflisten von Blobversionen oder Momentaufnahmen den Parameter BlobStates im Feld Version oder Momentaufnahme an. Der Dienst liefert Versionen und Schnappschüsse von ältesten bis neuesten.

Das folgende Codebeispiel zeigt, wie Blobversionen aufgelistet werden.

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Liste der Blobs im Apache Arrow-Format (Vorschau)

Important

Die Auflistung von Blobs im Apache-Arrow-Format befindet sich derzeit in der Vorschau. Dieses Szenario erfordert eine Beta-Version (Vorschau) der Azure Blob Storage-Clientbibliothek für .NET (zum Beispiel Azure.Storage.Blobseine Vorschauversion 12.30.0-beta.1 oder später). Vorschaufunktionen werden ohne Service-Level-Vereinbarung bereitgestellt und sind für Produktionsworkloads nicht empfohlen. Manche Funktionen werden möglicherweise nicht unterstützt oder haben eingeschränkte Funktionen. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbedingungen für Microsoft Azure-Vorschauversionen.

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 .NET SDK entschlüsselt Apache Arrow im Hintergrund und liefert weiterhin dieselben BlobItem Objekte 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.

Warning

Das Auflisten von Blobs im Apache Arrow-Format wird auf Speicherkonten mit aktiviertem hierarchischen Namensraum (Azure Data Lake Storage) nicht unterstützt.

Um Apache Arrow-formatierte Ergebnisse anzufordern, setzen Sie die ResponseFormat-Eigenschaft von GetBlobsOptions auf StorageResponseFormat.Arrow und geben Sie dann die Optionen an den BlobContainerClient.GetBlobs-Overload weiter, der akzeptiert GetBlobsOptions. Wenn Sie die Apache Arrow-Ausgabe verwenden, können Sie auch die Eigenschaften 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:

using Azure.Storage;
using Azure.Storage.Blobs.Models;

GetBlobsOptions options = new GetBlobsOptions
{
    Prefix = "FolderA/",
    ResponseFormat = StorageResponseFormat.Arrow
};

foreach (BlobItem blobItem in containerClient.GetBlobs(options))
{
    Console.WriteLine("Blob name: " + blobItem.Name);
}

Ressourcen

Um mehr darüber zu erfahren, wie man Blobs mit der Azure Blob Storage-Clientbibliothek für .NET auflistet, siehe die folgenden Ressourcen.

REST-API-Vorgänge

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

Ressourcen zur Clientbibliothek

Siehe auch

Zugehöriger Inhalt

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