Sdílet prostřednictvím

Použití .NET ke správě seznamů ACL ve službě Azure Data Lake Storage

  • Článek

V tomto článku se dozvíte, jak pomocí .NET získat, nastavit a aktualizovat seznamy řízení přístupu adresářů a souborů.

Pro nové podřízené položky vytvořené v rámci nadřazeného adresáře už je k dispozici dědičnost seznamů ACL. Seznamy ACL ale můžete přidávat, aktualizovat a odebírat rekurzivně u existujících podřízených položek nadřazeného adresáře, aniž byste museli provádět tyto změny jednotlivě pro každou podřízenou položku.

Referenční informace k rozhraní API pro balíčky (NuGet) | s referenčními informacemi | | k mapování | Gen1 na Gen2

Požadavky

  • Předplatné Azure – vytvořte si ho zdarma.
  • Účet úložiště Azure s povoleným hierarchickým oborem názvů (HNS). Postupujte podle těchto pokynů a vytvořte ho.
  • Verze 2.6.0 Azure CLI nebo vyšší.
  • Jedno z následujících oprávnění zabezpečení:
    • Zřízený objekt zabezpečení Microsoft Entra ID, který má přiřazenou roli Vlastník dat objektu blob služby Storage, vymezený cílový kontejner, účet úložiště, nadřazenou skupinu prostředků nebo předplatné.
    • Vlastníkem cílového kontejneru nebo adresáře, u kterého plánujete použít nastavení seznamu ACL. Pokud chcete seznamy ACL nastavit rekurzivně, zahrnuje to všechny podřízené položky v cílovém kontejneru nebo adresáři.
    • Klíč účtu úložiště.

Nastavení projektu

V této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Storage Data Lake.

Instalace balíčků

Z adresáře projektu nainstalujte balíčky pro klientské knihovny Azure Storage Data Lake a Azure Identity pomocí dotnet add package příkazu. Balíček Azure.Identity je potřeba pro připojení bez hesla ke službám Azure.

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

Přidání using direktiv

Na začátek souboru kódu přidejte tyto using direktivy:

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;

Připojení k účtu

Pokud chcete spustit příklady kódu v tomto článku, musíte vytvořit instanci DataLakeServiceClient , která představuje účet úložiště. Klientský objekt můžete autorizovat pomocí přihlašovacích údajů Microsoft Entra ID nebo pomocí klíče účtu.

Klientskou knihovnu identit Azure pro .NET můžete použít k ověření aplikace pomocí Microsoft Entra ID.

Poznámka:

Pokud k autorizaci přístupu používáte MICROSOFT Entra ID, ujistěte se, že je vašemu objektu zabezpečení přiřazena role Vlastník dat objektu blob služby Storage. Další informace o tom, jak se použijí oprávnění seznamu ACL a vliv jejich změny, najdete v tématu Model řízení přístupu ve službě Azure Data Lake Storage.

Nejprve přiřaďte k objektu zabezpečení jednu z následujících rolí řízení přístupu na základě role (Azure RBAC ):

Role Funkce nastavení seznamu ACL
Vlastník dat v objektech blob služby Storage Všechny adresáře a soubory v účtu.
Přispěvatel dat objektů blob úložiště Objekt zabezpečení vlastní pouze adresáře a soubory.

Dále vytvořte instanci DataLakeServiceClient a předejte novou instanci DefaultAzureCredential třídy.

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;
}

Další informace o použití DefaultAzureCredential k autorizaci přístupu k datům najdete v tématu Postup ověřování aplikací .NET pomocí služeb Azure.

Nastavení seznamů ACL

Když nastavíte seznam ACL, nahradíte celý seznam ACL včetně všech jeho položek. Pokud chcete změnit úroveň oprávnění objektu zabezpečení nebo přidat nový objekt zabezpečení do seznamu ACL, aniž by to ovlivnilo jiné existující položky, měli byste místo toho aktualizovat seznam ACL. Pokud chcete místo nahrazení aktualizovat seznam ACL, přečtěte si část Aktualizace seznamů ACL tohoto článku.

Pokud se rozhodnete nastavit seznam ACL, musíte přidat položku pro vlastnícího uživatele, položku pro vlastnící skupinu a položku pro všechny ostatní uživatele. Další informace o vlastnícího uživatele, vlastnící skupině a všech ostatních uživatelích najdete v tématu Uživatelé a identity.

V této části se dozvíte, jak:

  • Nastavení seznamu ACL adresáře
  • Nastavení seznamu ACL souboru
  • Rekurzivní nastavení seznamů ACL

Nastavení seznamu ACL adresáře

Získejte seznam řízení přístupu (ACL) adresáře voláním Metody DataLakeDirectoryClient.GetAccessControlAsync a nastavte seznam ACL voláním Metody DataLakeDirectoryClient.SetAccessControlList .

Tento příklad získá a nastaví seznam ACL adresáře s názvem my-directory. Řetězec user::rwx,group::r-x,other::rw- dává vlastnícího uživatele oprávnění ke čtení, zápisu a spouštění, dává vlastnící skupině oprávnění jen ke čtení a spouštění a dává všem ostatním oprávnění ke čtení a zápisu.

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

}

Můžete také získat a nastavit seznam ACL kořenového adresáře kontejneru. Kořenový adresář získáte předáním prázdného řetězce ("") do metody DataLakeFileSystemClient.GetDirectoryClient .

Nastavení seznamu ACL souboru

Získejte seznam řízení přístupu (ACL) souboru voláním Metody DataLakeFileClient.GetAccessControlAsync a nastavte seznam ACL voláním Metody DataLakeFileClient.SetAccessControlList .

Tento příklad získá a nastaví seznam ACL souboru s názvem my-file.txt. Řetězec user::rwx,group::r-x,other::rw- dává vlastnícího uživatele oprávnění ke čtení, zápisu a spouštění, dává vlastnící skupině oprávnění jen ke čtení a spouštění a dává všem ostatním oprávnění ke čtení a zápisu.

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);
}

Rekurzivní nastavení seznamů ACL

Nastavte seznamy ACL rekurzivně voláním Metody DataLakeDirectoryClient.SetAccessControlRecursiveAsync . Předejte tuto metodu Seznam PathAccessControlItem. Každá PathAccessControlItem definuje položku seznamu ACL.

Pokud chcete nastavit výchozí položku seznamu ACL, můžete nastavit PathAccessControlItem.DefaultScope vlastnost PathAccessControlItem PathAccessControlItem na true.

Tento příklad nastaví seznam ACL adresáře s názvem my-parent-directory. Tato metoda přijímá logický parametr s názvem isDefaultScope , který určuje, zda se má nastavit výchozí seznam ACL. Tento parametr se používá v konstruktoru PathAccessControlItem. Položky seznamu ACL poskytují vlastnímu uživateli oprávnění ke čtení, zápisu a provádění, poskytují vlastnící skupině oprávnění jen pro čtení a spouštění a dává všem ostatním přístup. Poslední položka seznamu ACL v tomto příkladu poskytuje konkrétnímu uživateli s ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx objektu oprávnění ke čtení a spouštění.

    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);
}

Aktualizace seznamů ACL

Při aktualizaci seznamu ACL upravíte seznam ACL místo nahrazení seznamu ACL. Můžete například přidat nový objekt zabezpečení do seznamu ACL, aniž by to ovlivnilo jiné objekty zabezpečení uvedené v seznamu ACL. Pokud chcete seznam ACL nahradit místo aktualizace, přečtěte si část Nastavení seznamů ACL tohoto článku.

V této části se dozvíte, jak:

  • Aktualizace seznamu ACL
  • Rekurzivní aktualizace seznamů ACL

Aktualizace seznamu ACL

Nejprve získejte seznam ACL adresáře voláním Metody DataLakeDirectoryClient.GetAccessControlAsync . Zkopírujte seznam položek seznamu ACL do nového seznamu PathAccessControl objektů. Potom vyhledejte položku, kterou chcete aktualizovat, a nahraďte ji v seznamu. Nastavte seznam ACL voláním Metody DataLakeDirectoryClient.SetAccessControlList .

Tento příklad aktualizuje kořenový seznam ACL kontejneru nahrazením položky seznamu ACL pro všechny ostatní uživatele.

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);
    }

   }

Rekurzivní aktualizace seznamů ACL

Chcete-li aktualizovat seznam ACL rekurzivně, vytvořte nový objekt ACL s položkou seznamu ACL, kterou chcete aktualizovat, a pak tento objekt použijte v operaci seznamu ACL aktualizace. Nezískáte stávající seznam ACL, stačí zadat položky seznamu ACL, které se mají aktualizovat.

Aktualizujte seznam ACL rekurzivně voláním metody DataLakeDirectoryClient.UpdateAccessControlRecursiveAsync . Předejte tuto metodu Seznam PathAccessControlItem. Každá PathAccessControlItem definuje položku seznamu ACL.

Pokud chcete aktualizovat výchozí položku seznamu ACL, můžete nastavit PathAccessControlItem.DefaultScope vlastnost PathAccessControlItem na true.

Tento příklad aktualizuje položku seznamu ACL oprávněním k zápisu. Tato metoda přijímá logický parametr s názvem isDefaultScope , který určuje, zda se má aktualizovat výchozí seznam ACL. Tento parametr se používá v konstruktoru 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);

}

Odebrání položek seznamu ACL

Můžete odebrat jednu nebo více položek seznamu ACL. V této části se dozvíte, jak:

  • Odebrání položky seznamu ACL
  • Rekurzivní odebrání položek seznamu ACL

Odebrání položky seznamu ACL

Nejprve získejte seznam ACL adresáře voláním Metody DataLakeDirectoryClient.GetAccessControlAsync . Zkopírujte seznam položek seznamu ACL do nového seznamu PathAccessControl objektů. Potom vyhledejte položku, kterou chcete odebrat, a zavolejte metodu Remove kolekce. Nastavte aktualizovaný seznam ACL voláním Metody DataLakeDirectoryClient.SetAccessControlList .

Tento příklad aktualizuje kořenový seznam ACL kontejneru nahrazením položky seznamu ACL pro všechny ostatní uživatele.

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);
    }

}

Rekurzivní odebrání položek seznamu ACL

Chcete-li odebrat položky seznamu ACL rekurzivně, vytvořte nový objekt seznamu ACL pro položku seznamu ACL, který se má odebrat, a pak tento objekt použijte v operaci odebrání seznamu ACL. Nezískáte stávající seznam ACL, stačí zadat položky seznamu ACL, které se mají odebrat.

Odeberte položky seznamu ACL voláním Metody DataLakeDirectoryClient.RemoveAccessControlRecursiveAsync . Předejte tuto metodu Seznam PathAccessControlItem. Každá PathAccessControlItem definuje položku seznamu ACL.

Pokud chcete odebrat výchozí položku seznamu ACL, můžete nastavit PathAccessControlItem.DefaultScope vlastnost PathAccessControlItem PathAccessControlItem na true.

Tento příklad odebere položku seznamu ACL z seznamu ACL adresáře s názvem my-parent-directory. Tato metoda přijímá logický parametr s názvem isDefaultScope , který určuje, zda má být položka odebrána z výchozího seznamu ACL. Tento parametr se používá v konstruktoru 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);

}

Zotavení po selháních

Při rekurzivní úpravě seznamů ACL může dojít k chybám modulu runtime nebo oprávnění. V případě chyb za běhu restartujte proces od začátku. K chybám oprávnění může dojít v případě, že objekt zabezpečení nemá dostatečná oprávnění k úpravě seznamu ACL adresáře nebo souboru, který je v hierarchii adresářů, který se upravuje. Vyřešte problém s oprávněním a pak se rozhodnete proces obnovit z bodu selhání pomocí tokenu pokračování nebo ho restartovat od začátku. Pokud chcete restartovat od začátku, nemusíte token pokračování používat. Položky seznamu ACL můžete znovu použít bez negativního dopadu.

Tento příklad vrátí token pokračování v případě selhání. Aplikace může tuto ukázku metody volat znovu po vyřešení chyby a předat token pokračování. Pokud se tato ukázková metoda volá poprvé, aplikace může předat hodnotu null parametru tokenu pokračování.

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;
    }

}

Pokud chcete, aby proces dokončil nepřerušený podle chyb oprávnění, můžete to zadat.

Chcete-li zajistit, aby proces byl dokončen bez přerušení, předejte AccessControlChangedOptions objektu a nastavte ContinueOnFailure vlastnost tohoto objektu na true.

Tento příklad nastaví položky seznamu ACL rekurzivně. Pokud tento kód narazí na chybu oprávnění, zaznamená toto selhání a pokračuje v provádění. V tomto příkladu se vypíše počet selhání do konzoly.

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());
}

Osvědčené postupy

Tato část obsahuje některé pokyny pro osvědčené postupy pro nastavení seznamů ACL rekurzivně.

Zpracování chyb za běhu

K chybě za běhu může dojít z mnoha důvodů (například kvůli výpadku nebo problému s připojením klienta). Pokud dojde k chybě za běhu, restartujte rekurzivní proces seznamu ACL. Seznamy ACL je možné znovu použít u položek, aniž by to způsobilo negativní dopad.

Zpracování chyb oprávnění (403)

Pokud při spuštění rekurzivního procesu seznamu ACL dojde k výjimce řízení přístupu, nemusí mít instanční objekt zabezpečení AD dostatečná oprávnění k použití seznamu ACL pro jednu nebo více podřízených položek v hierarchii adresářů. Pokud dojde k chybě oprávnění, proces se zastaví a poskytne se token pro pokračování. Opravte problém s oprávněním a pak pomocí tokenu pro pokračování zpracujte zbývající datovou sadu. Adresáře a soubory, které už byly úspěšně zpracovány, se nebudou muset znovu zpracovat. Můžete také zvolit restartování rekurzivního procesu seznamu ACL. Seznamy ACL je možné znovu použít u položek, aniž by to způsobilo negativní dopad.

Přihlašovací údaje

Doporučujeme zřídit objekt zabezpečení Microsoft Entra, který má přiřazenou roli Vlastník dat objektů blob služby Storage v oboru cílového účtu úložiště nebo kontejneru.

Výkon

Pokud chcete snížit latenci, doporučujeme spustit rekurzivní proces seznamu ACL ve virtuálním počítači Azure, který se nachází ve stejné oblasti jako váš účet úložiště.

Omezení seznamu ACL

Maximální počet seznamů ACL, které můžete použít pro adresář nebo soubor, je 32 přístupových seznamů ACL a 32 výchozích seznamů ACL. Další informace najdete v tématu Řízení přístupu ve službě Azure Data Lake Storage Gen2.

Viz také