Share via

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

  • Artikel

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

ACL-overname is al beschikbaar voor nieuwe onderliggende items die onder een bovenliggende map zijn gemaakt. 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.

Package (NuGet) | Samples | API reference | Gen1 to Gen2 mapping | Give Feedback

Vereisten

  • Azure-abonnement: maak er gratis een.
  • Azure Storage-account waarvoor HNS (hiërarchische naamruimte) 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 opslagblobgegevens is 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.

Uw project instellen

In deze sectie wordt beschreven hoe u een project instelt voor gebruik met de Azure Storage Data Lake-clientbibliotheek.

Pakketten installeren

Installeer vanuit uw projectmap pakketten voor de Azure Storage Data Lake- en Azure Identity-clientbibliotheken met behulp van de dotnet add package opdracht. Het Azure.Identity-pakket is nodig voor verbindingen zonder wachtwoord met Azure-services.

dotnet add package Azure.Storage.Files.DataLake
dotnet add package Azure.Identity

Voeg using-instructies toe

Voeg deze using instructies toe aan het begin van het codebestand:

using Azure;
using Azure.Core;
using Azure.Storage;
using Azure.Storage.Files.DataLake;
using Azure.Storage.Files.DataLake.Models;
using System.Collections.Generic;
using System.Threading.Tasks;

Verbinding maken met het account

Als u de codevoorbeelden in dit artikel wilt uitvoeren, moet u een DataLakeServiceClient-exemplaar maken dat het opslagaccount vertegenwoordigt. U kunt het clientobject autoriseren met Microsoft Entra ID-referenties of met een accountsleutel.

U kunt de Azure Identity-clientbibliotheek voor .NET gebruiken om uw toepassing te verifiëren met 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 voor meer informatie over hoe ACL-machtigingen worden toegepast en wat de gevolgen zijn van het wijzigen ervan.

Wijs eerst een van de volgende azure RBAC-rollen (op rollen gebaseerd toegangsbeheer) toe aan uw beveiligingsprincipaal:

Role ACL-instellingsmogelijkheid
Eigenaar van opslagblobgegevens Alle mappen en bestanden in het account.
Inzender van opslag-blobgegevens Alleen mappen en bestanden die eigendom zijn van de beveiligingsprincipaal.

Maak vervolgens een DataLakeServiceClient-exemplaar en geef een nieuw exemplaar van de klasse DefaultAzureCredential door .

public static DataLakeServiceClient GetDataLakeServiceClient(string accountName)
{
    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        new DefaultAzureCredential());

    return dataLakeServiceClient;
}

Zie .NET-toepassingen verifiëren met Azure-services voor meer informatie over het gebruik van DefaultAzureCredential om toegang tot gegevens te autoriseren.

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:

  • De ACL van een map instellen
  • De ACL van een bestand instellen
  • ACL's recursief instellen

De ACL van een map instellen

Haal de toegangsbeheerlijst (ACL) van een map op door de methode DataLakeDirectoryClient.GetAccessControlAsync aan te roepen en de ACL in te stellen door de methode DataLakeDirectoryClient.SetAccessControlList aan te roepen.

In dit voorbeeld wordt de ACL van een map met de naam my-directoryopgehaald en ingesteld. De tekenreeks user::rwx,group::r-x,other::rw- geeft de gebruiker lees-, schrijf- en uitvoermachtigingen, geeft de groep die eigenaar is alleen lees- en uitvoermachtigingen en geeft alle andere lees- en schrijfmachtigingen.

public async Task ManageDirectoryACLs(DataLakeFileSystemClient fileSystemClient)
{
    DataLakeDirectoryClient directoryClient =
      fileSystemClient.GetDirectoryClient("");

    PathAccessControl directoryAccessControl =
        await directoryClient.GetAccessControlAsync();

    foreach (var item in directoryAccessControl.AccessControlList)
    {
        Console.WriteLine(item.ToString());
    }

    IList<PathAccessControlItem> accessControlList
        = PathAccessControlExtensions.ParseAccessControlList
        ("user::rwx,group::r-x,other::rw-");

    directoryClient.SetAccessControlList(accessControlList);

}

U kunt ook de ACL van de hoofdmap van een container ophalen en instellen. Als u de hoofdmap wilt ophalen, geeft u een lege tekenreeks ("") door aan de methode DataLakeFileSystemClient.GetDirectoryClient .

De ACL van een bestand instellen

Haal de toegangsbeheerlijst (ACL) van een bestand op door de methode DataLakeFileClient.GetAccessControlAsync aan te roepen en de ACL in te stellen door de methode DataLakeFileClient.SetAccessControlList aan te roepen.

In dit voorbeeld wordt de ACL van een bestand met de naam my-file.txtopgehaald en ingesteld. De tekenreeks user::rwx,group::r-x,other::rw- geeft de gebruiker lees-, schrijf- en uitvoermachtigingen, geeft de groep die eigenaar is alleen lees- en uitvoermachtigingen en geeft alle andere lees- en schrijfmachtigingen.

public async Task ManageFileACLs(DataLakeFileSystemClient fileSystemClient)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient("my-directory");

    DataLakeFileClient fileClient =
        directoryClient.GetFileClient("hello.txt");

    PathAccessControl FileAccessControl =
        await fileClient.GetAccessControlAsync();

    foreach (var item in FileAccessControl.AccessControlList)
    {
        Console.WriteLine(item.ToString());
    }

    IList<PathAccessControlItem> accessControlList
        = PathAccessControlExtensions.ParseAccessControlList
        ("user::rwx,group::r-x,other::rw-");

    fileClient.SetAccessControlList(accessControlList);
}

ACL's recursief instellen

Stel ACL's recursief in door de methode DataLakeDirectoryClient.SetAccessControlRecursiveAsync aan te roepen. Geef deze methode een lijst met PathAccessControlItem door. Elke PathAccessControlItem definieert een ACL-vermelding.

Als u een standaard-ACL-vermelding wilt instellen, kunt u de eigenschap PathAccessControlItem.DefaultScope van pathAccessControlItem instellen op true.

In dit voorbeeld wordt de ACL van een map met de naam my-parent-directoryingesteld. Deze methode accepteert een Booleaanse parameter met de naam isDefaultScope die aangeeft of de standaard-ACL moet worden ingesteld. Deze parameter wordt gebruikt in de constructor van pathAccessControlItem. De vermeldingen van de ACL geven de gebruiker lees-, schrijf- en uitvoermachtigingen, geven 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 lees- en uitvoermachtigingen voor de object-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx .

    public async Task SetACLRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
    DataLakeDirectoryClient directoryClient =
        serviceClient.GetFileSystemClient("my-container").
            GetDirectoryClient("my-parent-directory");

    List<PathAccessControlItem> accessControlList =
        new List<PathAccessControlItem>()
    {
new PathAccessControlItem(AccessControlType.User,
    RolePermissions.Read |
    RolePermissions.Write |
    RolePermissions.Execute, isDefaultScope),

new PathAccessControlItem(AccessControlType.Group,
    RolePermissions.Read |
    RolePermissions.Execute, isDefaultScope),

new PathAccessControlItem(AccessControlType.Other,
    RolePermissions.None, isDefaultScope),

new PathAccessControlItem(AccessControlType.User,
    RolePermissions.Read |
    RolePermissions.Execute, isDefaultScope,
    entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
    };

    await directoryClient.SetAccessControlRecursiveAsync
        (accessControlList, null);
}

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 van een map op door de methode DataLakeDirectoryClient.GetAccessControlAsync aan te roepen. Kopieer de lijst met ACL-vermeldingen naar een nieuwe lijst met PathAccessControl-objecten . Zoek vervolgens de vermelding die u wilt bijwerken en vervang deze in de lijst. Stel de ACL in door de methode DataLakeDirectoryClient.SetAccessControlList aan te roepen.

In dit voorbeeld wordt de hoofd-ACL van een container bijgewerkt door de ACL-vermelding voor alle andere gebruikers te vervangen.

public async Task UpdateDirectoryACLs(DataLakeFileSystemClient fileSystemClient)
{
    DataLakeDirectoryClient directoryClient =
      fileSystemClient.GetDirectoryClient("");

    PathAccessControl directoryAccessControl =
        await directoryClient.GetAccessControlAsync();

    List<PathAccessControlItem> accessControlListUpdate 
        = (List<PathAccessControlItem>)directoryAccessControl.AccessControlList;

    int index = -1;

    foreach (var item in accessControlListUpdate)
    {
        if (item.AccessControlType == AccessControlType.Other)
        {
            index = accessControlListUpdate.IndexOf(item);
            break;
        }
    }

    if (index > -1)
    {
        accessControlListUpdate[index] = new PathAccessControlItem(AccessControlType.Other,
        RolePermissions.Read |
        RolePermissions.Execute);

        directoryClient.SetAccessControlList(accessControlListUpdate);
    }

   }

ACL's recursief bijwerken

Als u een ACL recursief wilt bijwerken, maakt u een nieuw ACL-object met de ACL-vermelding die u wilt bijwerken en gebruikt u dat object in de update-ACL-bewerking. Haal de bestaande ACL niet op, geef alleen ACL-vermeldingen op die moeten worden bijgewerkt.

Werk een ACL recursief bij door de methode DataLakeDirectoryClient.UpdateAccessControlRecursiveAsync aan te roepen. Geef deze methode een lijst met PathAccessControlItem door. Elke PathAccessControlItem definieert een ACL-vermelding.

Als u een standaard-ACL-vermelding wilt bijwerken, kunt u de eigenschap PathAccessControlItem.DefaultScope van pathAccessControlItem instellen op true.

In dit voorbeeld wordt een ACL-vermelding bijgewerkt met schrijfmachtigingen. Deze methode accepteert een Booleaanse parameter met de naam isDefaultScope die aangeeft of de standaard-ACL moet worden bijgewerkt. Deze parameter wordt gebruikt in de constructor van pathAccessControlItem.

public async Task UpdateACLsRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
    DataLakeDirectoryClient directoryClient =
        serviceClient.GetFileSystemClient("my-container").
        GetDirectoryClient("my-parent-directory");

    List<PathAccessControlItem> accessControlListUpdate =
        new List<PathAccessControlItem>()
    {
new PathAccessControlItem(AccessControlType.User,
    RolePermissions.Read |
    RolePermissions.Write |
    RolePermissions.Execute, isDefaultScope,
    entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
    };

    await directoryClient.UpdateAccessControlRecursiveAsync
        (accessControlListUpdate, null);

}

ACL-vermeldingen verwijderen

U kunt een of meer 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

Haal eerst de ACL van een map op door de methode DataLakeDirectoryClient.GetAccessControlAsync aan te roepen. Kopieer de lijst met ACL-vermeldingen naar een nieuwe lijst met PathAccessControl-objecten . Zoek vervolgens de vermelding die u wilt verwijderen en roep de methode Remove van de verzameling aan. Stel de bijgewerkte ACL in door de methode DataLakeDirectoryClient.SetAccessControlList aan te roepen.

In dit voorbeeld wordt de hoofd-ACL van een container bijgewerkt door de ACL-vermelding voor alle andere gebruikers te vervangen.

public async Task RemoveDirectoryACLEntry
    (DataLakeFileSystemClient fileSystemClient)
{
    DataLakeDirectoryClient directoryClient =
      fileSystemClient.GetDirectoryClient("");

    PathAccessControl directoryAccessControl =
        await directoryClient.GetAccessControlAsync();

    List<PathAccessControlItem> accessControlListUpdate
        = (List<PathAccessControlItem>)directoryAccessControl.AccessControlList;

    PathAccessControlItem entryToRemove = null;

    foreach (var item in accessControlListUpdate)
    {
        if (item.EntityId == "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
        {
            entryToRemove = item;
            break;
        }
    }

    if (entryToRemove != null)
    {
        accessControlListUpdate.Remove(entryToRemove);
        directoryClient.SetAccessControlList(accessControlListUpdate);
    }

}

ACL-vermeldingen recursief verwijderen

Als u ACL-vermeldingen recursief 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 door de methode DataLakeDirectoryClient.RemoveAccessControlRecursiveAsync aan te roepen. Geef deze methode een lijst met PathAccessControlItem door. Elke PathAccessControlItem definieert een ACL-vermelding.

Als u een standaard-ACL-vermelding wilt verwijderen, kunt u de eigenschap PathAccessControlItem.DefaultScope van pathAccessControlItem instellen op true.

In dit voorbeeld wordt een ACL-vermelding verwijderd uit de ACL van de map met de naam my-parent-directory. Deze methode accepteert een Booleaanse parameter met de naam isDefaultScope die aangeeft of de vermelding moet worden verwijderd uit de standaard-ACL. Deze parameter wordt gebruikt in de constructor van pathAccessControlItem.

public async Task RemoveACLsRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
    DataLakeDirectoryClient directoryClient =
        serviceClient.GetFileSystemClient("my-container").
            GetDirectoryClient("my-parent-directory");

    List<RemovePathAccessControlItem> accessControlListForRemoval =
        new List<RemovePathAccessControlItem>()
        {
    new RemovePathAccessControlItem(AccessControlType.User, isDefaultScope,
    entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
        };

    await directoryClient.RemoveAccessControlRecursiveAsync
        (accessControlListForRemoval, null);

}

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 wordt een vervolgtoken geretourneerd in het geval van een fout. De toepassing kan deze voorbeeldmethode opnieuw aanroepen nadat de fout is opgelost en het vervolgtoken doorgeven. Als deze voorbeeldmethode voor het eerst wordt aangeroepen, kan de toepassing een waarde van null de vervolgtokenparameter doorgeven.

public async Task<string> ResumeAsync(DataLakeServiceClient serviceClient,
    DataLakeDirectoryClient directoryClient,
    List<PathAccessControlItem> accessControlList,
    string continuationToken)
{
    try
    {
        var accessControlChangeResult =
            await directoryClient.SetAccessControlRecursiveAsync(
                accessControlList, continuationToken: continuationToken, null);

        if (accessControlChangeResult.Value.Counters.FailedChangesCount > 0)
        {
            continuationToken =
                accessControlChangeResult.Value.ContinuationToken;
        }

        return continuationToken;
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
        return continuationToken;
    }

}

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

Om ervoor te zorgen dat het proces ononderbroken wordt voltooid, geeft u een AccessControlChangedOptions-object door en stelt u de eigenschap ContinueOnFailure van dat object in op true.

In dit voorbeeld worden ACL-vermeldingen recursief ingesteld. Als deze code een machtigingsfout tegenkomt, wordt die fout vastgelegd en wordt de uitvoering voortgezet. In dit voorbeeld wordt het aantal fouten in de console afgedrukt.

public async Task ContinueOnFailureAsync(DataLakeServiceClient serviceClient,
    DataLakeDirectoryClient directoryClient,
    List<PathAccessControlItem> accessControlList)
{
    var accessControlChangeResult =
        await directoryClient.SetAccessControlRecursiveAsync(
            accessControlList, null, new AccessControlChangeOptions()
            { ContinueOnFailure = true });

    var counters = accessControlChangeResult.Value.Counters;

    Console.WriteLine("Number of directories changed: " +
        counters.ChangedDirectoriesCount.ToString());

    Console.WriteLine("Number of files changed: " +
        counters.ChangedFilesCount.ToString());

    Console.WriteLine("Number of failures: " +
        counters.FailedChangesCount.ToString());
}

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.

Referentie

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