Azure DataLake-Dienstclientbibliothek für Python– Version 12.14.0

  • Artikel

Überblick

Dieses Vorschaupaket für Python enthält ADLS Gen2-spezifische API-Unterstützung, die im Storage SDK verfügbar ist. Dies umfasst u. a.:

  1. Neue Vorgänge auf Verzeichnisebene (Erstellen, Umbenennen, Löschen) für das Speicherkonto mit aktiviertem hierarchischem Namespace (HNS). Für HNS-fähige Konten sind die Umbenennungs-/Verschiebungsvorgänge atomar.
  2. Berechtigungsbezogene Vorgänge (Abrufen/Festlegen von ACLs) für konten mit aktiviertem hierarchischem Namespace (HNS).

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

Erste Schritte

Voraussetzungen

Installieren des Pakets

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

pip install azure-storage-file-datalake --pre

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

# Install the extension 'Storage-Preview'
az extension add --name storage-preview

# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

Authentifizieren des Clients

Die Interaktion mit DataLake Storage beginnt mit einer instance der DataLakeServiceClient-Klasse. Sie benötigen ein vorhandenes Speicherkonto, dessen URL und Anmeldeinformationen, um das Clientobjekt zu instanziieren.

Abrufen von Anmeldeinformationen

Für die Authentifizierung des Clients stehen ihnen mehrere Optionen zur Auswahl:

  1. Verwenden einer SAS-Tokenzeichenfolge
  2. Verwenden eines Freigegebenen Zugriffsschlüssels für ein Konto
  3. Verwenden von Tokenanmeldeinformationen aus azure.identity

Alternativ können Sie sich mit der -Methode mit from_connection_string einem Speicher Verbindungszeichenfolge authentifizieren. Siehe Beispiel: Clienterstellung mit einem Verbindungszeichenfolge.

Sie können die Anmeldeinformationen weglassen, wenn Ihre Konto-URL bereits über ein SAS-Token verfügt.

Erstellen des Clients

Sobald Sie Ihre Konto-URL und Ihre Anmeldeinformationen bereit haben, können Sie den DataLakeServiceClient erstellen:

from azure.storage.filedatalake import DataLakeServiceClient

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

Wichtige Begriffe

DataLake-Speicher bietet vier Arten von Ressourcen:

  • Das Speicherkonto
  • Ein Dateisystem im Speicherkonto
  • Ein Verzeichnis unter dem Dateisystem
  • Eine Datei im Dateisystem oder im Verzeichnis

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

Das DataLake Storage SDK stellt vier verschiedene Clients für die Interaktion mit dem DataLake-Dienst bereit:

  1. DataLakeServiceClient : Dieser Client interagiert mit dem DataLake-Dienst auf Kontoebene. Sie bietet Vorgänge zum Abrufen und Konfigurieren der Kontoeigenschaften sowie zum Auflisten, Erstellen und Löschen von Dateisystemen innerhalb des Kontos. Bei Vorgängen in Bezug auf ein bestimmtes Dateisystem, ein bestimmtes Verzeichnis oder eine Datei können Clients für diese Entitäten auch mithilfe der get_file_client- get_directory_client oder get_file_system_client -Funktionen abgerufen werden.
  2. FileSystemClient : Dieser Client stellt die Interaktion mit einem bestimmten Dateisystem dar, auch wenn dieses Dateisystem noch nicht vorhanden ist. Es stellt Vorgänge zum Erstellen, Löschen oder Konfigurieren von Dateisystemen bereit und umfasst Vorgänge zum Auflisten von Pfaden unter dem Dateisystem, zum Hochladen und Löschen von Dateien oder Verzeichnissen im Dateisystem. Bei Vorgängen, die sich auf eine bestimmte Datei beziehen, kann der Client auch mithilfe der get_file_client -Funktion abgerufen werden. Bei Vorgängen, die sich auf ein bestimmtes Verzeichnis beziehen, kann der Client mithilfe der get_directory_client -Funktion abgerufen werden.
  3. DataLakeDirectoryClient : Dieser Client stellt die Interaktion mit einem bestimmten Verzeichnis dar, auch wenn dieses Verzeichnis noch nicht vorhanden ist. Es bietet Verzeichnisvorgänge zum Erstellen, Löschen, Umbenennen, Abrufen von Eigenschaften und Festlegen von Eigenschaftenvorgängen.
  4. DataLakeFileClient : Dieser Client stellt die Interaktion mit einer bestimmten Datei dar, auch wenn diese Datei noch nicht vorhanden ist. Es bietet Dateivorgänge zum Anfügen von Daten, Leeren von Daten, Löschen, Erstellen und Lesen von Dateien.
  5. DataLakeLeaseClient : Dieser Client stellt Leaseinteraktionen mit einem FileSystemClient, DataLakeDirectoryClient oder DataLakeFileClient dar. Es bietet Vorgänge zum Abrufen, Erneuern, Freigeben, Ändern und Unterbrechen von Leases für die Ressourcen.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Storage DataLake-Aufgaben behandeln, einschließlich:

Clienterstellung mit einem Verbindungszeichenfolge

Erstellen Sie den DataLakeServiceClient mithilfe der Verbindungszeichenfolge zu Ihrem Azure Storage-Konto.

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")

Hochladen einer Datei

Laden Sie eine Datei in Ihr Dateisystem hoch.

from azure.storage.filedatalake import DataLakeFileClient

data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))

Herunterladen einer Datei

Laden Sie eine Datei aus Ihrem Dateisystem herunter.

from azure.storage.filedatalake import DataLakeFileClient

file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")

with open("./BlockDestination.txt", "wb") as my_file:
    download = file.download_file()
    download.readinto(my_file)

Auflisten von Pfaden

Listen Sie die Pfade in Ihrem Dateisystem auf.

from azure.storage.filedatalake import FileSystemClient

file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")

paths = file_system.get_paths()
for path in paths:
    print(path.name + '\n')

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-Operation-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. Der Standardwert ist 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

DataLake Storage-Clients 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.filedatalake import DataLakeServiceClient

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

Nächste Schritte

Weiterer Beispielcode

Erste Schritte mit unseren Azure DataLake-Beispielen.

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

  • datalake_samples_access_control.py - Beispiele für gängige DataLake Storage-Aufgaben:

    • Einrichten eines Dateisystems
    • Erstellen eines Verzeichnisses
    • Festlegen/Abrufen der Zugriffssteuerung für das Verzeichnis
    • Erstellen von Dateien unter dem Verzeichnis
    • Festlegen/Abrufen der Zugriffssteuerung für jede Datei
    • Löschen eines Dateisystems

  • datalake_samples_upload_download.py - Beispiele für gängige DataLake Storage-Aufgaben:

    • Einrichten eines Dateisystems
    • Datei erstellen
    • Anfügen von Daten an die Datei
    • Löschen von Daten in die Datei
    • Herunterladen der hochgeladenen Daten
    • Löschen eines Dateisystems

Zusätzliche Dokumentation

Tabelle für ADLS Gen1- zu ADLS Gen2-API-Zuordnung Ausführlichere REST-Dokumentation zu Data Lake Storage Gen2 finden Sie in der Data Lake Storage Gen2-Dokumentation zu 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.