Schnellstart: Azure Blob Storage-Clientbibliothek für Python

Hinweis

Die Option Von Grund auf neu erstellen führt Sie schrittweise durch den Prozess des Erstellens eines neuen Projekts, das Installieren von Paketen, das Schreiben des Codes und das Ausführen einer einfachen Konsolen-App. Dieser Ansatz wird empfohlen, wenn Sie alle Details zum Erstellen einer App verstehen möchten, die eine Verbindung mit Azure Blob Storage herstellt. Wenn Sie Bereitstellungsaufgaben automatisieren und mit einem abgeschlossenen Projekt beginnen möchten, wählen Sie Mit einer Vorlage beginnen.

Hinweis

Die Option Mit einer Vorlage beginnen verwendet die Azure Developer CLI, um Bereitstellungsaufgaben zu automatisieren, damit sie mit einem abgeschlossenen Projekt starten. Dieser Ansatz wird empfohlen, wenn Sie den Code so schnell wie möglich erkunden möchten, ohne die Setupaufgaben durchzugehen. Wenn Sie Schritt-für-Schritt-Anleitungen zum Erstellen der App bevorzugen, wählen Sie Von Grund auf neu erstellen aus.

Erste Schritte mit der Azure Blob Storage-Clientbibliothek für Python zum Verwalten von Blobs und Containern.

In diesem Artikel führen Sie die Schritte zum Installieren des Pakets aus und testen den Beispielcode für grundlegende Aufgaben.

In diesem Artikel verwenden Sie die Azure Developer CLI, um Azure-Ressourcen bereitzustellen und eine fertige Konsolen-App mit nur wenigen Befehlen auszuführen.

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (PyPI) | Beispiele

In diesem Video wird gezeigt, wie Sie mit der Verwendung der Azure Blob Storage-Clientbibliothek für Python beginnen.

Die Schritte im Video werden auch in den folgenden Abschnitten beschrieben.

Voraussetzungen

Einrichten

In diesem Abschnitt wird beschrieben, wie ein Projekt zur Verwendung mit der Azure Blob Storage-Clientbibliothek für Python vorbereitet wird.

Erstellen des Projekts

Erstellen Sie eine Python-Anwendung mit dem Namen blob-quickstart.

  1. Erstellen Sie in einem Konsolenfenster (z. B. PowerShell oder Bash) ein neues Verzeichnis für das Projekt:

    mkdir blob-quickstart

  2. Wechseln Sie zu dem neu erstellten Verzeichnis blob-quickstart:

    cd blob-quickstart

Installieren der Pakete

Installieren Sie im Projektverzeichnis Pakete für die Azure Blob Storage- und Azure Identity-Clientbibliotheken mithilfe des Befehls pip install. Sie benötigen das paket azure-identity für kennwortlose Verbindungen mit Azure Diensten.

pip install azure-storage-blob azure-identity

Einrichten des App-Frameworks

Führen Sie im Projektverzeichnis die folgenden Schritte aus, um die grundlegende Struktur der App zu erstellen:

  1. Öffnen Sie eine neue Textdatei im Code-Editor.
  2. Fügen Sie import Anweisungen hinzu, erstellen Sie die Struktur für das Programm, und fügen Sie eine grundlegende Ausnahmebehandlung hinzu, wie im folgenden Beispiel gezeigt.
  3. Speichern Sie die neue Datei als blob_quickstart.py im Verzeichnis blob-quickstart.
import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

Wenn Sie Azure Developer CLI installieren, können Sie ein Speicherkonto erstellen und den Beispielcode mit nur wenigen Befehlen ausführen. Sie können das Projekt in Ihrer lokalen Entwicklungsumgebung oder in einem DevContainer- ausführen.

Initialisieren der Azure Developer CLI-Vorlage und Bereitstellen von Ressourcen

Führen Sie aus einem leeren Verzeichnis die folgenden Schritte aus, um die azd-Vorlage zu initialisieren, Azure-Ressourcen bereitzustellen und mit dem Code zu beginnen:

  • Klonen Sie die Schnellstart-Repositoryressourcen von GitHub und initialisieren Sie die Vorlage lokal:

    azd init --template blob-storage-quickstart-python

    Sie werden zur Eingabe der folgenden Informationen aufgefordert:

    • Environment name: Azure Developer CLI verwendet diesen Wert als Präfix für alle Azure Ressourcen, die sie erstellt. Der Name muss für alle Azure Abonnements eindeutig sein und zwischen 3 und 24 Zeichen lang sein. Der Name darf nur Ziffern und Kleinbuchstaben enthalten.

  • Melden Sie sich bei Azure an:

    azd auth login

  • Bereitstellen der Ressourcen in Azure:

    azd up

    Sie werden zur Eingabe der folgenden Informationen aufgefordert:

    • Abonnement: Das Azure-Abonnement, an das Ihre Ressourcen bereitgestellt werden.
    • Standort: Die Azure-Region, in der Ihre Ressourcen bereitgestellt werden.

    Die Bereitstellung kann einige Minuten dauern. Die Ausgabe des azd up Befehls enthält den Namen des neu erstellten Speicherkontos, das Sie später zum Ausführen des Codes benötigen.

Führen Sie den Beispielcode aus

Zu diesem Zeitpunkt haben Sie die Ressourcen für Azure bereitgestellt, und der Code kann fast ausgeführt werden. Führen Sie die folgenden Schritte aus, um Pakete zu installieren, den Namen des Speicherkontos im Code zu aktualisieren und die Beispielkonsolen-App auszuführen:

  • Install packages: Installieren Sie im lokalen Verzeichnis Pakete für die Azure Blob Storage- und Azure Identity-Clientbibliotheken, indem Sie den folgenden Befehl ausführen: pip install azure-storage-blob azure-identity
  • Aktualisieren Sie den Namen des Speicherkontos: Bearbeiten Sie im lokalen Verzeichnis die Datei mit dem Namen blob_quickstart.py. Suchen Sie den <storage-account-name>-Platzhalter und ersetzen Sie ihn durch den tatsächlichen Namen des Speicherkontos, das vom Befehl azd up erstellt wurde. Speichern Sie die Änderungen.
  • Führen Sie das Projekt aus: Führen Sie den folgenden Befehl aus, um die App auszuführen: python blob_quickstart.py
  • Beobachten Sie die Ausgabe: Diese App erstellt eine Testdatei in Ihrem lokalen Daten-Ordner und lädt sie in einen Container im Speicherkonto hoch. Anschließend werden im Beispiel die Blobs im Container aufgelistet, und die Datei wird mit einem neuen Namen heruntergeladen, damit Sie die alte und neue Datei vergleichen können.

Weitere Informationen zur Funktionsweise des Beispielcodes finden Sie in Codebeispielen.

Wenn Sie mit dem Testen des Codes fertig sind, lesen Sie den Abschnitt Bereinigen von Ressourcen, um die vom Befehl azd up erstellten Ressourcen zu löschen.

Objektmodell

Azure Blob Storage ist für die Speicherung großer Mengen unstrukturierter Daten optimiert. Unstrukturierte Daten sind Daten, die keinem bestimmten Datenmodell und keiner bestimmten Definition entsprechen (also beispielsweise Text- oder Binärdaten). Blob Storage bietet drei Typen von Ressourcen:

  • Das Speicherkonto
  • Einen Container im Speicherkonto
  • Ein Blob im Container

Das folgende Diagramm zeigt die Beziehung zwischen diesen Ressourcen:

Screenshot der Blob-Speicherarchitektur mit einem Speicherkonto, einem Container und Blobs.

Verwenden Sie die folgenden Python-Klassen zur Interaktion mit diesen Ressourcen:

  • BlobServiceClient: Verwenden Sie die Klasse BlobServiceClient, um mit Azure Storage Ressourcen und BLOB-Containern zu arbeiten.
  • ContainerClient: Verwenden Sie die Klasse ContainerClient, um mit Azure Storage Containern und deren Blobs zu arbeiten.
  • BlobClient: Verwenden Sie die Klasse BlobClient, um mit Azure Storage Blobs zu arbeiten.

Codebeispiele

Mit diesen Beispielcodeausschnitten wird veranschaulicht, wie folgende Vorgänge mit der Azure Blob Storage-Clientbibliothek für Python durchgeführt werden:

Hinweis

Die Azure Developer CLI-Vorlage enthält eine Datei mit bereits vorhandenem Beispielcode. Die folgenden Beispiele enthalten Details für jeden Teil des Beispielcodes. Die Vorlage implementiert die empfohlene kennwortlose Authentifizierungsmethode, wie im Abschnitt Authentifizieren bei Azure beschrieben. Die Verbindungszeichenfolgenmethode wird als Alternative angezeigt, wird jedoch nicht in der Vorlage verwendet und wird nicht für Produktionscode empfohlen.

Authentifizieren bei Azure und Autorisieren des Zugriffs auf Blobdaten

Anwendungsanforderungen an Azure Blob Storage müssen autorisiert werden. Die Verwendung der von der Azure Identity-Clientbibliothek bereitgestellten Klasse DefaultAzureCredential ist der empfohlene Ansatz zum Implementieren von kennwortlosen Verbindungen mit Azure-Diensten in Ihrem Code, einschließlich Blob Storage.

Sie können Anforderungen an Azure Blob Storage auch mithilfe des Kontozugriffsschlüssels autorisieren. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen darauf achten, dass die Zugriffsschlüssel niemals an einem unsicheren Ort offengelegt werden. Jeder, der über den Zugriffsschlüssel verfügt, kann Anforderungen für das Speicherkonto autorisieren und hat somit Zugriff auf alle Daten. DefaultAzureCredential bietet verbesserte Verwaltungs- und Sicherheitsvorteile gegenüber dem Kontoschlüssel, um kennwortlose Authentifizierung zu ermöglichen. Beide Optionen werden im folgenden Beispiel veranschaulicht.

„DefaultAzureCredential“ unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet wird. Bei diesem Ansatz kann Ihre App unterschiedliche Authentifizierungsmethoden in verschiedenen Umgebungen (lokal gegenüber Produktion) verwenden, ohne umgebungsspezifischen Code zu implementieren.

Sie finden die Reihenfolge und die Speicherorte, an denen DefaultAzureCredential nach Anmeldeinformationen sucht, in der Übersicht zur Azure Identity-Bibliothek.

Zum Beispiel kann sich Ihre App während der lokalen Entwicklung mithilfe Ihrer Azure CLI-Anmeldeinformationen authentifizieren. Ihre App kann dann eine managed Identity verwenden, nachdem sie für Azure bereitgestellt wurde. Für diesen Übergang sind keine Änderungen am Code erforderlich.

Weisen Sie Ihrem Microsoft Entra-Benutzerkonto Rollen zu.

Stellen Sie bei lokaler Entwicklung sicher, dass das Benutzerkonto, das auf Blobdaten zugreift, über die richtigen Berechtigungen verfügt. Sie benötigen die Rolle Storage Blob Data Contributor, um Blobdaten zu lesen und zu schreiben. Um sich selbst diese Rolle zuweisen zu können, benötigen Sie die Rolle Benutzerzugriffsadministrator oder eine andere Rolle, die die Aktion Microsoft.Authorization/roleAssignments/write enthält. Sie können einem Benutzer Azure RBAC-Rollen über das Azure-Portal, die Azure CLI oder mit Azure PowerShell zuweisen. Weitere Informationen zur Rolle " Storage Blob Data Contributor " finden Sie unter "Storage Blob Data Contributor". Weitere Informationen zu den verfügbaren Bereichen für Rollenzuweisungen finden Sie unter Grundlegendes zum Bereich für Azure RBAC.

In diesem Szenario weisen Sie Ihrem Benutzerkonto Berechtigungen zu, die auf das Speicherkonto zugeschnitten sind, um dem Prinzip der geringsten Rechte zu folgen. Auf diese Weise erhalten Benutzer nur die erforderlichen Mindestberechtigungen, und es entstehen sicherere Produktionsumgebungen.

Im folgenden Beispiel wird Ihrem Benutzerkonto die Rolle Mitwirkender an Storage-Blobdaten zugewiesen, die sowohl Lese- als auch Schreibzugriff auf Blobdaten in Ihrem Speicherkonto ermöglicht.

Wichtig

In den meisten Fällen dauert es eine oder zwei Minute(n), bis die Rollenzuweisung in Azure weitergegeben wird. In seltenen Fällen kann es aber bis zu acht Minuten dauern. Wenn bei der ersten Ausführung Ihres Codes Authentifizierungsfehler auftreten, warten Sie einige Momente, und versuchen Sie es dann erneut.

  1. Suchen Sie im Azure-Portal Ihr Speicherkonto mithilfe der Hauptsuchleiste oder der linken Navigationsleiste.

  2. Wählen Sie auf der Übersichtsseite des Speicherkontos im linken Menü die Option Zugriffssteuerung (IAM) aus.

  3. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Registerkarte Rollenzuweisungen aus.

  4. Wählen Sie im oberen Menü + Hinzufügen und aus dem dann angezeigten Dropdownmenü die Option Rollenzuweisung hinzufügen aus.

    Ein Screenshot zeigt, wie eine Rolle zugewiesen wird.

  5. Über das Suchfeld können Sie die Ergebnisse für die gewünschte Rolle filtern. Suchen Sie in diesem Beispiel nach Mitwirkender an Speicherblobdaten, wählen Sie das entsprechende Ergebnis und dann Weiter aus.

  6. Wählen Sie unter Zugriff zuweisen zu die Option Benutzer, Gruppe oder Dienstprinzipal und dann die Option + Mitglieder auswählen aus.

  7. Suchen Sie im Dialogfeld nach Ihrem Microsoft Entra-Benutzernamen (normalerweise Ihre E-Mail-Adresse benutzer@domäne), und wählen Sie unten im Dialogfeld Auswählen aus.

  8. Wählen Sie Überprüfen und zuweisen aus, um zur letzten Seite zu gelangen, und wählen Sie erneut Überprüfen und zuweisen aus, um den Vorgang abzuschließen.

Melden Sie sich an, und verbinden Sie Ihren App-Code mit Azure mithilfe von DefaultAzureCredential

Führen Sie die folgenden Schritte aus, um den Zugriff auf Daten in Ihrem Speicherkonto zu autorisieren:

  1. Stellen Sie sicher, dass Sie mit demselben Microsoft Entra-Konto authentifiziert sind, dem Sie die Rolle für Ihr Speicherkonto zugewiesen haben. Dann können Sie sich über die Azure-Befehlszeilenschnittstelle (Azure CLI), Visual Studio Code oder Azure PowerShell authentifizieren.

    Melden Sie sich mit dem folgenden Befehl bei Azure über die Azure CLI an:

    az login

  2. Wenn Sie DefaultAzureCredential verwenden möchten, vergewissern Sie sich, dass das azure-identity-Paket installiert ist und die Klasse importiert wurde:

    from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

  3. Fügen Sie diesen Code im try-Block hinzu. Wenn der Code auf Ihrer lokalen Workstation ausgeführt wird, verwendet DefaultAzureCredential zur Authentifizierung bei Azure die Entwickleranmeldeinformationen des Tools mit der höchsten Priorität, bei dem Sie angemeldet sind. Beispiele für diese Tools sind die Azure CLI oder Visual Studio Code.

    account_url = "https://<storageaccountname>.blob.core.windows.net"
default_credential = DefaultAzureCredential()

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

  4. Aktualisieren Sie den Namen des Speicherkontos im URI Ihres BlobServiceClient Objekts. Sie finden den Namen des Speicherkontos auf der Übersichtsseite des Azure Portals.

    Screenshot der Seite im Azure-Portal mit Hervorhebung des Namens des Speicherkontos.

    Hinweis

    Wenn er für Azure bereitgestellt wird, kann dieser Code Anforderungen zum Azure Storage von einer Anwendung autorisieren, die in Azure ausgeführt wird. Sie müssen jedoch verwaltete Identitäten in Ihrer App in Azure aktivieren. Konfigurieren Sie dann Ihr Speicherkonto, um dieser verwalteten Identität das Herstellen einer Verbindung zu ermöglichen. Ausführliche Anleitungen zum Konfigurieren dieser Verbindung zwischen Azure-Diensten finden Sie im Tutorial Auth from Azure-hosted apps (Autorisieren aus von Azure gehosteten Apps).

Container erstellen

Erstellen Sie einen neuen Container in Ihrem Speicherkonto, indem Sie die Methode create_container für das blob_service_client-Objekt aufrufen. In diesem Beispiel fügt der Code einen GUID-Wert an den Containernamen an, damit dieser eindeutig ist.

Fügen Sie diesen Code am Ende des try-Blocks hinzu:

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

Weitere Informationen zum Erstellen eines Containers und weitere Codebeispiele zum Erkunden finden Sie unter Erstellen eines Blobcontainers mit Python.

Wichtig

Die Containernamen müssen klein geschrieben werden. Weitere Informationen zum Benennen von Containern und Blobs finden Sie unter Naming and Referencing Containers, Blobs, and Metadata (Benennen von Containern, Blobs und Metadaten und Verweisen auf diese).

Hochladen von Blobs in einen Container

Hochladen eines Blobs in einen Container mithilfe von upload_blob. Der Beispielcode erstellt eine Textdatei im lokalen Datenverzeichnis, die in den Container hochgeladen werden soll.

Fügen Sie diesen Code am Ende des try-Blocks hinzu:

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

Weitere Informationen zum Hochladen von Blobs und weitere Codebeispiele finden Sie unter Upload a blob with Python.

Listen Sie die Blobs in einem Container auf.

Listen Sie die Blobs im Container auf, indem Sie die list-blobs-Methode aufrufen. In diesem Fall wurde dem Container nur ein Blob hinzugefügt, sodass beim Auflisten auch nur ein Blob zurückgegeben wird.

Fügen Sie diesen Code am Ende des try-Blocks hinzu:

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

Weitere Informationen zum Auflisten von Blobs und weitere Codebeispiele finden Sie unter List blobs mit Python.

Blobs herunterladen

Laden Sie das zuvor erstellte Blob herunter, indem Sie die download_blob-Methode aufrufen. Im Beispielcode wird das Suffix „DOWNLOAD“ an den Dateinamen angefügt, damit beide Dateien im lokalen Dateisystem angezeigt werden können.

Fügen Sie diesen Code am Ende des try-Blocks hinzu:

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

Weitere Informationen zum Herunterladen von Blobs und weitere Codebeispiele zum Erkunden finden Sie unter Herunterladen eines Blobs mit Python.

Löschen eines Containers

Der folgende Code bereinigt die Ressourcen, die die App erstellt hat, indem der gesamte Container mithilfe der delete_container-Methode entfernt wird. Sie können die lokalen Dateien auch löschen, wenn Sie möchten.

Die App pausiert für eine Benutzereingabe durch Aufrufen von input(), bevor sie das Blob, den Container und die lokalen Dateien löscht. Überprüfen Sie, ob die Ressourcen ordnungsgemäß erstellt wurden, bevor sie gelöscht werden.

Fügen Sie diesen Code am Ende des try-Blocks hinzu:

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

Weitere Informationen zum Löschen eines Containers und weitere Codebeispiele finden Sie unter Delete und Wiederherstellen eines BLOB-Containers mit Python.

Ausführen des Codes

Mit dieser App wird in Ihrem lokalen Ordner eine Testdatei erstellt und in Azure Blob Storage hochgeladen. Im Beispiel werden dann die Blobs im Container aufgelistet, und die Datei wird mit einem neuen Namen heruntergeladen. Sie können die alten und neuen Dateien vergleichen.

Wechseln Sie zu dem Verzeichnis, das die blob_quickstart.py Datei enthält, und führen Sie den folgenden python Befehl aus, um die App auszuführen:

python blob_quickstart.py

Die Ausgabe der App ähnelt dem folgenden Beispiel (UUID-Werte zur besseren Lesbarkeit weggelassen):

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Überprüfen Sie den Ordner data vor dem Start der Bereinigung auf die beiden Dateien. Sie können sie vergleichen und sehen, dass sie identisch sind.

Bereinigen von Ressourcen

Nachdem Sie die Dateien überprüft und die Tests abgeschlossen haben, drücken Sie die EINGABETASTE , um die Testdateien zusammen mit dem Container zu löschen, den Sie im Speicherkonto erstellt haben. Sie können Ressourcen auch mit der Azure-Befehlszeilenschnittstelle löschen.

Wenn Sie mit der Schnellstartanleitung fertig sind, bereinigen Sie die Ressourcen, die Sie erstellt haben, indem Sie den folgenden Befehl ausführen:

azd down

Sie werden aufgefordert, die Löschung der Ressourcen zu bestätigen. Drücken Sie zur Bestätigung y.

Nächster Schritt

Azure Storage-Beispiele und -Entwicklerleitfäden für Python

  • Last updated on