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

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.

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.

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

Vereisten

  • Een Azure-abonnement. Zie Gratis proefversie van Azure ophalen.

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

Uw project instellen

Installeer het NuGet-pakket Azure.Storage.Files.DataLake om aan de slag te gaan.

  1. Open een opdrachtvenster (bijvoorbeeld: Windows PowerShell).

  2. Installeer vanuit de projectmap het pakket Azure.Storage.Files.DataLake preview met behulp van de dotnet add package opdracht.

    dotnet add package Azure.Storage.Files.DataLake -v 12.6.0 -s https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-net/nuget/v3/index.json
    

    Voeg deze vervolgens toe met behulp van instructies boven aan 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 naar het account

Als u de fragmenten in dit artikel wilt gebruiken, moet u een DataLakeServiceClient-exemplaar maken dat het opslagaccount vertegenwoordigt.

Verbinding maken 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.

U kunt de Azure Identity-clientbibliotheek voor .NET gebruiken om uw toepassing te verifiëren met Microsoft Entra-id.

Nadat u het pakket hebt geïnstalleerd, voegt u deze using-instructie toe aan het begin van het codebestand.

using Azure.Identity;

Eerst moet u een van de volgende azure RBAC-rollen (op rollen gebaseerd toegangsbeheer) toewijzen aan uw beveiligingsprincipaal:

- Rol ACL-instellingsmogelijkheid
Eigenaar van opslagblobgegevens Alle mappen en bestanden in het account.
Inzender voor Storage Blob-gegevens 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.

Verbinding maken met behulp van een accountsleutel

U kunt toegang tot gegevens autoriseren met behulp van uw accounttoegangssleutels (gedeelde sleutel). In dit voorbeeld wordt een DataLakeServiceClient-exemplaar gemaakt dat is geautoriseerd met de accountsleutel.

public static DataLakeServiceClient GetDataLakeServiceClient(string accountName, string accountKey)
{
    StorageSharedKeyCredential sharedKeyCredential =
        new StorageSharedKeyCredential(accountName, accountKey);

    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

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

    return dataLakeServiceClient;
}

Let op

Autorisatie met gedeelde sleutel wordt niet aanbevolen omdat deze mogelijk minder veilig is. Schakel voor optimale beveiliging autorisatie uit via een gedeelde sleutel voor uw opslagaccount, zoals beschreven in Autorisatie van gedeelde sleutels voorkomen voor een Azure Storage-account.

Het gebruik van toegangssleutels en verbindingsreeks s moet worden beperkt tot het eerste bewijs van concept-apps of prototypen voor ontwikkeling die geen toegang hebben tot productie- of gevoelige gegevens. Anders moeten de verificatieklassen op basis van tokens die beschikbaar zijn in de Azure SDK altijd de voorkeur krijgen bij het verifiëren bij Azure-resources.

Microsoft raadt aan dat clients Microsoft Entra ID of sas (Shared Access Signature) gebruiken om toegang tot gegevens in Azure Storage te autoriseren. Zie Bewerkingen autoriseren voor gegevenstoegang voor meer informatie.

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

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