Azure Storage Blobs-Clientbibliothek für Python – Version 12.19.0

  • Artikel

Azure Blob Storage ist die Objektspeicherlösung von Microsoft für die Cloud. Blobspeicher ist für die Speicherung großer Mengen von unstrukturierten Daten, z.B. Text oder Binärdaten, optimiert.

Blobspeicher ist für folgende Zwecke ideal geeignet:

  • Speichern von Bildern oder Dokumenten direkt auf einem Browser
  • Speichern von Dateien für verteilten Zugriff
  • Video- und Audiostreaming
  • Speichern von Daten für Sicherung und Wiederherstellung, Notfallwiederherstellung und Archivierung
  • Speichern von Daten für Analysen durch einen lokalen oder von Azure gehosteten Dienst

Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Storage Blobs-Clientbibliothek für Python mit pip:

pip install azure-storage-blob

Speicherkonto erstellen

Wenn Sie ein neues Speicherkonto erstellen möchten, können Sie das Azure-Portal, Azure PowerShell oder die Azure CLI verwenden:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Erstellen des Clients

Mit der Azure Storage Blobs-Clientbibliothek für Python können Sie mit drei Arten von Ressourcen interagieren: dem Speicherkonto selbst, Blobspeichercontainern und Blobs. Die Interaktion mit diesen Ressourcen beginnt mit einer instance eines Clients. Zum Erstellen eines Clientobjekts benötigen Sie die Blobdienstkonto-URL des Speicherkontos und anmeldeinformationen, mit denen Sie auf das Speicherkonto zugreifen können:

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

Nachschlagen der Konto-URL

Sie können die Blobdienst-URL des Speicherkontos über das Azure-Portal, Azure PowerShell oder die Azure CLI finden:

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

Anmeldeinformationen

Der credential Parameter kann in verschiedenen Formen bereitgestellt werden, abhängig von der Art der Autorisierung , die Sie verwenden möchten:

  1. Um Azure Active Directory-Tokenanmeldeinformationen (AAD) zu verwenden, geben Sie eine instance des gewünschten Anmeldeinformationstyps an, der aus der Azure-Identity-Bibliothek abgerufen wird. Beispielsweise kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren.

    Dies erfordert eine anfängliche Einrichtung:

    Verwenden Sie die zurückgegebenen Tokenanmeldeinformationen, um den Client zu authentifizieren:

        from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )

  2. Um ein SAS-Token (Shared Access Signature) zu verwenden, geben Sie das Token als Zeichenfolge an. Wenn Ihre Konto-URL das SAS-Token enthält, lassen Sie den Parameter mit Anmeldeinformationen aus. Sie können ein SAS-Token im Azure-Portal unter "Shared Access Signature" generieren oder eine der generate_sas() Funktionen verwenden, um ein SAS-Token für das Speicherkonto, den Container oder das Blob zu erstellen:

    from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

  3. Geben Sie den Schlüssel als Zeichenfolge an, um einen freigegebenen Schlüssel des Speicherkontos (auch als Kontoschlüssel oder Zugriffsschlüssel bezeichnet) zu verwenden. Dies finden Sie im Azure-Portal im Abschnitt "Zugriffsschlüssel" oder indem Sie den folgenden Azure CLI-Befehl ausführen:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Verwenden Sie den Schlüssel als Anmeldeinformationsparameter, um den Client zu authentifizieren:

    from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")

    Wenn Sie eine benutzerdefinierte URL verwenden (was bedeutet, dass die URL nicht in diesem Format <my_account_name>.blob.core.windows.netvorliegt), instanziieren Sie den Client mithilfe der folgenden Anmeldeinformationen:

    from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})

  4. Um den anonymen öffentlichen Lesezugriff zu verwenden, lassen Sie einfach den Anmeldeinformationsparameter aus.

Erstellen des Clients aus einem Verbindungszeichenfolge

Abhängig von Ihrem Anwendungsfall und Ihrer Autorisierungsmethode können Sie es vorziehen, einen Client instance mit einem Speicher Verbindungszeichenfolge zu initialisieren, anstatt die Konto-URL und die Anmeldeinformationen separat bereitzustellen. Übergeben Sie dazu den Speicher Verbindungszeichenfolge an die Klassenmethode des from_connection_string Clients:

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

Die Verbindungszeichenfolge zu Ihrem Speicherkonto finden Sie im Azure-Portal unter dem Abschnitt „Zugriffsschlüssel“ oder indem Sie den folgenden CLI-Befehl ausführen:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Wichtige Begriffe

Der Azure Blob Service besteht aus den folgenden Komponenten:

  • Das Speicherkonto selbst
  • Ein Container innerhalb des Speicherkontos
  • Ein Blob in einem Container

Mit der Azure Storage Blobs-Clientbibliothek für Python können Sie mit jeder dieser Komponenten über ein dediziertes Clientobjekt interagieren.

Clients

Vier verschiedene Clients werden bereitgestellt, um mit den verschiedenen Komponenten des Blob-Diensts zu interagieren:

  1. BlobServiceClient : Dieser Client stellt die Interaktion mit dem Azure-Speicherkonto selbst dar und ermöglicht es Ihnen, vorkonfigurierte Clientinstanzen abzurufen, um auf die Container und Blobs in zuzugreifen. Es bietet Vorgänge zum Abrufen und Konfigurieren der Kontoeigenschaften sowie zum Auflisten, Erstellen und Löschen von Containern innerhalb des Kontos. Um Vorgänge für einen bestimmten Container oder Blob auszuführen, rufen Sie einen Client mithilfe der get_container_client -Methode oder get_blob_client ab.
  2. ContainerClient : Dieser Client stellt die Interaktion mit einem bestimmten Container dar (der noch nicht vorhanden sein muss) und ermöglicht es Ihnen, vorkonfigurierte Clientinstanzen für den Zugriff auf die Blobs in zu erwerben. Sie bietet Vorgänge zum Erstellen, Löschen oder Konfigurieren eines Containers und umfasst Vorgänge zum Auflisten, Hochladen und Löschen der darin enthaltenen Blobs. Um Vorgänge für ein bestimmtes Blob im Container auszuführen, rufen Sie einen Client mithilfe der get_blob_client -Methode ab.
  3. BlobClient : Dieser Client stellt die Interaktion mit einem bestimmten Blob dar (das noch nicht vorhanden sein muss). Es bietet Vorgänge zum Hochladen, Herunterladen, Löschen und Erstellen von Momentaufnahmen eines Blobs sowie spezifische Vorgänge pro Blobtyp.
  4. BlobLeaseClient: Dieser Client stellt Leaseinteraktionen mit einem oder BlobClientdarContainerClient. Es bietet Vorgänge zum Abrufen, Erneuern, Freigeben, Ändern und Unterbrechen einer Lease für eine angegebene Ressource.

Asynchrone Clients

Diese Bibliothek enthält eine vollständige asynchrone API, die unter Python 3.5 und höher unterstützt wird. Um ihn verwenden zu können, müssen Sie zuerst einen asynchronen Transport installieren, z. B. aiohttp. Weitere Informationen finden Sie in der Dokumentation zu azure-core .

Asynchrone Clients und Anmeldeinformationen sollten geschlossen werden, wenn sie nicht mehr benötigt werden. Diese Objekte sind asynchrone Kontext-Manager und definieren asynchrone close Methoden.

Blobtypen

Nachdem Sie einen Client initialisiert haben, können Sie zwischen den verschiedenen Blobtypen wählen:

  • Blockblobs speichern Text und Binärdaten bis zu ca. 4,75 TiB. Blockblobs bestehen aus Datenblöcken, die einzeln verwaltet werden können
  • Anfügeblobs bestehen wie Blockblobs aus Blöcken, sind aber für Anfügevorgänge optimiert. Anfügeblobs eignen sich ideal für Szenarien wie die Protokollierung von Daten von virtuellen Computern.
  • In Seitenblobs werden Random-Access-Dateien mit einer Größe von bis zu 8 TiB gespeichert. Seitenblobs speichern VHD-Dateien (Virtual Hard Drive) und dienen als Datenträger für virtuelle Azure-Computer

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Speicherblobaufgaben behandeln, einschließlich:

Beachten Sie, dass ein Container zuvor erstellt werden muss, um ein Blob hochzuladen oder herunterzuladen.

Erstellen eines Containers

Erstellen Sie einen Container, aus dem Sie Blobs hochladen oder herunterladen können.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

Verwenden des asynchronen Clients zum Hochladen eines Blobs

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Hochladen eines Blobs

Hochladen eines Blobs in Ihren Container

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

Verwenden des asynchronen Clients zum Hochladen eines Blobs

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Herunterladen eines Blobs

Herunterladen eines Blobs aus Ihrem Container

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

asynchrones Herunterladen eines Blobs

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Auflisten von Blobs

Auflisten der Blobs in Ihrem Container

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

Asynchrones Auflisten der Blobs

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

Optionale Konfiguration

Optional Schlüsselwort (keyword) Argumente, die auf Client- und Vorgangsebene übergeben werden können.

Konfiguration der Wiederholungsrichtlinie

Verwenden Sie die folgenden Schlüsselwort (keyword) Argumente, wenn Sie einen Client instanziieren, um die Wiederholungsrichtlinie zu konfigurieren:

  • retry_total (int): Gesamtanzahl der zuzulassenden Wiederholungen. Hat Vorrang vor anderen Zählungen. retry_total=0 Übergeben Sie den Vorgang, wenn Sie keine Wiederholung bei Anforderungen durchführen möchten. Der Standardwert ist 10.
  • retry_connect (int): Wie viele Verbindungsfehler wiederholt werden sollen. Der Standardwert ist 3.
  • retry_read (int): Wie oft Lesefehler wiederholt werden sollen. Der Standardwert ist 3.
  • retry_status (int): Wie oft bei fehlerhaften status Codes wiederholt werden soll. Der Standardwert ist 3.
  • retry_to_secondary (bool): Gibt an, ob die Anforderung an das sekundäre Ziel übergeben werden soll, sofern möglich. Dies sollte nur aktiviert werden, wenn RA-GRS-Konten verwendet werden und möglicherweise veraltete Daten verarbeitet werden können. Der Standardwert lautet False.

Verschlüsselungskonfiguration

Verwenden Sie die folgenden Schlüsselwort (keyword) Argumente, wenn Sie einen Client instanziieren, um die Verschlüsselung zu konfigurieren:

  • require_encryption (bool): Wenn auf True festgelegt ist, erzwingt, dass Objekte verschlüsselt und entschlüsselt werden.
  • encryption_version (str): Gibt die zu verwendende Verschlüsselungsversion an. Aktuelle Optionen sind '2.0' oder '1.0' , und der Standardwert ist '1.0'. Version 1.0 ist veraltet, und es wird dringend empfohlen , Version 2.0 zu verwenden.
  • key_encryption_key (Objekt): Der vom Benutzer bereitgestellte schlüssel-encryption-key. Die instance müssen die folgenden Methoden implementieren:
    • wrap_key(key)--umschließt den angegebenen Schlüssel mithilfe eines Algorithmus der Wahl des Benutzers.
    • get_key_wrap_algorithm()- gibt den Algorithmus zurück, der zum Umschließen des angegebenen symmetrischen Schlüssels verwendet wird.
    • get_kid()- gibt eine Zeichenfolgenschlüssel-ID für diesen Schlüssel-Verschlüsselungsschlüssel zurück.
  • key_resolver_function (aufrufbar): Der vom Benutzer bereitgestellte Schlüssellöser. Verwendet die Kid-Zeichenfolge, um einen Schlüssel-Verschlüsselung-Schlüssel zurückzugeben, der die oben definierte Schnittstelle implementiert.

Andere Client-/Pro-Vorgang-Konfiguration

Andere optionale Konfiguration Schlüsselwort (keyword) Argumente, die auf dem Client oder pro Vorgang angegeben werden können.

Client Schlüsselwort (keyword) Argumente:

  • connection_timeout (int): Die Anzahl der Sekunden, die der Client wartet, um eine Verbindung mit dem Server herzustellen. Die Standardwerte sind 20 Sekunden.
  • read_timeout (int): Die Anzahl der Sekunden, die der Client zwischen aufeinanderfolgenden Lesevorgängen auf eine Antwort vom Server wartet. Dies ist ein Timeout auf Socketebene, das sich nicht auf die Gesamtdatengröße auswirkt. Clientseitige Lesetimeouts werden automatisch wiederholt. Der Standardwert ist 60 Sekunden.
  • transport (Any): Vom Benutzer bereitgestellter Transport zum Senden der HTTP-Anforderung.

Pro Vorgang Schlüsselwort (keyword) Argumente:

  • raw_response_hook (aufrufbar): Der angegebene Rückruf verwendet die vom Dienst zurückgegebene Antwort.
  • raw_request_hook (aufrufbar): Der angegebene Rückruf verwendet die Anforderung, bevor sie an den Dienst gesendet wird.
  • client_request_id (str): Optional vom Benutzer angegebene Identifikation der Anforderung.
  • user_agent (str): Fügt den benutzerdefinierten Wert an den Benutzer-Agent-Header an, der mit der Anforderung gesendet werden soll.
  • logging_enable (bool): Aktiviert die Protokollierung auf DEBUG-Ebene. Der Standardwert lautet „False“. Kann auch auf Clientebene übergeben werden, um es für alle Anforderungen zu aktivieren.
  • logging_body (bool): Aktiviert die Protokollierung des Anforderungs- und Antworttexts. Der Standardwert lautet „False“. Kann auch auf Clientebene übergeben werden, um es für alle Anforderungen zu aktivieren.
  • headers (dict): Übergeben Sie benutzerdefinierte Header als Schlüssel- und Wertpaare. Beispiel: headers={'CustomValue': value}

Problembehandlung

Allgemein

Speicherblobclients lösen ausnahmen aus, die in Azure Core definiert sind.

Diese Liste kann als Verweis verwendet werden, um ausgelöste Ausnahmen abzufangen. Um den spezifischen Fehlercode der Ausnahme abzurufen, verwenden Sie das error_code -Attribut, d. h exception.error_code. .

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem logging_enable Argument aktiviert werden:

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:

service_client.get_service_stats(logging_enable=True)

Nächste Schritte

Weiterer Beispielcode

Erste Schritte mit unseren Blobbeispielen.

Im GitHub-Repository des SDK stehen Ihnen mehrere Python SDK-Beispiele für Storage Blobs zur Verfügung. Diese Beispiele enthalten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Speicherblobs auftreten:

  • blob_samples_container_access_policy.py (asynchrone Version): Beispiele zum Festlegen von Zugriffsrichtlinien:

    • Einrichten der Zugriffsrichtlinie für Container

  • blob_samples_hello_world.py (asynchrone Version): Beispiele für gängige Speicherblobaufgaben:

    • Einrichten eines Containers
    • Erstellen eines Block-, Seiten- oder Anfügeblobs
    • Hochladen von Blobs
    • Herunterladen von Blobs
    • Löschen von Blobs

  • blob_samples_authentication.py (asynchrone Version): Beispiele für die Authentifizierung und Erstellung des Clients:

    • Aus einem Verbindungszeichenfolge
    • Aus einem freigegebenen Zugriffsschlüssel
    • Aus einem Token für die Gemeinsame Zugriffssignatur
    • Aus Active Directory

  • blob_samples_service.py (asynchrone Version): Beispiele für die Interaktion mit dem Blobdienst:

    • Abrufen von Kontoinformationen
    • Abrufen und Festlegen von Diensteigenschaften
    • Abrufen von Dienststatistiken
    • Erstellen, Auflisten und Löschen von Containern
    • Abrufen des Blob- oder Containerclients

  • blob_samples_containers.py (asynchrone Version): Beispiele für die Interaktion mit Containern:

    • Erstellen eines Containers und Löschen von Containern
    • Festlegen von Metadaten für Container
    • Containereigenschaften abrufen
    • Abrufen einer Lease für Einen Container
    • Festlegen einer Zugriffsrichtlinie für einen Container
    • Hochladen, Auflisten und Löschen von Blobs im Container
    • Abrufen des Blobclients für die Interaktion mit einem bestimmten Blob

  • blob_samples_common.py (asynchrone Version): Beispiele, die allen Blobtypen gemeinsam sind:

    • Erstellen einer Momentaufnahme
    • Löschen eines Blob-Momentaufnahme
    • Vorläufiges Löschen eines Blobs
    • Wiederherstellen eines Blobs
    • Abrufen einer Lease für ein Blob
    • Kopieren eines Blobs aus einer URL

  • blob_samples_directory_interface.py – Beispiele für die Interfacing mit Blob Storage, als wäre es ein Verzeichnis in einem Dateisystem:

    • Kopieren (Hochladen oder Herunterladen) einer einzelnen Datei oder eines Verzeichnisses
    • Auflisten von Dateien oder Verzeichnissen auf einer einzelnen Ebene oder rekursiv
    • Löschen einer einzelnen Datei oder rekursives Löschen eines Verzeichnisses

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure Blob Storage finden Sie in der Dokumentation zu Azure Blob Storage auf docs.microsoft.com.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.