Verwenden von PowerShell zum Verwalten von Zugriffssteuerungslisten in Azure Data Lake Storage

Dieser Artikel zeigt Ihnen, wie Sie PowerShell nutzen, um die Zugriffskontrolllisten (ACLs) von Verzeichnissen und Dateien zu erhalten, zu setzen und zu aktualisieren.

Neue untergeordnete Elemente, die Sie unter einem übergeordneten Verzeichnis erstellen, erben automatisch Zugriffssteuerungslisten. Sie können jedoch auch ACLs rekursiv für vorhandene Kindelemente eines Elternverzeichnisses hinzufügen, aktualisieren und entfernen, ohne diese Änderungen für jedes Kindelement einzeln vornehmen zu müssen.

Referenz | Feedback senden

Voraussetzungen

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

• Ein Speicherkonto, bei dem der hierarchische Namespace (HNS) aktiviert ist. Befolgen Sie diese Anleitung für die Erstellung.

• Eine der folgenden Sicherheitsberechtigungen:

  • Ein bereitgestellter Microsoft Entra ID-Sicherheitsprinzipal, dem die Rolle Besitzer von Speicherblobdaten zugewiesen ist, die auf den Zielcontainer, das Speicherkonto, die übergeordnete Ressourcengruppe oder das Abonnement beschränkt ist.

  • Der Benutzer muss Besitzer des Zielcontainers oder -verzeichnisses sein, in dem Sie die ACL-Einstellungen anwenden möchten. Um Zugriffssteuerungslisten rekursiv festzulegen, schließt dieser Benutzer alle untergeordneten Elemente im Zielcontainer oder -verzeichnis ein.

Installieren des PowerShell-Moduls

1. Überprüfen Sie mit dem folgenden Befehl, ob die von Ihnen installierte PowerShell-Version 5.1 oder höher ist.

   echo $PSVersionTable.PSVersion.ToString()
   

   Um Ihre PowerShell-Version zu aktualisieren, siehe Bestehende Windows PowerShell aktualisieren.

2. Installieren Sie das Modul Az.Storage.

   Install-Module Az.Storage -Repository PSGallery -Force  
   

   Für weitere Informationen zur Installation von PowerShell-Modulen siehe Install the Azure PowerShell module.

Herstellen einer Verbindung mit dem Konto

1. Öffnen Sie ein Windows PowerShell-Befehlsfenster, melden Sie sich dann mit dem Befehl Connect-AzAccount bei Ihrem Azure-Abonnement an, und befolgen Sie die Anweisungen auf dem Bildschirm.

   Connect-AzAccount
   

2. Wenn deine Identität mit mehr als einem Abonnement verknüpft ist und du nicht aufgefordert wirst, das Abonnement auszuwählen, setze dein aktives Abonnement auf das Abonnement des Speicherkontos, das du verwenden möchtest. In diesem Beispiel ersetzen Sie den Platzhalterwert <subscription-id> durch die ID Ihres Abonnements.

   Select-AzSubscription -SubscriptionId <subscription-id>
   

3. Rufen Sie den Speicherkontokontext ab.

   $ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -UseConnectedAccount
   

ACLs abrufen

Rufen Sie die Zugriffssteuerungsliste eines Verzeichnisses oder einer Datei mithilfe des Cmdlets Get-AzDataLakeGen2Item ab.

In Azure Data Lake Storage wird ein Container auch als Dateisystem bezeichnet. Der -FileSystem in den folgenden Beispielen verwendete Parameter nimmt den Namen Ihres Containers an.

Das folgende Beispiel ruft die ACL des Stammverzeichnisses eines container ab und gibt sie dann in der Konsole aus.

$filesystemName = "my-file-system"
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

Das folgende Beispiel erhält die ACL eines Verzeichnisses und druckt dann die ACL auf die Konsole.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

Das folgende Beispiel erhält das ACL einer Datei und druckt das ACL dann auf die Konsole.

$filePath = "my-directory/upload.txt"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

Die folgende Abbildung zeigt die Ausgabe nach dem Abrufen der Zugriffssteuerungsliste eines Verzeichnisses.

In diesem Beispiel verfügt der zuständige Benutzer über Berechtigungen zum Lesen, Schreiben und Ausführen. Die Eigentümergruppe verfügt nur über Lese- und Ausführungsberechtigungen. Weitere Informationen zu Zugriffssteuerungslisten finden Sie unter Zugriffssteuerung in Azure Data Lake Storage.

Festlegen von ACLs

Wenn du ein ACL setzt , ersetzt du das gesamte ACL einschließlich aller Einträge. Wenn Sie die Berechtigungsstufe eines Sicherheitsprinzipals ändern oder einen neuen Sicherheitsprinzip zur ACL hinzufügen möchten, ohne andere bestehende Einträge zu beeinflussen, aktualisieren Sie stattdessen die ACL. Informationen zum Aktualisieren einer ACL, anstatt sie zu ersetzen, finden Sie im Abschnitt Aktualisieren von ACLs in diesem Artikel.

Wenn Sie die ACL festlegen, müssen Sie einen Eintrag für den Eigentümerbenutzer, einen Eintrag für die Eigentümergruppe und einen Eintrag für alle anderen Benutzer hinzufügen. Weitere Informationen zum zuständigen Benutzer, zur zuständigen Gruppe und zu allen anderen Benutzern finden Sie unter Benutzer und Identitäten.

In diesem Abschnitt erfahren Sie Folgendes:

• Eine ACL festlegen
• Rekursives Festlegen von ACLs

Eine ACL festlegen

Verwenden Sie das Cmdlet Set-AzDataLakeGen2ItemAclObject, um eine ACL für den Besitzer, die Besitzergruppe oder andere Benutzer zu erstellen. Verwenden Sie dann das Cmdlet Update-AzDataLakeGen2Item, um die Zugriffssteuerungsliste zu übernehmen.

In diesem Beispiel wird die Zugriffssteuerungsliste für das Stammverzeichnis eines Containers für den zuständigen Benutzer, die zuständige Gruppe oder andere Benutzer festgelegt und dann an der Konsole ausgegeben.

$filesystemName = "my-file-system"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Acl $acl
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

In diesem Beispiel wird die Zugriffssteuerungsliste auf ein Verzeichnis für den zuständigen Benutzer, die zuständige Gruppe oder andere Benutzer festgelegt und dann auf der Konsole ausgegeben.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

In diesem Beispiel wird die Zugriffssteuerungsliste auf eine Datei für den zuständigen Benutzer, die zuständige Gruppe oder andere Benutzer festgelegt und anschließend auf der Konsole ausgegeben.

$filesystemName = "my-file-system"
$filePath = "my-directory/upload.txt"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "-wx" -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath -Acl $acl
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

Die folgende Abbildung zeigt die Ausgabe, nachdem die ACL einer Datei festgelegt wurde.

In diesem Beispiel verfügen der zuständige Benutzer und die zuständige Gruppe nur über Berechtigungen zum Lesen und Schreiben. Alle anderen Benutzer verfügen über Berechtigungen zum Schreiben und Ausführen. Weitere Informationen zu Zugriffssteuerungslisten finden Sie unter Zugriffssteuerung in Azure Data Lake Storage.

Rekursives Festlegen von ACLs

Zum rekursiven Festlegen von Zugriffssteuerungslisten verwenden Sie das Cmdlet Set-AzDataLakeGen2AclRecursive.

In diesem Beispiel wird die ACL des Verzeichnisses my-parent-directory festgelegt. Diese Einträge gewähren dem besitzenden Benutzer Lese-, Schreib- und Ausführungsberechtigungen, geben der besitzenden Gruppe nur Lese- und Ausführungsrechte und allen anderen keinen Zugriff. 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.

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission r-x -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "---" -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission r-x -InputObject $acl

Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Ein Beispiel dafür, wie ACLs unter Angabe einer Batchgröße rekursiv stapelweise festgelegt werden, finden Sie im Referenzartikel zu Set-AzDataLakeGen2AclRecursive.

Aktualisieren von ACLs

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.

In diesem Abschnitt erfahren Sie Folgendes:

• Aktualisieren einer ACL
• ACLs rekursiv aktualisieren

Aktualisieren einer ACL

Rufen Sie zuerst die Zugriffssteuerungsliste ab. Verwenden Sie dann das Cmdlet Set-AzDataLakeGen2ItemAclObject, um einen ACL-Eintrag hinzuzufügen oder zu aktualisieren. Verwenden Sie das Cmdlet Update-AzDataLakeGen2Item, um die ACL zu übernehmen.

Dieses Beispiel erstellt oder aktualisiert die ACL für ein Verzeichnis für einen Benutzer.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = (Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname).ACL
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID aaaaaaaa-bbbb-cccc-1111-222222222222 -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

ACLs rekursiv aktualisieren

Sie aktualisieren Zugriffssteuerungslisten rekursiv mithilfe des Cmdlets Update-AzDataLakeGen2AclRecursive.

Dieses Beispiel aktualisiert einen ACL-Eintrag mit Schreibberechtigung.

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission rwx

Update-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Ein Beispiel dazu, wie ACLs durch Festlegen einer Batchgröße rekursiv stapelweise aktualisiert werden, finden Sie im Referenzartikel zu Update-AzDataLakeGen2AclRecursive.

Entfernen von ACL-Einträgen

In diesem Abschnitt erfahren Sie Folgendes:

• Entfernen eines ACL-Eintrags
• Rekursives Entfernen von ACL-Einträgen

Entfernen eines ACL-Eintrags

Dieses Beispiel entfernt einen Eintrag aus einer vorhandenen Zugriffssteuerungsliste. Es verwendet den $ctx Speicherkonto-Kontext sowie die $acl, $filesystemName, und $dirname Variablen, die in früheren Abschnitten dieses Artikels festgelegt wurden.

$id = "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Create the new ACL object.
[Collections.Generic.List[System.Object]]$aclnew =$acl

foreach ($a in $aclnew)
{
    if ($a.AccessControlType -eq "User" -and $a.DefaultScope -eq $false -and $a.EntityId -eq $id)
    {
        $aclnew.Remove($a);
        break;
    }
}
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $aclnew

Rekursives Entfernen von ACL-Einträgen

Sie können einen oder mehrere ACL-Einträge rekursiv entfernen. Um einen ACL-Eintrag zu entfernen, erstelle ein neues ACL-Objekt für den ACL-Eintrag, den du entfernen möchtest, und verwende dieses Objekt dann in der Operation "ACL entfernen". Rufen Sie nicht die vorhandene Zugriffssteuerungsliste ab, sondern geben Sie nur die zu entfernenden ACL-Einträge an.

Sie entfernen ACL-Einträge mithilfe des Cmdlets Remove-AzDataLakeGen2AclRecursive.

In diesem Beispiel wird ein ACL-Eintrag aus dem Stammverzeichnis des Containers entfernt.

$filesystemName = "my-container"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---"

Remove-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName  -Acl $acl

Ein Beispiel, das ACLs rekursiv batchweise entfernt, indem eine Batchgröße angegeben wird, finden Sie im Referenzartikel zu Remove-AzDataLakeGen2AclRecursive.

Wiederherstellen nach Fehlern

Beim rekursiven Ändern von Zugriffssteuerungslisten können Laufzeit- oder Berechtigungsfehler auftreten. Die Beispiele in diesem Abschnitt verwenden den $ctx Speicherkontokontext und die $filesystemName, $dirname, und $acl Variablen, die in früheren Abschnitten dieses Artikels festgelegt wurden, wieder.

Starten Sie den Prozess bei Laufzeitfehlern vom Anfang neu. Berechtigungsfehler können auftreten, wenn der Sicherheitsprinzipal nicht über ausreichende Berechtigungen verfügt, um die ACL eines Verzeichnisses oder einer Datei zu ändern, die sich in der Verzeichnishierarchie befindet, die Sie ändern. Adressieren Sie das Berechtigungsproblem und entscheiden Sie sich dann, ob Sie den Prozess vom Ausfallpunkt aus mit einem Fortsetzungstoken fortsetzen oder den Prozess von vorne neu starten. Sie müssen das Fortsetzungstoken nicht verwenden, wenn Sie vom Anfang neu starten. Sie können ACL-Einträge ohne negative Auswirkung erneut anwenden.

Dieses Beispiel liefert Ergebnisse an die Variable zurück und leitet dann fehlgeschlagene Einträge in eine formatierte Tabelle.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$result
$result.FailedEntries | ft

Basierend auf der Ausgabe der Tabelle können Sie alle Berechtigungsfehler beheben und die Ausführung dann mit dem Fortsetzungstoken fortsetzen.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinuationToken $result.ContinuationToken
$result

Ein Beispiel dafür, wie ACLs unter Angabe einer Batchgröße rekursiv stapelweise festgelegt werden, finden Sie im Referenzartikel zu Set-AzDataLakeGen2AclRecursive.

Wenn du möchtest, dass der Prozess ohne Unterbrechung durch Berechtigungsfehler abgeschlossen wird, kannst du das so konfigurieren.

Dieses Beispiel verwendet den Parameter ContinueOnFailure, sodass die Ausführung auch bei einem Berechtigungsfehler im Vorgang fortgesetzt wird.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinueOnFailure

echo "[Result Summary]"
echo "TotalDirectoriesSuccessfulCount: `t$($result.TotalDirectoriesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalFilesSuccessfulCount)"
echo "TotalFailureCount: `t`t`t`t`t$($result.TotalFailureCount)"
echo "FailedEntries:"$($result.FailedEntries | ft)

Ein Beispiel dafür, wie ACLs unter Angabe einer Batchgröße rekursiv stapelweise festgelegt werden, finden Sie im Referenzartikel zu Set-AzDataLakeGen2AclRecursive.

Bewährte Methoden

Dieser Abschnitt bietet Ihnen einige Richtlinien zu bewährten Verfahren für das rekursive Festlegen von ACLs.

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.

ACL-Beschränkungen

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.

Siehe auch

• Bekannte Probleme
• Storage PowerShell-Cmdlets
• Zugriffssteuerungsmodell in Azure Data Lake Storage
• Zugriffssteuerungslisten (Access Control Lists, ACLs) in Azure Data Lake Storage