Blobs mit Python auflisten

Dieser Artikel zeigt, wie man Blobs mit der Azure Storage-Clientbibliothek für Python auflistet.

Um mehr über das Auflisten von Blobs durch asynchrone APIs zu erfahren, siehe List Blobs asynchronously.

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• Azure Storage-Konto – Erstellen eines Speicherkontos
• Python 3.8+

Richten Sie Ihre Umgebung ein

Wenn Sie kein vorhandenes Projekt haben, wird in diesem Abschnitt gezeigt, wie Sie ein Projekt für die Arbeit mit der Azure Blob Storage-Clientbibliothek für Python einrichten. Weitere Details finden Sie unter Erste Schritte mit Azure Blob Storage und Python.

Um die Codebeispiele in diesem Artikel zu verwenden, führen Sie die folgenden Schritte zum Einrichten Ihres Projekts aus.

Installieren von Paketen

Installieren Sie die folgenden Pakete mittels pip install:

pip install azure-storage-blob azure-identity

Importanweisungen hinzufügen

Fügen Sie die folgenden import -Anweisungen ein:

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobPrefix

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

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:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

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

Informationen über Optionen für das Auflisten von Blobs

Wenn du Blobs aus deinem Code auflistest, kannst du viele Optionen angeben, um zu steuern, wie die Ergebnisse von Azure Storage zurückkommen. 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 eine dieser Methoden auf:

• ContainerClient.list_blobs (zusammen mit dem Namen optional Metadaten, Tags und andere Informationen zu jedem Blob enthalten)
• ContainerClient.list_blob_names (Gibt nur den Blobnamen zurück.)

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

• ContainerClient.walk_blobs (neben dem Namen optional Metadaten, Tags und andere Informationen zu jedem Blob hinzufügen)

Filtern von Ergebnissen mit einem Präfix

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

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). Man kann jedoch Blobs in virtuelle Verzeichnisse organisieren, um eine Ordnerstruktur nachzuahmen. 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 du deine Blobs mit einem Delimiter benennenst, kannst du Blobs 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 führt die Blobs im angegebenen Container mithilfe einer flachen Auflistung auf:

def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

Die Beispielausgabe sieht in etwa so aus:

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

Sie können auch Optionen festlegen, um Listenergebnisse zu filtern oder weitere Informationen anzuzeigen. Im folgenden Beispiel werden Blobs und Blobtags aufgelistet:

def list_blobs_flat_options(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

Die Beispielausgabe sieht in etwa so aus:

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

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:

• ContainerClient.walk_blobs

Im folgenden Beispiel werden die Blobs im angegebenen Container mithilfe einer hierarchischen Auflistung aufgelistet:

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

Die Beispielausgabe sieht in etwa so aus:

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

Blobs asynchron auflisten

Die Azure Blob Storage-Clientbibliothek für Python unterstützt das asynchrone Auflisten von Blobs. Weitere Informationen zu den Projekteinrichtungsanforderungen finden Sie unter Asynchrone Programmierung.

Befolgen Sie diese Schritte, um Blobs mithilfe asynchroner APIs aufzulisten:

1. Fügen Sie die folgenden import-Anweisungen hinzu:

   import asyncio
   
   from azure.identity.aio import DefaultAzureCredential
   from azure.storage.blob.aio import BlobServiceClient, ContainerClient, BlobPrefix
   

2. Fügen Sie Code hinzu, um das Programm mithilfe von asyncio.run auszuführen. Diese Funktion führt die übergebene Koroutine, main() in diesem Beispiel, aus und verwaltet die Ereignisschleife asyncio. Koroutinen werden durch die Verwendung der async/await-Syntax deklariert. In diesem Beispiel erstellt die BlobServiceClient-Coroutine zunächst das async with der obersten Ebene unter Verwendung von main() und ruft dann die Methode auf, die die Blobs auflistet. Nur der Client auf oberster Ebene muss async with verwenden, da andere von ihr erstellte Clients denselben Verbindungspool verwenden.

   async def main():
       sample = BlobSamples()
   
       # TODO: Replace <storage-account-name> with your actual storage account name
       account_url = "https://<storage-account-name>.blob.core.windows.net"
       credential = DefaultAzureCredential()
   
       async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
           await sample.list_blobs_flat(blob_service_client, "sample-container")
   
   if __name__ == '__main__':
       asyncio.run(main())
   

3. Fügen Sie Code hinzu, um die Blobs aufzulisten. Das folgende Codebeispiel listet Blobs mit einer flachen Auflistung auf. Der Code ist derselbe wie im synchronen Beispiel, außer dass die Methode mit dem async Schlüsselwort deklariert wird und async for beim Aufruf der Methode list_blobs verwendet wird.

   async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
       container_client = blob_service_client.get_container_client(container=container_name)
   
       async for blob in container_client.list_blobs():
           print(f"Name: {blob.name}")
   

Mit dieser Grundaufstellung können Sie weitere Beispiele in diesem Artikel als Koroutinen mit asynchroner/await-Syntax implementieren.

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 Python SDK dekodiert Apache Arrow im Hintergrund und liefert weiterhin dieselben BlobProperties 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.

Um Ergebnisse im Apache-Arrow-Format anzufordern, setzen Sie das Schlüsselwortargument response_format beim Aufruf von ContainerClient.list_blobs oder ContainerClient.list_blob_names auf "arrow". Wenn Sie die Apache Arrow-Ausgabe verwenden, können Sie auch die start_from und end_before Schlüsselwort-Argumente einstellen, 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:

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

Ressourcen

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

Codebeispiele

• Sehen Sie sich in diesem Artikel synchrone oder asynchrone Codebeispiele (GitHub) an.

REST-API-Vorgänge

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

• Blobs auflisten (REST-API)

Ressourcen zur Clientbibliothek

• Referenzdokumentation zur Clientbibliothek
• Quellcode der Clientbibliothek
• Paket (PyPi)

Siehe auch

• Aufzählen von Blobressourcen
• Blobversionsverwaltung

Zugehöriger Inhalt

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