Verwenden von Python zum Verwalten von Zugriffssteuerungslisten in Azure Data Lake Storage Gen2

In diesem Artikel erfahren Sie, wie Sie mithilfe von Python die Zugriffssteuerungslisten von Verzeichnissen und Dateien abrufen, festlegen und aktualisieren.

Die Vererbung von Zugriffssteuerungslisten (ACLs) ist für neue untergeordnete Elemente, die unter einem übergeordneten Verzeichnis erstellt werden, bereits verfügbar. Sie können Zugriffssteuerungslisten aber auch rekursiv für die vorhandenen untergeordneten Elemente eines übergeordneten Verzeichnisses hinzufügen, aktualisieren und entfernen, ohne diese Änderungen für jedes untergeordnete Element einzeln vornehmen zu müssen.

Paket (Python-Paketindex) | Beispiel | Rekursive ACL-Beispiele | API-Referenz | Zuordnung von Gen1 zu Gen2 | Feedback geben

Voraussetzungen

• Ein Azure-Abonnement. Weitere Informationen finden Sie unter Kostenlose Azure-Testversion.

• Ein Speicherkonto, für das der hierarchische Namespace aktiviert ist. Befolgen Sie diese Anleitung für die Erstellung.

• Azure CLI, Version 2.6.0 oder höher.

• Eine der folgenden Sicherheitsberechtigungen:

  • Ein bereitgestellter Sicherheitsprinzipal für Microsoft Entra ID, dem die Rolle Storage Blob-Datenbesitzer im Bereich des Zielcontainers, der übergeordneten Ressourcengruppe oder des Abonnements zugewiesen wurde.

  • Der Benutzer muss Besitzer des Zielcontainers oder -verzeichnisses sein, in dem Sie die ACL-Einstellungen anwenden möchten. Beim rekursiven Festlegen von ACLs schließt dies alle untergeordneten Elemente im Zielcontainer oder -verzeichnis ein.

  • Speicherkontoschlüssel

Einrichten des Projekts

Installieren Sie die Azure Data Lake Storage-Clientbibliothek für Python mithilfe von pip.

pip install azure-storage-file-datalake

Fügen Sie diese Importanweisungen am Anfang Ihrer Codedatei hinzu.

from azure.storage.filedatalake import DataLakeServiceClient
from azure.identity import DefaultAzureCredential

Herstellen einer Verbindung mit dem Konto

Wenn Sie die Codeausschnitte in diesem Artikel verwenden möchten, müssen Sie eine DataLakeServiceClient-Instanz erstellen, die das Speicherkonto darstellt.

Herstellen einer Verbindung mithilfe von Microsoft Entra ID

Hinweis

Wenn Sie Microsoft Entra ID verwenden, um den Zugriff zu autorisieren, sollten Sie sicherstellen, dass Ihrem Sicherheitsprinzipal die Rolle Besitzer von Speicherblobdaten zugewiesen wurde. Weitere Informationen dazu, wie ACL-Berechtigungen angewendet werden und wie sich Änderungen daran auswirken, finden Sie unter Zugriffssteuerungsmodell in Azure Data Lake Storage Gen2.

Sie können die Azure-Identitätsclientbibliothek für Python verwenden, um Ihre Anwendung bei Microsoft Entra ID zu authentifizieren.

Im Rahmen dieses Prozesses müssen Sie dem Sicherheitsprinzipal eine der folgenden Azure RBAC-Rollen (Azure Role-Based Access Control) zuweisen:

Role	ACL-Einstellungsfunktion
Besitzer von Speicherblobdaten	Alle Verzeichnisse und Dateien im Konto
Mitwirkender an Speicherblobdaten	Nur Verzeichnisse und Dateien im Besitz des Sicherheitsprinzipals

Erstellen Sie als Nächstes eine DataLakeServiceClient-Instanz und übergeben Sie eine neue Instanz der DefaultAzureCredential-Klasse.

def get_service_client_token_credential(self, account_name) -> DataLakeServiceClient:
    account_url = f"https://{account_name}.dfs.core.windows.net"
    token_credential = DefaultAzureCredential()

    service_client = DataLakeServiceClient(account_url, credential=token_credential)

    return service_client

Weitere Informationen zur Verwendung von DefaultAzureCredential zum Autorisieren des Datenzugriffs finden Sie unter Übersicht: Authentifizieren von Python-Apps bei Azure mithilfe des Azure SDK.

Herstellen einer Verbindung per Kontoschlüssel

Sie können den Zugriff auf Daten mithilfe Ihrer Kontozugriffsschlüssel (Gemeinsam verwendeter Schlüssel) autorisieren. In diesem Beispiel wird eine DataLakeServiceClient-Instanz erstellt, die mit dem Kontoschlüssel autorisiert ist.

def get_service_client_account_key(self, account_name, account_key) -> DataLakeServiceClient:
    account_url = f"https://{account_name}.dfs.core.windows.net"
    service_client = DataLakeServiceClient(account_url, credential=account_key)

    return service_client

Achtung

Eine Autorisierung mit einem gemeinsam verwendeten Schlüssel wird nicht empfohlen, da sie möglicherweise weniger sicher ist. Um optimale Sicherheit zu gewährleisten, deaktivieren Sie die Autorisierung über gemeinsam genutzten Schlüssel für Ihr Speicherkonto. Eine Anleitung finden Sie unter Verhindern der Autorisierung mit gemeinsam verwendeten Schlüsseln für ein Azure Storage-Konto.

Sie sollten die Verwendung von Zugriffsschlüsseln und Verbindungszeichenfolgen auf vorläufige Proof-of-Concept-Anwendungen oder Entwicklungsprototypen beschränken, die keinen Zugriff auf Produktionsdaten oder vertrauliche Daten haben. In allen anderen Fällen sollten Sie immer die tokenbasierten Authentifizierungsklassen, die im Azure SDK verfügbar sind, für die Authentifizierung bei Azure-Ressourcen verwenden.

Microsoft empfiehlt, dass Clients entweder Microsoft Entra ID oder eine SAS (Shared Access Signature) verwenden, um den Zugriff auf Daten in Azure Storage zu autorisieren. Weitere Informationen finden Sie unter Autorisieren von Vorgängen für den Datenzugriff.

Festlegen von ACLs

Wenn Sie eine neue Zugriffssteuerungsliste (ACL) festlegen, ersetzen Sie die gesamte bestehende Zugriffssteuerungsliste einschließlich aller Einträge. Wenn Sie die Berechtigungsebene eines Sicherheitsprinzipals ändern oder der Zugriffssteuerungsliste einen neuen Sicherheitsprinzipal hinzufügen möchten, ohne dass sich dies auf bereits vorhandene Einträge auswirkt, sollten Sie die Zugriffssteuerungsliste stattdessen aktualisieren. Informationen dazu, wie eine Zugriffssteuerungsliste aktualisiert statt ersetzt wird, finden Sie im Abschnitt Aktualisieren von ACLs in diesem Artikel.

In diesem Abschnitt erfahren Sie Folgendes:

• Festlegen der ACL eines Verzeichnisses
• Festlegen der ACL einer Datei

Festlegen der ACL eines Verzeichnisses

Rufen Sie die Zugriffssteuerungsliste (Access Control List, ACL) eines Verzeichnisses ab, indem Sie die Methode DataLakeDirectoryClient.get_access_control aufrufen und die ACL durch Aufrufen der Methode DataLakeDirectoryClient.set_access_control festlegen.

In diesem Beispiel wird die ACL des Verzeichnisses my-directory abgerufen und dann festgelegt. Mit der Zeichenfolge rwxr-xrw- werden dem zuständigen Benutzer Lese-, Schreib- und Ausführungsberechtigungen und der zuständigen Gruppe nur Lese- und Ausführungsberechtigungen gewährt, während allen anderen lediglich Lese- und Schreibzugriff gewährt wird.

def manage_directory_permissions():
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-file-system")

        directory_client = file_system_client.get_directory_client("my-directory")
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])
        
        new_dir_permissions = "rwxr-xrw-"
        
        directory_client.set_access_control(permissions=new_dir_permissions)
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])
    
    except Exception as e:
     print(e)

Sie können auch die ACL des Stammverzeichnisses eines Containers abrufen und festlegen. Um das Stammverzeichnis abzurufen, rufen Sie die FileSystemClient._get_root_directory_client-Methode auf.

Festlegen der ACL einer Datei

Rufen Sie die Zugriffssteuerungsliste (Access Control List, ACL) einer Datei ab, indem Sie die Methode DataLakeFileClient.get_access_control aufrufen und die ACL durch Aufrufen der Methode DataLakeFileClient.set_access_control festlegen.

Im folgenden Beispiel wird die ACL der Datei my-file.txt abgerufen und dann festgelegt. Mit der Zeichenfolge rwxr-xrw- werden dem zuständigen Benutzer Lese-, Schreib- und Ausführungsberechtigungen und der zuständigen Gruppe nur Lese- und Ausführungsberechtigungen gewährt, während allen anderen lediglich Lese- und Schreibzugriff gewährt wird.

def manage_file_permissions():
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-file-system")

        directory_client = file_system_client.get_directory_client("my-directory")
        
        file_client = directory_client.get_file_client("uploaded-file.txt")

        acl_props = file_client.get_access_control()
        
        print(acl_props['permissions'])
        
        new_file_permissions = "rwxr-xrw-"
        
        file_client.set_access_control(permissions=new_file_permissions)
        
        acl_props = file_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

Rekursives Festlegen von ACLs

Wenn Sie eine neue Zugriffssteuerungsliste (ACL) festlegen, ersetzen Sie die gesamte bestehende Zugriffssteuerungsliste einschließlich aller Einträge. Wenn Sie die Berechtigungsebene eines Sicherheitsprinzipals ändern oder der Zugriffssteuerungsliste einen neuen Sicherheitsprinzipal hinzufügen möchten, ohne dass sich dies auf bereits vorhandene Einträge auswirkt, sollten Sie die Zugriffssteuerungsliste stattdessen aktualisieren. Informationen dazu, wie eine Zugriffssteuerungsliste aktualisiert wird, anstatt sie zu ersetzen, finden Sie im Abschnitt Rekursives Aktualisieren von Zugriffssteuerungslisten in diesem Artikel.

Sie legen Zugriffssteuerungslisten rekursiv fest, indem Sie die DataLakeDirectoryClient.set_access_control_recursive-Methode aufrufen.

Wenn Sie einen standardmäßigen ACL-Eintrag festlegen möchten, fügen Sie die Zeichenfolge default: an den Anfang jeder ACL-Eintragszeichenfolge an.

In diesem Beispiel wird die ACL des Verzeichnisses my-parent-directory festgelegt.

Diese Methode akzeptiert einen booleschen Parameter namens is_default_scope, der angibt, ob die Standard-ACL festgelegt werden soll. Wenn dieser Parameter True ist, wird der Liste der ACL-Einträge die Zeichenfolge default: vorangestellt. Die Einträge in diesem Beispiel gewähren die folgenden Berechtigungen: Lese-, Schreib- und Ausführungsberechtigungen für den besitzenden Benutzer, Lese- und Ausführungsberechtigungen für die besitzende Gruppe und Leseberechtigungen für alle anderen. Der letzte ACL-Eintrag in diesem Beispiel gewährt einem bestimmten Benutzer mit der Objekt-ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Lese- und Ausführungsberechtigungen.

def set_permission_recursively(is_default_scope):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")

        acl = 'user::rwx,group::r-x,other::r--,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'   

        if is_default_scope:
           acl = 'default:user::rwx,default:group::r-x,default:other::r--,default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        directory_client.set_access_control_recursive(acl=acl)
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

Ein Beispiel, das Zugriffssteuerungslisten durch Angabe einer Batchgröße rekursiv in Batches verarbeitet, finden Sie im Python-Beispiel.

Rekursives Aktualisieren von Zugriffssteuerungslisten

Wenn Sie eine Zugriffssteuerungsliste aktualisieren, ändern Sie die Zugriffssteuerungsliste, anstatt sie zu ersetzen. Beispielsweise können Sie der Zugriffssteuerungsliste einen neuen Sicherheitsprinzipal hinzufügen, ohne dass sich dies auf andere Sicherheitsprinzipale auswirkt, die in der Zugriffssteuerungsliste aufgelistet sind. Informationen dazu, wie eine Zugriffssteuerungsliste ersetzt statt aktualisiert wird, finden Sie im Abschnitt Festlegen von Zugriffssteuerungslisten in diesem Artikel.

Um eine Zugriffssteuerungsliste rekursiv zu aktualisieren, erstellen Sie ein neues ACL-Objekt mit dem ACL-Eintrag, den Sie aktualisieren möchten, und verwenden Sie dieses Objekt dann im Aktualisierungsvorgang der Zugriffssteuerungsliste. Rufen Sie nicht die vorhandene Zugriffssteuerungsliste ab, stellen Sie lediglich die zu aktualisierenden Zugriffssteuerungslisteneinträge bereit. Sie aktualisieren eine Zugriffssteuerungsliste rekursiv, indem Sie die DataLakeDirectoryClient.update_access_control_recursive-Methode aufrufen. Wenn Sie einen standardmäßigen ACL-Eintrag aktualisieren möchten, fügen Sie die Zeichenfolge default: an den Anfang jeder ACL-Eintragszeichenfolge an.

Dieses Beispiel aktualisiert einen ACL-Eintrag mit Schreibberechtigung.

In diesem Beispiel wird die ACL des Verzeichnisses my-parent-directory festgelegt. Diese Methode akzeptiert einen booleschen Parameter namens is_default_scope, der angibt, ob die Standard-ACL aktualisiert werden soll. Wenn dieser Parameter True ist, wird dem aktualisierten ACL-Eintrag die Zeichenfolge default: vorangestellt.

def update_permission_recursively(is_default_scope):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx'   

        if is_default_scope:
           acl = 'default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx'

        directory_client.update_access_control_recursive(acl=acl)

        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

Ein Beispiel, das Zugriffssteuerungslisten durch Angabe einer Batchgröße rekursiv in Batches verarbeitet, finden Sie im Python-Beispiel.

Rekursives Entfernen von ACL-Einträgen

Sie können einen oder mehrere ACL-Einträge entfernen. Um ACL-Einträge rekursiv zu entfernen, erstellen Sie ein neues ACL-Objekt für den zu entfernenden ACL-Eintrag, und verwenden Sie dieses Objekt dann im Entfernungsvorgang der ACL. Rufen Sie nicht die vorhandene ACL ab, stellen Sie lediglich die zu entfernenden ACL-Einträge bereit.

Sie entfernen ACL-Einträge, indem Sie die DataLakeDirectoryClient.remove_access_control_recursive-Methode aufrufen. Wenn Sie einen standardmäßigen ACL-Eintrag entfernen möchten, fügen Sie die Zeichenfolge default: an den Anfang der ACL-Eintragszeichenfolge an.

In diesem Beispiel wird ein ACL-Eintrag aus der Zugriffssteuerungsliste des Verzeichnisses my-parent-directory entfernt. Diese Methode akzeptiert einen booleschen Parameter namens is_default_scope, der angibt, ob der Eintrag aus der Standard-ACL entfernt werden soll. Wenn dieser Parameter True ist, wird dem aktualisierten ACL-Eintrag die Zeichenfolge default: vorangestellt.

def remove_permission_recursively(is_default_scope):

    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")

        acl = 'user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

        if is_default_scope:
           acl = 'default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

        directory_client.remove_access_control_recursive(acl=acl)

    except Exception as e:
     print(e)

Ein Beispiel, das Zugriffssteuerungslisten durch Angabe einer Batchgröße rekursiv in Batches verarbeitet, finden Sie im Python-Beispiel.

Wiederherstellen nach Fehlern

Es können Laufzeit- oder Berechtigungsfehler auftreten. Starten Sie den Prozess bei Laufzeitfehlern vom Anfang neu. Berechtigungsfehler können auftreten, wenn der Sicherheitsprinzipal nicht über ausreichende Berechtigungen verfügt, um die Zugriffssteuerungsliste eines Verzeichnisses oder einer Datei zu ändern, die sich in der geänderten Verzeichnishierarchie befindet. Beheben Sie das Berechtigungsproblem, und setzen Sie dann den Prozess ab dem Zeitpunkt des Fehlers mithilfe eines Fortsetzungstokens fort, oder starten Sie den Prozess vom Anfang neu. Sie müssen das Fortsetzungstoken nicht verwenden, wenn Sie vom Anfang neu starten. Sie können ACL-Einträge ohne negative Auswirkung erneut anwenden.

In diesem Beispiel wird im Fall eines Fehlers ein Fortsetzungstoken zurückgegeben. Die Anwendung kann diese Beispielmethode erneut aufrufen, nachdem der Fehler behoben wurde, und das Fortsetzungstoken übergeben. Wenn diese Beispielmethode zum ersten Mal aufgerufen wird, kann die Anwendung den Wert None für den Fortsetzungstokenparameter übergeben.

def resume_set_acl_recursive(continuation_token):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user::rwx,group::rwx,other::rwx,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        acl_change_result = directory_client.set_access_control_recursive(acl=acl, continuation=continuation_token)

        continuation_token = acl_change_result.continuation

        return continuation_token
        
    except Exception as e:
     print(e) 
     return continuation_token

Ein Beispiel, das Zugriffssteuerungslisten durch Angabe einer Batchgröße rekursiv in Batches verarbeitet, finden Sie im Python-Beispiel.

Wenn Sie möchten, dass der Prozess ohne Unterbrechung durch Berechtigungsfehler durchgeführt wird, können Sie dies angeben.

Um sicherzustellen, dass der Prozess ohne Unterbrechung durchgeführt wird, übergeben Sie kein Fortsetzungstoken an die DataLakeDirectoryClient.set_access_control_recursive-Methode.

In diesem Beispiel werden ACL-Einträge rekursiv festgelegt. Wenn dieser Code auf einen Berechtigungsfehler stößt, wird dieser Fehler aufgezeichnet und die Ausführung fortgesetzt. In diesem Beispiel wird die Anzahl der Fehler an die Konsole ausgegeben.

def continue_on_failure():
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user::rwx,group::rwx,other::rwx,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        acl_change_result = directory_client.set_access_control_recursive(acl=acl)

        print("Summary: {} directories and {} files were updated successfully, {} failures were counted."
          .format(acl_change_result.counters.directories_successful, acl_change_result.counters.files_successful,
                  acl_change_result.counters.failure_count))
        
    except Exception as e:
     print(e)

Ein Beispiel, das Zugriffssteuerungslisten durch Angabe einer Batchgröße rekursiv in Batches verarbeitet, finden Sie im Python-Beispiel.

Bewährte Methoden

Dieser Abschnitt enthält einige Richtlinien zu bewährten Methoden für das rekursive Festlegen von Zugriffssteuerungslisten.

Behandeln von Laufzeitfehlern

Ein Laufzeitfehler kann aus vielen Gründen auftreten (z. B. bei einem Ausfall oder einem Clientkonnektivitätsproblem). Wenn ein Laufzeitfehler auftritt, starten Sie den rekursiven ACL-Prozess neu. Zugriffssteuerungslisten können ohne negative Auswirkungen erneut auf Elemente angewandt werden.

Behandeln von Berechtigungsfehlern (403)

Wenn beim Ausführen eines rekursiven ACL-Prozesses eine Zugriffssteuerungsausnahme auftritt, verfügt Ihr AD-Sicherheitsprinzipal möglicherweise nicht über ausreichende Berechtigungen zum Anwenden einer Zugriffssteuerungsliste auf eines der untergeordneten Elemente in der Verzeichnishierarchie. Wenn ein Berechtigungsfehler auftritt, wird der Prozess angehalten, und es wird ein Fortsetzungstoken bereitgestellt. Beheben Sie das Berechtigungsproblem, und verwenden Sie dann das Fortsetzungstoken, um das restliche Dataset zu verarbeiten. Die Verzeichnisse und Dateien, die bereits erfolgreich verarbeitet wurden, müssen nicht erneut verarbeitet werden. Sie können den rekursiven ACL-Prozess auch neu starten. Zugriffssteuerungslisten können ohne negative Auswirkungen erneut auf Elemente angewandt werden.

Anmeldeinformationen

Es wird empfohlen, einen Microsoft Entra-Sicherheitsprinzipal bereitzustellen, dem die Rolle Besitzer von Speicherblobdaten im Bereich des Zielspeicherkontos oder -containers zugewiesen wurde.

Leistung

Um die Latenz zu verringern, empfiehlt es sich, den rekursiven ACL-Prozess auf einem virtuellen Azure-Computer (VM) auszuführen, der sich in derselben Region wie das Speicherkonto befindet.

Einschränkungen bei Zugriffssteuerungslisten

Die maximale Anzahl von Zugriffssteuerungslisten, die Sie auf ein Verzeichnis oder eine Datei anwenden können, beträgt 32 ACLs für den Zugriff und 32 Standard-ACLs. Weitere Informationen finden Sie unter Zugriffssteuerung in Azure Data Lake Storage Gen2.

Weitere Informationen

• API-Referenzdokumentation
• Paket (Python-Paketindex)
• Beispiele
• Zuordnung von Gen1 zu Gen2
• Bekannte Probleme
• Feedback geben
• Zugriffssteuerungsmodell in Azure Data Lake Storage Gen2
• Zugriffssteuerungslisten (ACLs) in Azure Data Lake Storage Gen2