Share via

Azure Storage File Share-Clientbibliothek für Python– Version 12.15.0

  • Artikel

Azure File Share Storage bietet vollständig verwaltete Dateifreigaben in der Cloud, auf die über das branchenübliche SMB-Protokoll (Server Message Block) zugegriffen werden kann. Azure-Dateifreigaben können gleichzeitig durch die Cloud oder lokale Bereitstellungen von Windows, Linux und macOS eingebunden werden. Außerdem können Azure-Dateifreigaben auf Windows-Servern mit der Azure-Dateisynchronisierung zwischengespeichert werden, um einen schnellen Zugriff in der Nähe des Datennutzungsorts zu gewährleisten.

Verwendungsmöglichkeiten für Azure-Dateifreigaben:

  • Ersetzen oder Ergänzen lokaler Dateiserver
  • "Lift and Shift"-Anwendungen
  • Vereinfachen der Cloudentwicklung mit freigegebenen Anwendungseinstellungen, Diagnosefreigaben und Dev/Test/Debug-Tools

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

Erste Schritte

Voraussetzungen

Installieren des Pakets

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

pip install azure-storage-file-share

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-Dateifreigabe-Clientbibliothek für Python können Sie mit vier Arten von Ressourcen interagieren: dem Speicherkonto selbst, Dateifreigaben, Verzeichnissen und Dateien. Die Interaktion mit diesen Ressourcen beginnt mit einer instance eines Clients. Zum Erstellen eines Clientobjekts benötigen Sie die Dateidienst-URL des Speicherkontos und eine Anmeldeinformation, die Ihnen den Zugriff auf das Speicherkonto ermöglicht:

from azure.storage.fileshare import ShareServiceClient

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

Nachschlagen der Konto-URL

Sie finden die Dateidienst-URL des Speicherkontos über das Azure-Portal, Azure PowerShell oder die Azure CLI:

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

Typen von Anmeldeinformationen

Der credential Parameter kann in verschiedenen Formen bereitgestellt werden, je nachdem, welche Autorisierung Sie verwenden möchten:

  1. 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, die Freigabe oder die Datei zu erstellen:

    from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, 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)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)

  2. Um einen freigegebenen Speicherkontoschlüssel (auch als Kontoschlüssel oder Zugriffsschlüssel bezeichnet) zu verwenden, geben Sie den Schlüssel als Zeichenfolge an. 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.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")

Erstellen des Clients aus einer Verbindungszeichenfolge

Abhängig von Ihrem Anwendungsfall und Ihrer Autorisierungsmethode können Sie es vorziehen, einen Client instance mit einer 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.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.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-Dateifreigabedienst besteht aus den folgenden Komponenten:

  • Das Speicherkonto selbst
  • Eine Dateifreigabe innerhalb des Speicherkontos
  • Eine optionale Hierarchie von Verzeichnissen innerhalb der Dateifreigabe
  • Eine Datei innerhalb der Dateifreigabe, die bis zu 1 TiB groß sein kann

Mit der Azure Storage-Dateifreigabe-Clientbibliothek für Python können Sie mit jeder dieser Komponenten mithilfe eines dedizierten Clientobjekts interagieren.

Asynchrone Clients

Diese Bibliothek enthält eine vollständige asynchrone API, die unter Python 3.5 und höher unterstützt wird. Um es 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.

Clients

Vier verschiedene Clients werden für die Interaktion mit den verschiedenen Komponenten des Dateifreigabediensts bereitgestellt:

  1. ShareServiceClient : Dieser Client stellt die Interaktion mit dem Azure-Speicherkonto selbst dar und ermöglicht es Ihnen, vorkonfigurierte Clientinstanzen für den Zugriff auf die Darin enthaltenen Dateifreigaben abzurufen. Es bietet Vorgänge zum Abrufen und Konfigurieren der Diensteigenschaften sowie zum Auflisten, Erstellen und Löschen von Freigaben innerhalb des Kontos. Um Vorgänge für eine bestimmte Freigabe auszuführen, rufen Sie einen Client mithilfe der get_share_client -Methode ab.
  2. ShareClient : Dieser Client stellt die Interaktion mit einer bestimmten Dateifreigabe dar (die noch nicht vorhanden sein muss), und ermöglicht es Ihnen, vorkonfigurierte Clientinstanzen für den Zugriff auf die Verzeichnisse und Dateien darin zu erhalten. Es stellt Vorgänge zum Erstellen, Löschen, Konfigurieren oder Erstellen von Momentaufnahmen einer Freigabe bereit und umfasst Vorgänge zum Erstellen und Aufzählen der Inhalte der Darin enthaltenen Verzeichnisse. Um Vorgänge für ein bestimmtes Verzeichnis oder eine bestimmte Datei auszuführen, rufen Sie einen Client mit den get_directory_client Methoden oder get_file_client ab.
  3. ShareDirectoryClient : Dieser Client stellt die Interaktion mit einem bestimmten Verzeichnis dar (das noch nicht vorhanden sein muss). Es stellt Vorgänge zum Erstellen, Löschen oder Aufzählen des Inhalts eines unmittelbaren oder geschachtelten Unterverzeichnisses bereit und umfasst Vorgänge zum Erstellen und Löschen von Dateien darin. Bei Vorgängen, die sich auf ein bestimmtes Unterverzeichnis oder eine bestimmte Datei beziehen, kann ein Client für diese Entität auch mithilfe der get_subdirectory_client Funktionen und get_file_client abgerufen werden.
  4. ShareFileClient : Dieser Client stellt die Interaktion mit einer bestimmten Datei dar (die noch nicht vorhanden sein muss). Es bietet Vorgänge zum Hochladen, Herunterladen, Erstellen, Löschen und Kopieren einer Datei.

Ausführliche Informationen zu Einschränkungen bei der Pfadbenennung finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Aufgaben der Speicherdateifreigabe abdecken, einschließlich:

Erstellen einer Dateifreigabe

Erstellen einer Dateifreigabe zum Speichern Ihrer Dateien

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

Verwenden des asynchronen Clients zum Erstellen einer Dateifreigabe

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

Hochladen einer Datei

Hochladen einer Datei in die Freigabe

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

Asynchrones Hochladen einer Datei

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

Herunterladen einer Datei

Herunterladen einer Datei aus der Freigabe

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

Asynchrones Herunterladen einer Datei

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

Auflisten der Inhalte eines Verzeichnisses

Auflisten aller Verzeichnisse und Dateien unter einem übergeordneten Verzeichnis

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

Asynchrones Auflisten der Inhalte eines Verzeichnisses

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

Optionale Konfiguration

Optionale 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): Gesamtzahl der zuzulassenden Wiederholungen. Hat Vorrang vor anderen Zählungen. retry_total=0 Übergeben Sie, wenn Sie bei Anforderungen keinen Wiederholungsversuch durchführen möchten. Der Standardwert ist 10.
  • retry_connect (int): Gibt an, wie viele Verbindungsfehler wiederholt werden sollen. Der Standardwert ist 3.
  • retry_read (int): Gibt an, wie oft bei Lesefehlern wiederholt werden soll. Der Standardwert ist 3.
  • retry_status (int): Gibt an, wie oft bei fehlerhaften status Codes wiederholt werden soll. Der Standardwert ist 3.
  • retry_to_secondary (bool): Gibt an, ob die Anforderung ggf. an die sekundäre Anforderung wiederholt werden soll. Dies sollte nur aktiviert werden, wenn RA-GRS-Konten verwendet werden, und möglicherweise veraltete Daten können verarbeitet werden. Der Standardwert lautet False.

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

Speicherdateiclients lösen in Azure Core definierte Ausnahmen aus.

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.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
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 = ShareServiceClient.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_properties(logging_enable=True)

Nächste Schritte

Weiterer Beispielcode

Erste Schritte mit unseren Dateifreigabebeispielen.

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

  • file_samples_hello_world.py (asynchrone Version): Beispiele in diesem Artikel:

    • Clienterstellung
    • Erstellen einer Dateifreigabe
    • Hochladen einer Datei

  • file_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

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

    • Abrufen und Festlegen von Diensteigenschaften
    • Erstellen, Auflisten und Löschen von Freigaben
    • Abrufen eines Freigabeclients

  • file_samples_share.py (asynchrone Version): Beispiele für die Interaktion mit Dateifreigaben:

    • Erstellen einer Freigabemomentaufnahme
    • Festlegen von Freigabekontingent und Metadaten
    • Auflisten von Verzeichnissen und Dateien
    • Abrufen des Verzeichnisses oder Dateiclients für die Interaktion mit einer bestimmten Entität

  • file_samples_directory.py (asynchrone Version): Beispiele für die Interaktion mit Verzeichnissen:

    • Erstellen eines Verzeichnisses und Hinzufügen von Dateien
    • Erstellen und Löschen von Unterverzeichnissen
    • Abrufen des Unterverzeichnisclients

  • file_samples_client.py (asynchrone Version): Beispiele für die Interaktion mit Dateien:

    • Erstellen, Hochladen, Herunterladen und Löschen von Dateien
    • Kopieren einer Datei aus einer URL

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zum Azure-Dateifreigabespeicher finden Sie in der Azure File Share Storage-Dokumentation 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.