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

Dit artikel laat zien hoe je PowerShell gebruikt om de toegangscontrolelijsten (ACL's) van mappen en bestanden op te halen, in te stellen en bij te werken.

Nieuwe kinditems die je onder een oudermap aanmaakt, erven automatisch ACL's. Je kunt echter ook ACL's recursief toevoegen, bijwerken en verwijderen op bestaande kinditems van een oudermap zonder deze wijzigingen individueel voor elk kinditem aan te brengen.

Naslagwerk | Feedback 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.

• Een van de volgende beveiligingsmachtigingen:

  • Een ingerichte Microsoft Entra ID-beveiligingsprincipal waaraan de rol Storage Blob Data Owner is toegewezen, met als bereik 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. Om ACL's recursief in te stellen, bevat deze gebruiker alle kinditems in de doelcontainer of directory.

De PowerShell-module installeren

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

   echo $PSVersionTable.PSVersion.ToString()
   

   Om je versie van PowerShell te upgraden, zie Bestaande Windows PowerShell upgraden.

2. Installeer de Az.Storage-module .

   Install-Module Az.Storage -Repository PSGallery -Force  
   

   Voor meer informatie over hoe je PowerShell-modules installeert, zie Install the Azure PowerShell module.

Verbinding maken met het account

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

   Connect-AzAccount
   

2. Als je identiteit aan meer dan één abonnement is gekoppeld en je wordt niet gevraagd het abonnement te selecteren, stel je actieve abonnement dan in op het abonnement van het opslagaccount dat je wilt gebruiken. 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
   

ACLs ophalen

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

In Azure Data Lake Storage wordt een container ook wel een bestandssysteem genoemd. De -FileSystem parameter die in de volgende voorbeelden wordt gebruikt, neemt de naam van je container aan.

Het volgende voorbeeld haalt de ACL van de rootmap van een container op en print vervolgens de ACL naar de console.

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

Het volgende voorbeeld krijgt de ACL van een map en print vervolgens de ACL naar de console.

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

Het volgende voorbeeld krijgt de ACL van een bestand en print vervolgens de ACL naar de console.

$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.

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 voor meer informatie over toegangsbeheerlijsten.

ACL's instellen

Wanneer je een ACL instelt, vervang je de volledige ACL, inclusief alle items. Als je het permissieniveau van een security principal wilt wijzigen of een nieuwe security principal aan de ACL wilt toevoegen zonder andere bestaande vermeldingen te beïnvloeden, werk dan de ACL bij. 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 cmdlet Set-AzDataLakeGen2ItemAclObject om een ACL te maken voor de gebruiker, de groep die eigenaar is of andere gebruikers. Gebruik vervolgens de cmdlet Update-AzDataLakeGen2Item om de ACL door te voeren.

In dit voorbeeld wordt de ACL ingesteld voor de hoofdmap van een container voor de eigenaar, de eigenaarsgroep of andere gebruikers, waarna de ACL op de console wordt afgedrukt.

$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 gebruiker die eigenaar is, de eigenaarsgroep of andere gebruikers, en wordt de ACL vervolgens in de console weergegeven.

$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 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

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

In dit voorbeeld hebben de eigenaar-gebruiker en de eigenaar-groep alleen lees- en schrijfrechten. Alle andere gebruikers hebben schrijf- en uitvoermachtigingen. Zie Toegangsbeheer in Azure Data Lake Storage 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 items geven de eigenaar lees-, schrijf- en uitvoerrechten, geven de groep waartoe de eigenaar behoort alleen lees- en uitvoerrechten, en geven 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

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 cmdlet Set-AzDataLakeGen2ItemAclObject om een ACL-vermelding toe te voegen of bij te werken. Gebruik de cmdlet Update-AzDataLakeGen2Item om de ACL door te voeren.

In dit voorbeeld wordt de ACL voor een gebruiker gemaakt of bijgewerkt op 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 aaaaaaaa-bbbb-cccc-1111-222222222222 -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

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

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. Het hergebruikt de context van opslagaccounts $ctx en de $acl, $filesystemName, en variabelen $dirname die in eerdere secties van dit artikel zijn vastgesteld.

$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. Om een ACL-invoer te verwijderen, maak je een nieuw ACL-object aan voor de ACL-invoer die je wilt verwijderen, en gebruik je dat object vervolgens in de ACL-verwijderingsoperatie. 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

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

Herstellen van storingen

Er kunnen runtime- of machtigingsfouten optreden bij het recursief wijzigen van ACL's. De voorbeelden in deze sectie hergebruiken de context van het $ctx opslagaccount en de $filesystemName, $dirname, en variabelen $acl die in eerdere secties van dit artikel zijn vastgesteld.

Voor runtimefouten start u het proces opnieuw vanaf het begin. Toestemmingsfouten kunnen optreden als de security principal niet voldoende toestemming heeft om de ACL van een map of bestand in de directoryhiërarchie te wijzigen die je aan het wijzigen bent. Pak het permissieprobleem aan en kies er vervolgens voor om het proces te hervatten vanaf het punt van falen met behulp van een continuïteitstoken, of het proces opnieuw te starten. 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.

Dit voorbeeld geeft resultaten terug aan de variabele en stuurt vervolgens mislukte vermeldingen naar een opgemaakte tabel.

$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 je wilt dat het proces wordt afgerond zonder onderbreking door permissiefouten, kun je het zo configureren.

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.TotalDirectoriesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalFilesSuccessfulCount)"
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.

Beste praktijken

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.

Inloggegevens

We raden u aan een Microsoft Entra-beveiligingsprincipal te configureren waaraan de rol Storage Blob Data Owner is toegewezen binnen 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

• Bekende problemen
• PowerShell-cmdlets voor opslag
• Toegangsbeheermodel in Azure Data Lake Storage
• Toegangsbeheerlijsten (ACL's) in Azure Data Lake Storage