Använda PowerShell för att hantera ACL:er i Azure Data Lake Storage Gen2

  • Artikel

Den här artikeln visar hur du använder PowerShell för att hämta, ange och uppdatera åtkomstkontrollistor med kataloger och filer.

ACL-arv är redan tillgängligt för nya underordnade objekt som skapas under en överordnad katalog. Men du kan också lägga till, uppdatera och ta bort ACL:er rekursivt på befintliga underordnade objekt i en överordnad katalog utan att behöva göra dessa ändringar individuellt för varje underordnat objekt.

Referens | Ge feedback

Förutsättningar

  • En Azure-prenumeration. Mer information finns i Hämta kostnadsfri utvärderingsversion av Azure.

  • Ett lagringskonto med hierarkisk namnrymd (HNS) aktiverat. Följ dessa instruktioner för att skapa en.

  • Azure CLI-version 2.6.0 eller senare.

  • En av följande säkerhetsbehörigheter:

    • Ett etablerat Säkerhetsobjekt för Microsoft Entra-ID som har tilldelats rollen Lagringsblobdataägare, begränsad till målcontainern, lagringskontot, den överordnade resursgruppen eller prenumerationen..

    • Ägande användare av målcontainern eller katalogen som du planerar att tillämpa ACL-inställningar på. Om du vill ange ACL:er rekursivt inkluderar detta alla underordnade objekt i målcontainern eller katalogen.

    • Lagringskontonyckel.

Installera PowerShell-modulen

  1. Kontrollera att den version av PowerShell som har installerats är 5.1 eller högre med hjälp av följande kommando.

    echo $PSVersionTable.PSVersion.ToString()

    Information om hur du uppgraderar din version av PowerShell finns i Uppgradera befintlig Windows PowerShell

  2. Installera Az.Storage-modulen .

    Install-Module Az.Storage -Repository PSGallery -Force

    Mer information om hur du installerar PowerShell-moduler finns i Installera Azure PowerShell-modulen

Anslut till kontot

Välj hur du vill att dina kommandon ska få auktorisering till lagringskontot.

Alternativ 1: Skaffa auktorisering med hjälp av Microsoft Entra-ID

Kommentar

Om du använder Microsoft Entra-ID för att auktorisera åtkomst kontrollerar du att ditt säkerhetsobjekt har tilldelats rollen Lagringsblobdataägare. Mer information om hur ACL-behörigheter tillämpas och hur du ändrar dem finns i Åtkomstkontrollmodell i Azure Data Lake Storage Gen2.

Med den här metoden ser systemet till att ditt användarkonto har lämpliga Azure-rollbaserade åtkomstkontrolltilldelningar (Azure RBAC) och ACL-behörigheter.

  1. Öppna ett Windows PowerShell-kommandofönster och logga sedan in på din Azure-prenumeration med Connect-AzAccount kommandot och följ anvisningarna på skärmen.

    Connect-AzAccount

  2. Om din identitet är associerad med mer än en prenumeration ställer du in din aktiva prenumeration på prenumerationen på det lagringskonto som du vill skapa och hantera kataloger i. I det här exemplet ersätter du <subscription-id> platshållarvärdet med ID:t för din prenumeration.

    Select-AzSubscription -SubscriptionId <subscription-id>

  3. Hämta kontexten för lagringskontot.

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

Alternativ 2: Skaffa auktorisering med hjälp av lagringskontonyckeln

Med den här metoden kontrollerar systemet inte Azure RBAC- eller ACL-behörigheter. Hämta kontexten för lagringskontot med hjälp av en kontonyckel.

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

Hämta ACL:er

Hämta ACL för en katalog eller fil med hjälp av cmdleten Get-AzDataLakeGen2Item.

Det här exemplet hämtar ACL för rotkatalogen för en container och skriver sedan ut ACL:en till konsolen.

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

Det här exemplet hämtar ACL:en för en katalog och skriver sedan ut ACL:en till konsolen.

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

Det här exemplet hämtar ACL:en för en fil och skriver sedan ut ACL:en till konsolen.

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

Följande bild visar utdata när du har hämtat ACL för en katalog.

Get ACL output for directory

I det här exemplet har den ägande användaren läs-, skriv- och körningsbehörigheter. Ägande gruppen har endast läs- och körningsbehörigheter. Mer information om åtkomstkontrollistor finns i Åtkomstkontroll i Azure Data Lake Storage Gen2.

Ange ACL:er

När du anger en ACL ersätter du hela ACL:en inklusive alla dess poster. Om du vill ändra behörighetsnivån för ett säkerhetsobjekt eller lägga till ett nytt säkerhetsobjekt i ACL:n utan att påverka andra befintliga poster bör du uppdatera ACL:en i stället. Information om hur du uppdaterar en ACL i stället för att ersätta den finns i avsnittet Uppdatera ACL:er i den här artikeln.

Om du väljer att ange ACL måste du lägga till en post för den ägande användaren, en post för ägande gruppen och en post för alla andra användare. Mer information om den ägande användaren, ägande gruppen och alla andra användare finns i Användare och identiteter.

Det här avsnittet visar hur du:

  • Ange en ACL
  • Ange ACL:er rekursivt

Ange en ACL

Använd cmdleten Set-AzDataLakeGen2ItemAclObject för att skapa en ACL för den ägande användaren, ägande gruppen eller andra användare. Använd sedan cmdleten Update-AzDataLakeGen2Item för att checka in ACL:en.

I det här exemplet anges ACL i rotkatalogen för en container för den ägande användaren, ägande gruppen eller andra användare och skriver sedan ut ACL:en till konsolen.

$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

Det här exemplet anger ACL på en katalog för den ägande användaren, ägande gruppen eller andra användare och skriver sedan ut ACL:en till konsolen.

$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

Kommentar

Om du vill ange en standardpost för ACL använder du parametern -DefaultScope när du kör kommandot Set-AzDataLakeGen2ItemAclObject . Exempel: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope.

Det här exemplet anger ACL på en fil för den ägande användaren, ägande gruppen eller andra användare och skriver sedan ut ACL:en till konsolen.

$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

Kommentar

Om du vill ange ACL för en viss grupp eller användare, tjänstens huvudnamn eller hanterade identitet använder du deras respektive objekt-ID:n. Om du till exempel vill ange ACL för en grupp använder du group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Om du vill ange en användares ACL använder du user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Följande bild visar utdata när du har angett ACL för en fil.

Get ACL output for file

I det här exemplet har ägande användare och ägande grupp endast läs- och skrivbehörigheter. Alla andra användare har skriv- och körningsbehörigheter. Mer information om åtkomstkontrollistor finns i Åtkomstkontroll i Azure Data Lake Storage Gen2.

Ange ACL:er rekursivt

Ange ACL:er rekursivt med hjälp av cmdleten Set-AzDataLakeGen2AclRecursive .

I det här exemplet anges ACL för en katalog med namnet my-parent-directory. Dessa poster ger den ägande användaren läs-, skriv- och körningsbehörighet, ger ägande gruppen endast läs- och körningsbehörigheter och ger alla andra ingen åtkomst. Den sista ACL-posten i det här exemplet ger en specifik användare med objekt-ID:t "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" läs- och körningsbehörigheter.

$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

Kommentar

Om du vill ange en standardpost för ACL använder du parametern -DefaultScope när du kör kommandot Set-AzDataLakeGen2ItemAclObject . Exempel: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope.

Ett exempel som anger ACL:er rekursivt i batchar genom att ange en batchstorlek finns i referensartikeln Set-AzDataLakeGen2AclRecursive .

Uppdatera ACL:er

När du uppdaterar en ACL ändrar du ACL:en i stället för att ersätta ACL:en. Du kan till exempel lägga till ett nytt säkerhetsobjekt till ACL utan att påverka andra säkerhetsobjekt som anges i ACL: n. Om du vill ersätta ACL:en i stället för att uppdatera den läser du avsnittet Ange ACL:er i den här artikeln.

Det här avsnittet visar hur du:

  • Uppdatera en ACL
  • Uppdatera ACL:er rekursivt

Uppdatera en ACL

Hämta först ACL:en. Använd sedan cmdleten Set-AzDataLakeGen2ItemAclObject för att lägga till eller uppdatera en ACL-post. Använd cmdleten Update-AzDataLakeGen2Item för att checka in ACL:en.

Det här exemplet skapar eller uppdaterar ACL:en i en katalog för en användare.

$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

Kommentar

Om du vill uppdatera en standardpost för ACL använder du parametern -DefaultScope när du kör kommandot Set-AzDataLakeGen2ItemAclObject . Exempel: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -DefaultScope.

Uppdatera ACL:er rekursivt

Uppdatera ACL:er rekursivt med hjälp av cmdleten Update-AzDataLakeGen2AclRecursive .

I det här exemplet uppdateras en ACL-post med skrivbehörighet.

$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

Kommentar

Om du vill ange ACL för en viss grupp eller användare, tjänstens huvudnamn eller hanterade identitet använder du deras respektive objekt-ID:n. Om du till exempel vill ange ACL för en grupp använder du group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Om du vill ange en användares ACL använder du user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Ett exempel som uppdaterar ACL:er rekursivt i batchar genom att ange en batchstorlek finns i referensartikeln Update-AzDataLakeGen2AclRecursive .

Ta bort ACL-poster

Det här avsnittet visar hur du:

  • Ta bort en ACL-post
  • Ta bort ACL-poster rekursivt

Ta bort en ACL-post

Det här exemplet tar bort en post från en befintlig 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

Ta bort ACL-poster rekursivt

Du kan ta bort en eller flera ACL-poster rekursivt. Om du vill ta bort en ACL-post skapar du ett nytt ACL-objekt för ACL-posten som ska tas bort och använder sedan objektet i ta bort ACL-åtgärden. Hämta inte den befintliga ACL:en. Ange bara de ACL-poster som ska tas bort.

Ta bort ACL-poster med cmdleten Remove-AzDataLakeGen2AclRecursive .

Det här exemplet tar bort en ACL-post från containerns rotkatalog.

$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

Kommentar

Om du vill ta bort en standardpost för ACL använder du parametern -DefaultScope när du kör kommandot Set-AzDataLakeGen2ItemAclObject . Exempel: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---" -DefaultScope.

Om du vill se ett exempel som tar bort ACL:er rekursivt i batchar genom att ange en batchstorlek kan du läsa referensartikeln Remove-AzDataLakeGen2AclRecursive .

Återställa från fel

Du kan stöta på körnings- eller behörighetsfel när du ändrar ACL:er rekursivt.

Starta om processen från början för körningsfel. Behörighetsfel kan inträffa om säkerhetsobjektet inte har tillräcklig behörighet för att ändra ACL för en katalog eller fil som finns i kataloghierarkin som ändras. Åtgärda behörighetsproblemet och välj sedan att antingen återuppta processen från felpunkten med hjälp av en fortsättningstoken eller starta om processen från början. Du behöver inte använda fortsättningstoken om du föredrar att starta om från början. Du kan använda ACL-poster igen utan någon negativ inverkan.

Det här exemplet returnerar resultat till variabeln och skickar sedan misslyckade poster till en formaterad tabell.

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

Baserat på tabellens utdata kan du åtgärda eventuella behörighetsfel och sedan återuppta körningen med hjälp av fortsättningstoken.

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

Ett exempel som anger ACL:er rekursivt i batchar genom att ange en batchstorlek finns i referensartikeln Set-AzDataLakeGen2AclRecursive .

Om du vill att processen ska slutföras utan avbrott av behörighetsfel kan du ange det.

I det här exemplet används parametern ContinueOnFailure så att körningen fortsätter även om åtgärden påträffar ett behörighetsfel.

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

Ett exempel som anger ACL:er rekursivt i batchar genom att ange en batchstorlek finns i referensartikeln Set-AzDataLakeGen2AclRecursive .

Bästa praxis

Det här avsnittet innehåller några riktlinjer för bästa praxis för att ställa in ACL:er rekursivt.

Hantera körningsfel

Ett körningsfel kan inträffa av många orsaker (till exempel ett avbrott eller ett problem med klientanslutningen). Om du stöter på ett körningsfel startar du om den rekursiva ACL-processen. ACL:er kan tillämpas på objekt igen utan att orsaka en negativ inverkan.

Hantera behörighetsfel (403)

Om du stöter på ett undantag för åtkomstkontroll när du kör en rekursiv ACL-process kanske ditt AD-säkerhetsobjekt inte har tillräcklig behörighet för att tillämpa en ACL på ett eller flera av de underordnade objekten i kataloghierarkin. När ett behörighetsfel inträffar stoppas processen och en fortsättningstoken tillhandahålls. Åtgärda behörighetsproblemet och använd sedan fortsättningstoken för att bearbeta den återstående datauppsättningen. Katalogerna och filerna som redan har bearbetats behöver inte bearbetas igen. Du kan också välja att starta om den rekursiva ACL-processen. ACL:er kan tillämpas på objekt igen utan att orsaka en negativ inverkan.

Autentiseringsuppgifter

Vi rekommenderar att du etablerar ett Microsoft Entra-säkerhetsobjekt som har tilldelats rollen Storage Blob Data Owner i omfånget för mållagringskontot eller containern.

Prestanda

För att minska svarstiden rekommenderar vi att du kör den rekursiva ACL-processen på en virtuell Azure-dator (VM) som finns i samma region som ditt lagringskonto.

ACL-gränser

Det maximala antalet ACL:er som du kan använda för en katalog eller fil är 32 åtkomst-ACL:er och 32 standard-ACL:er. Mer information finns i Åtkomstkontroll i Azure Data Lake Storage Gen2.

Se även