PowerShell gebruiken om ACL's te beheren in Azure Data Lake Storage Gen2

  • Artikel

In dit artikel leest u hoe u PowerShell gebruikt om de toegangsbeheerlijsten van mappen en bestanden op te halen, in te stellen en bij te werken.

Overname van ACL is al beschikbaar voor nieuwe onderliggende items die zijn gemaakt onder een bovenliggende map. U kunt echter ook ACL's recursief toevoegen, bijwerken en verwijderen op de bestaande onderliggende items van een bovenliggende map zonder dat u deze wijzigingen afzonderlijk hoeft aan te brengen voor elk onderliggend item.

Naslaginformatie | geven

Vereisten

  • Een Azure-abonnement. Zie Gratis proefversie van Azure downloaden voor meer informatie.

  • Een opslagaccount waarvoor hiërarchische naamruimte (HNS) is ingeschakeld. Volg deze instructies om er een te maken.

  • Azure CLI-versie 2.6.0 of hoger.

  • Een van de volgende beveiligingsmachtigingen:

    • Een ingerichte Microsoft Entra ID-beveiligingsprincipaal waaraan de rol Eigenaar van opslagblobgegevensis toegewezen, die is gericht op de doelcontainer, het opslagaccount, de bovenliggende resourcegroep of het abonnement.

    • De gebruiker die eigenaar is van de doelcontainer of map waarop u ACL-instellingen wilt toepassen. Als u ACL's recursief wilt instellen, omvat dit alle onderliggende items in de doelcontainer of map.

    • Sleutel van opslagaccount.

De PowerShell-module installeren

  1. Controleer of de versie van PowerShell die is geïnstalleerd, is 5.1 of hoger met behulp van de volgende opdracht.

    echo $PSVersionTable.PSVersion.ToString()

    Zie Bestaande Windows PowerShell upgraden om uw versie van PowerShell bij te werken

  2. Installeer de Az.Storage-module .

    Install-Module Az.Storage -Repository PSGallery -Force

    Zie De Azure PowerShell-module installeren voor meer informatie over het installeren van PowerShell-modules

Verbinding maken naar het account

Kies hoe u wilt dat uw opdrachten autorisatie voor het opslagaccount verkrijgen.

Optie 1: Autorisatie verkrijgen met behulp van Microsoft Entra-id

Notitie

Als u de Microsoft Entra-id gebruikt om toegang te verlenen, moet u ervoor zorgen dat de rol van de eigenaar van de opslagblobgegevens is toegewezen aan uw beveiligingsprincipaal. Zie het Access Control-model in Azure Data Lake Storage Gen2 voor meer informatie over hoe ACL-machtigingen worden toegepast en wat de gevolgen zijn van het wijzigen ervan.

Met deze methode zorgt het systeem ervoor dat uw gebruikersaccount beschikt over de juiste Azure RBAC-toewijzingen (op rollen gebaseerd toegangsbeheer) en ACL-machtigingen.

  1. Open een Windows PowerShell-opdrachtvenster en meld u aan bij uw Azure-abonnement met de Connect-AzAccount opdracht en volg de aanwijzingen op het scherm.

    Connect-AzAccount

  2. Als uw identiteit is gekoppeld aan meer dan één abonnement, stelt u uw actieve abonnement in op het abonnement van het opslagaccount waarin u mappen wilt maken en beheren. Vervang in dit voorbeeld de waarde van de <subscription-id> tijdelijke aanduiding door de id van uw abonnement.

    Select-AzSubscription -SubscriptionId <subscription-id>

  3. Haal de context van het opslagaccount op.

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

Optie 2: autorisatie verkrijgen met behulp van de sleutel van het opslagaccount

Met deze methode controleert het systeem geen Azure RBAC- of ACL-machtigingen. Haal de context van het opslagaccount op met behulp van een accountsleutel.

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

ACL's ophalen

Haal de ACL van een map of bestand op met behulp van de Get-AzDataLakeGen2Itemcmdlet.

In dit voorbeeld wordt de ACL van de hoofdmap van een container opgehaald en wordt de ACL vervolgens naar de console afgedrukt.

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

In dit voorbeeld wordt de ACL van een map opgehaald en wordt de ACL vervolgens naar de console afgedrukt.

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

In dit voorbeeld wordt de ACL van een bestand opgehaald en wordt de ACL vervolgens naar de console afgedrukt.

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

In de volgende afbeelding ziet u de uitvoer nadat u de ACL van een map hebt opgehaald.

Get ACL output for directory

In dit voorbeeld heeft de gebruiker die eigenaar is, lees-, schrijf- en uitvoermachtigingen. De groep die eigenaar is, heeft alleen lees- en uitvoermachtigingen. Zie Toegangsbeheer in Azure Data Lake Storage Gen2 voor meer informatie over toegangsbeheerlijsten.

ACL's instellen

Wanneer u een ACL instelt, vervangt u de volledige ACL, inclusief alle vermeldingen. Als u het machtigingsniveau van een beveiligingsprincipaal wilt wijzigen of een nieuwe beveiligingsprincipaal wilt toevoegen aan de ACL zonder dat dit van invloed is op andere bestaande vermeldingen, moet u in plaats daarvan de ACL bijwerken . Als u een ACL wilt bijwerken in plaats van deze te vervangen, raadpleegt u de sectie ACL's bijwerken van dit artikel.

Als u ervoor kiest om de ACL in te stellen , moet u een vermelding toevoegen voor de gebruiker die eigenaar is, een vermelding voor de groep die eigenaar is en een vermelding voor alle andere gebruikers. Zie Gebruikers en identiteiten voor meer informatie over de gebruiker die eigenaar is, de groep die eigenaar is en alle andere gebruikers.

In deze sectie ziet u hoe u het volgende kunt doen:

  • Een ACL instellen
  • ACL's recursief instellen

Een ACL instellen

Gebruik de Set-AzDataLakeGen2ItemAclObject cmdlet om een ACL te maken voor de eigenaar van de gebruiker, de groep die eigenaar is of andere gebruikers. Gebruik vervolgens de Update-AzDataLakeGen2Item cmdlet om de ACL door te voeren.

In dit voorbeeld wordt de ACL ingesteld in de hoofdmap van een container voor de eigenaar van de gebruiker, de groep die eigenaar is of andere gebruikers, en drukt u de ACL vervolgens af op de console.

$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 dit voorbeeld wordt de ACL ingesteld op een map voor de eigenaar van de gebruiker, de groep die eigenaar is of andere gebruikers, en drukt de ACL vervolgens af op de console.

$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

Notitie

Als u een standaard-ACL-vermelding wilt instellen, gebruikt u de parameter -DefaultScope wanneer u de opdracht Set-AzDataLakeGen2ItemAclObject uitvoert. Voorbeeld: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope.

In dit voorbeeld wordt de ACL ingesteld op een bestand voor de eigenaar van de gebruiker, de groep die eigenaar is of andere gebruikers, en drukt de ACL vervolgens af op de console.

$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

Notitie

Gebruik de respectieve object-id's om de ACL van een specifieke groep of gebruiker, service-principal of beheerde identiteit in te stellen. Als u bijvoorbeeld de ACL van een groep wilt instellen, gebruikt u group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Als u de ACL van een gebruiker wilt instellen, gebruikt u user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

In de volgende afbeelding ziet u de uitvoer na het instellen van de ACL van een bestand.

Get ACL output for file

In dit voorbeeld heeft de groep die eigenaar is alleen lees- en schrijfmachtigingen. Alle andere gebruikers hebben schrijf- en uitvoermachtigingen. Zie Toegangsbeheer in Azure Data Lake Storage Gen2 voor meer informatie over toegangsbeheerlijsten.

ACL's recursief instellen

Stel ACL's recursief in met behulp van de cmdlet Set-AzDataLakeGen2AclRecursive .

In dit voorbeeld wordt de ACL van een map met de naam my-parent-directoryingesteld. Deze vermeldingen geven de gebruiker lees-, schrijf- en uitvoermachtigingen, geeft de groep die eigenaar is alleen lees- en uitvoermachtigingen en geeft alle anderen geen toegang. De laatste ACL-vermelding in dit voorbeeld geeft een specifieke gebruiker met de object-id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxxxx' lees- en uitvoermachtigingen.

$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

Notitie

Als u een standaard-ACL-vermelding wilt instellen, gebruikt u de parameter -DefaultScope wanneer u de opdracht Set-AzDataLakeGen2ItemAclObject uitvoert. Voorbeeld: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope.

Zie het artikel Set-AzDataLakeGen2AclRecursive reference voor een voorbeeld waarmee ACL's recursief in batches worden ingesteld door een batchgrootte op te geven.

ACL's bijwerken

Wanneer u een ACL bijwerkt , wijzigt u de ACL in plaats van de ACL te vervangen. U kunt bijvoorbeeld een nieuwe beveiligingsprincipaal toevoegen aan de ACL zonder dat dit van invloed is op andere beveiligingsprinciplen die worden vermeld in de ACL. Als u de ACL wilt vervangen in plaats van deze bij te werken, raadpleegt u de sectie ACL's instellen van dit artikel.

In deze sectie ziet u hoe u het volgende kunt doen:

  • Een ACL bijwerken
  • ACL's recursief bijwerken

Een ACL bijwerken

Haal eerst de ACL op. Gebruik vervolgens de Set-AzDataLakeGen2ItemAclObject cmdlet om een ACL-vermelding toe te voegen of bij te werken. Gebruik de Update-AzDataLakeGen2Item cmdlet om de ACL door te voeren.

In dit voorbeeld wordt de ACL voor een gebruiker gemaakt of bijgewerkt in een map .

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

Notitie

Als u een standaard-ACL-vermelding wilt bijwerken, gebruikt u de parameter -DefaultScope wanneer u de opdracht Set-AzDataLakeGen2ItemAclObject uitvoert. Voorbeeld: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -DefaultScope.

ACL's recursief bijwerken

Werk ACL's recursief bij met behulp van de cmdlet Update-AzDataLakeGen2AclRecursive .

In dit voorbeeld wordt een ACL-vermelding bijgewerkt met schrijfmachtigingen.

$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

Notitie

Gebruik de respectieve object-id's om de ACL van een specifieke groep of gebruiker, service-principal of beheerde identiteit in te stellen. Als u bijvoorbeeld de ACL van een groep wilt instellen, gebruikt u group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Als u de ACL van een gebruiker wilt instellen, gebruikt u user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Zie het naslagartikel Update-AzDataLakeGen2AclRecursive voor een voorbeeld waarin ACL's recursief worden bijgewerkt in batches door een batchgrootte op te geven.

ACL-vermeldingen verwijderen

In deze sectie ziet u hoe u het volgende kunt doen:

  • Een ACL-vermelding verwijderen
  • ACL-vermeldingen recursief verwijderen

Een ACL-vermelding verwijderen

In dit voorbeeld wordt een vermelding verwijderd uit een bestaande ACL.

$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

ACL-vermeldingen recursief verwijderen

U kunt een of meer ACL-vermeldingen recursief verwijderen. Als u een ACL-vermelding wilt verwijderen, maakt u een nieuw ACL-object voor de ACL-vermelding die moet worden verwijderd en gebruikt u dat object in de bewerking ACL verwijderen. Haal de bestaande ACL niet op, geef alleen de ACL-vermeldingen op die moeten worden verwijderd.

Verwijder ACL-vermeldingen met behulp van de cmdlet Remove-AzDataLakeGen2AclRecursive .

In dit voorbeeld wordt een ACL-vermelding verwijderd uit de hoofdmap van de container.

$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

Notitie

Als u een standaard-ACL-vermelding wilt verwijderen, gebruikt u de parameter -DefaultScope wanneer u de opdracht Set-AzDataLakeGen2ItemAclObject uitvoert. Voorbeeld: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---" -DefaultScope.

Zie het naslagartikel Remove-AzDataLakeGen2AclRecursive voor een voorbeeld dat ACL's recursief verwijdert in batches door een batchgrootte op te geven.

Herstellen na fouten

Er kunnen runtime- of machtigingsfouten optreden bij het recursief wijzigen van ACL's.

Voor runtimefouten start u het proces opnieuw vanaf het begin. Machtigingsfouten kunnen optreden als de beveiligingsprincipaal niet over voldoende machtigingen beschikt om de ACL te wijzigen van een map of bestand dat zich in de maphiërarchie bevindt die wordt gewijzigd. Los het machtigingsprobleem op en kies er vervolgens voor om het proces te hervatten vanaf het punt van de fout met behulp van een vervolgtoken of start het proces opnieuw vanaf het begin. U hoeft het vervolgtoken niet te gebruiken als u liever opnieuw wilt opstarten vanaf het begin. U kunt ACL-vermeldingen opnieuw gebruiken zonder negatieve gevolgen.

In dit voorbeeld worden de resultaten geretourneerd naar de variabele en worden de vermeldingen vervolgens niet in een opgemaakte tabel weergegeven.

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

Op basis van de uitvoer van de tabel kunt u eventuele machtigingsfouten oplossen en vervolgens de uitvoering hervatten met behulp van het vervolgtoken.

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

Zie het artikel Set-AzDataLakeGen2AclRecursive reference voor een voorbeeld waarmee ACL's recursief in batches worden ingesteld door een batchgrootte op te geven.

Als u wilt dat het proces ononderbroken wordt voltooid door machtigingsfouten, kunt u dat opgeven.

In dit voorbeeld wordt de ContinueOnFailure parameter gebruikt, zodat de uitvoering wordt voortgezet, zelfs als de bewerking een machtigingsfout tegenkomt.

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

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

Zie het artikel Set-AzDataLakeGen2AclRecursive reference voor een voorbeeld waarmee ACL's recursief in batches worden ingesteld door een batchgrootte op te geven.

Aanbevolen procedures

In deze sectie vindt u enkele aanbevolen richtlijnen voor het recursief instellen van ACL's.

Runtimefouten afhandelen

Een runtimefout kan om verschillende redenen optreden (bijvoorbeeld een storing of een probleem met de clientconnectiviteit). Als er een runtimefout optreedt, start u het recursieve ACL-proces opnieuw. ACL's kunnen opnieuw worden toegepast op items zonder een negatieve impact te veroorzaken.

Machtigingsfouten afhandelen (403)

Als er een uitzondering voor toegangsbeheer optreedt tijdens het uitvoeren van een recursief ACL-proces, beschikt uw AD-beveiligingsprincipaal mogelijk niet over voldoende machtigingen om een ACL toe te passen op een of meer onderliggende items in de adreslijsthiërarchie. Wanneer er een machtigingsfout optreedt, stopt het proces en wordt er een vervolgtoken opgegeven. Los het machtigingsprobleem op en gebruik vervolgens het vervolgtoken om de resterende gegevensset te verwerken. De mappen en bestanden die al zijn verwerkt, hoeven niet opnieuw te worden verwerkt. U kunt er ook voor kiezen om het recursieve ACL-proces opnieuw te starten. ACL's kunnen opnieuw worden toegepast op items zonder een negatieve impact te veroorzaken.

Referenties

U wordt aangeraden een Microsoft Entra-beveiligingsprincipaal in te richten waaraan de rol Eigenaar van opslagblobgegevens is toegewezen in het bereik van het doelopslagaccount of de doelcontainer.

Prestaties

Als u de latentie wilt verminderen, raden we u aan het recursieve ACL-proces uit te voeren op een virtuele Azure-machine (VM) die zich in dezelfde regio bevindt als uw opslagaccount.

ACL-limieten

Het maximum aantal ACL's dat u kunt toepassen op een map of bestand, is 32 toegangs-ACL's en 32 standaard-ACL's. Zie Toegangsbeheer in Azure Data Lake Storage Gen2 voor meer informatie.

Zie ook