Herunterladen eines Blobs mit Python

  • Artikel

In diesem Artikel wird beschrieben, wie ein Blob mithilfe der Azure Storage-Clientbibliothek für Python heruntergeladen wird. Sie können Blobdaten an verschiedene Ziele herunterladen, einschließlich einen lokalen Dateipfad, einen Stream oder eine Textzeichenfolge. Sie können auch einen Blobstream öffnen und daraus lesen.

Informationen zum Herunterladen von Blobs mithilfe asynchroner APIs finden Sie unter Asynchrones Herunterladen von Blobs.

Voraussetzungen

Erstellen Ihrer Umgebung

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

Hinzufügen von Importanweisungen

Fügen Sie die folgenden import -Anweisungen ein:

import io
import os
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient

Autorisierung

Der Autorisierungsmechanismus muss über die erforderlichen Berechtigungen zum Ausführen eines Downloadvorgangs verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) benötigen Sie mindestens die integrierte Azure RBAC-Rolle Storage-Blobdatenleser. Weitere Informationen finden Sie im Autorisierungsleitfaden für Abrufen des 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.

Herunterladen eines Blobs

Sie können die folgende Methode verwenden, um ein Blob herunterzuladen:

Die Methode download_blob gibt ein StorageStreamDownloader-Objekt zurück. Während eines Downloads teilen die Clientbibliotheken die Downloadanforderung in Blöcke auf, wobei jeder Block mit einer separaten Anforderung zum Abrufen des Blobbereichs heruntergeladen wird. Dieses Verhalten hängt von der Gesamtgröße des Blobs ab und davon, wie die Datenübertragungsoptionen festgelegt sind.

Herunterladen in einen Dateipfad

Das folgende Beispiel lädt ein Blob in einen Dateipfad herunter:

def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob()
        sample_blob.write(download_stream.readall())

Herunterladen in einen Stream

Das folgende Beispiel lädt ein Blob in einen Stream herunter. In diesem Beispiel lädt StorageStreamDownloader.read_into den Blobinhalt in einen Stream herunter und gibt die Anzahl der gelesenen Bytes zurück:

def download_blob_to_stream(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # readinto() downloads the blob contents to a stream and returns the number of bytes read
    stream = io.BytesIO()
    num_bytes = blob_client.download_blob().readinto(stream)
    print(f"Number of bytes: {num_bytes}")

Herunterladen eines Blobs in Blöcken

Das folgende Beispiel lädt ein Blob herunter und durchläuft Blöcke im Downloadstream. In diesem Beispiel gibt StorageStreamDownloader.chunks einen Iterator zurück, mit dem Sie den Blobinhalt in Blöcken lesen können:

def download_blob_chunks(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # This returns a StorageStreamDownloader
    stream = blob_client.download_blob()
    chunk_list = []

    # Read data in chunks to avoid loading all into memory at once
    for chunk in stream.chunks():
        # Process your data (anything can be done here - 'chunk' is a byte array)
        chunk_list.append(chunk)

Herunterladen in eine Zeichenfolge

Das folgende Beispiel lädt den Blobinhalt als Text herunter. In diesem Beispiel ist der encoding-Parameter erforderlich, damit readall() eine Zeichenfolge zurückgibt. Andernfalls werden Bytes zurückgegeben:

def download_blob_to_string(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # encoding param is necessary for readall() to return str, otherwise it returns bytes
    downloader = blob_client.download_blob(max_concurrency=1, encoding='UTF-8')
    blob_text = downloader.readall()
    print(f"Blob contents: {blob_text}")

Herunterladen eines Blockblobs mit Konfigurationsoptionen

Beim Herunterladen eines Blobs können Sie Konfigurationsoptionen für die Clientbibliothek definieren. Diese Optionen können feiner abgestimmt werden, um die Leistung und Zuverlässigkeit zu verbessern. Die folgenden Codebeispiele zeigen, wie Sie Konfigurationsoptionen für einen Download sowohl auf Methodenebene als auch auf Clientebene beim Instanziieren von BlobClient definieren. Diese Optionen können auch für eine ContainerClient-Instanz oder eine BlobServiceClient-Instanz konfiguriert werden.

Angeben von Datenübertragungsoptionen beim Download

Sie können beim Instanziieren eines Clients Konfigurationsoptionen festlegen, um die Leistung für Datenübertragungsvorgänge zu optimieren. Sie können die folgenden Schlüsselwortargumente übergeben, wenn Sie ein Clientobjekt in Python erstellen:

  • max_chunk_get_size – Die maximale Blockgröße, die zum Herunterladen eines Blobs verwendet wird. Der Standardwert ist 4 MiB.
  • max_single_get_size – Die maximale Größe für ein Blob, das in einem einzigen Aufruf heruntergeladen werden soll. Wenn die Gesamtblobgröße max_single_get_size überschreitet, wird der Rest der Blobdaten in Blöcken heruntergeladen. Der Standardwert ist 32 MiB.

Bei Downloadvorgängen können Sie das max_concurrency-Argument auch übergeben, wenn Sie download_blob aufrufen. Dieses Argument definiert die maximale Anzahl paralleler Verbindungen für den Downloadvorgang.

Das folgende Codebeispiel zeigt, wie beim Erstellen eines BlobClient-Objekts Datenübertragungsoptionen angegeben und Daten mithilfe dieses Clientobjekts heruntergeladen werden. Die in diesem Beispiel angegebenen Werte sind nicht als Empfehlungen zu verstehen. Zur ordnungsgemäßen Optimierung dieser Werte müssen die spezifischen Anforderungen Ihrer App berücksichtigt werden.

def download_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for download
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_single_get_size=1024*1024*32, # 32 MiB
        max_chunk_get_size=1024*1024*4 # 4 MiB
    )

    with open(file=os.path.join(r'file_path', 'file_name'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob(max_concurrency=2)
        sample_blob.write(download_stream.readall())

Asynchrones Herunterladen von Blobs

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

Führen Sie die folgenden Schritte aus, um ein Blob mithilfe asynchroner APIs herunterzuladen:

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

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient

  2. Fügen Sie Code hinzu, um das Programm mithilfe von asyncio.run auszuführen. Diese Funktion führt die übergebene Coroutine aus, main() in unserem Beispiel, und verwaltet die Ereignisschleife von asyncio. Coroutinen werden mit der async/await-Syntax deklariert. In diesem Beispiel erstellt die Coroutine main() zunächst die oberste Ebene von BlobServiceClient mit async with und ruft dann die Methode auf, die das Blob herunterlädt. Beachten Sie, dass nur der Client auf oberster Ebene async withverwenden muss, da andere von ihm erstellte Clients denselben Verbindungspool aufweisen.

    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.download_blob_to_file(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())

  3. Fügen Sie Code zum Herunterladen des Blob hinzu. Das folgende Beispiel lädt ein Blob über ein BlobClient-Objekt in einen lokalen Dateipfad herunter. Der Code ist identisch mit dem synchronen Beispiel, mit der Ausnahme, dass die Methode mit dem Schlüsselwort „async“ deklariert wird und das Schlüsselwort „await‘‘ beim Aufrufen der Methode „download_blob“ verwendet wird.

    async def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = await blob_client.download_blob()
        data = await download_stream.readall()
        sample_blob.write(data)

Mit dieser grundlegenden Einrichtung können Sie weitere Beispiele in diesem Artikel als Coroutinen mit async/await-Syntax implementieren.

Ressourcen

Weitere Informationen zum Herunterladen von Blobs mithilfe der Azure Blob Storage-Clientbibliothek für Python finden Sie in den folgenden Ressourcen.

Codebeispiele

REST-API-Vorgänge

Das Azure SDK für Python enthält Bibliotheken, die auf der Azure-REST-API basieren, und ermöglicht Ihnen so die Interaktion mit REST-API-Vorgängen über vertraute Python-Paradigmen. Die Methoden der Clientbibliothek zum Herunterladen von Blobs verwenden den folgenden REST-API-Vorgang:

Ressourcen zur Clientbibliothek

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.