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

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

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

Balíček (NuGet) | Ukázky | Referenční informace k rozhraní API | Mapování Gen1 na Gen2 | Dejte zpětnou vazbu

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ý bezpečnostní objekt Microsoft Entra ID, kterému byla přiřazena role Vlastník dat objektu Blob služby Storage, vymezená na cílový kontejner, účet úložiště, nadřazenou skupinu prostředků nebo předplatné.
- Vlastník cílového kontejneru nebo adresáře, na který plánujete použít nastavení 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řidejte `using` direktivy

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.

Microsoft Entra ID (doporučeno)
Klíč úč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 bezpečnostnímu principálu přiřazena role vlastníka dat úložiště blob. 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 objektu hlavního zabezpečení jednu z následujících rolí řízení přístupu podle role (Azure RBAC):

Role	Možnost nastavení ACL
Vlastník dat úložiště Blob	Všechny adresáře a soubory v účtu.
Přispěvatel dat úložiště Blob	Pouze adresáře a soubory vlastněné zabezpečovacím principálem.

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.

Přístup k datům můžete autorizovat pomocí přístupových klíčů k účtu (sdílený klíč). Tento příklad vytvoří instanci DataLakeServiceClient , která je autorizovaná pomocí klíče účtu.

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

Upozornění

Autorizace pomocí sdíleného klíče se nedoporučuje, protože může být méně zabezpečená. Pokud chcete zajistit optimální zabezpečení, zakažte autorizaci prostřednictvím sdíleného klíče pro váš účet úložiště, jak je popsáno v části Zabránění autorizaci sdíleného klíče pro účet služby Azure Storage.

Použití přístupových klíčů a připojovací řetězec by mělo být omezené na počáteční testování konceptů aplikací nebo prototypů vývoje, které nepřistupují k produkčním nebo citlivým datům. Jinak by se při ověřování prostředků Azure měly vždy upřednostňovat třídy ověřování založené na tokenech, které jsou dostupné v sadě Azure SDK.

Microsoft doporučuje, aby klienti k autorizaci přístupu k datům ve službě Azure Storage používali buď ID Microsoft Entra, nebo sdílený přístupový podpis (SAS). Další informace najdete v tématu Autorizace operací pro přístup k datům.

Nastavení seznamů ACL

Když nastavíte ACL, nahradíte celý seznam, 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ím uživateli, vlastnící skupiny a všech ostatních uživatelích viz část Uživatelé a identity.

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

Nastavte ACL adresáře
Nastavit ACL souboru
Rekurzivní nastavení seznamů ACL

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

Nastavit 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 tomuto metodě Seznam PathAccessControlItem. Každá PathAccessControlItem definuje položku seznamu ACL.

Pokud chcete nastavit výchozí položku seznamu ACL, můžete nastavit vlastnost PathAccessControlItem.DefaultScope u 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í, vlastní skupině poskytují oprávnění jen pro čtení a provádění a všem ostatním nedávají žádný 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 ACL

Při aktualizaci ACL ji upravíte místo jejího nahrazení. 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 ACL
Rekurzivní aktualizace seznamů ACL

Aktualizace 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é ACL kontejneru tím, že nahradí položku ACL pro všechny další 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ávejte stávající seznam ACL, jen uveďte položky seznamu ACL, které se mají aktualizovat.

Aktualizujte seznam ACL rekurzivně voláním metody DataLakeDirectoryClient.UpdateAccessControlRecursiveAsync . Předejte tomuto metodě 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 řízení přístupu (ACL) s 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);

}

Odebrat položky ACL

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

Odstranit položku v seznamu ACL
Rekurzivně odeberte položky ACL

Odstranit položku v 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é ACL kontejneru tím, že nahradí položku ACL pro všechny další 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ě odeberte položky 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ávejte stávající ACL, pouze poskytněte položky ACL, které se mají odebrat.

Odeberte záznamy ACL voláním metody DataLakeDirectoryClient.RemoveAccessControlRecursiveAsync. Předejte tomuto metodě Seznam PathAccessControlItem. Každá PathAccessControlItem definuje položku seznamu ACL.

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

Tento příklad odstraní položku ACL ze 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 vrací token pokračování v případě selhání. Aplikace může tuto příklad 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 proběhl bez přerušení kvůli chybám oprávnění, můžete to nastavit.

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í. Tento příklad 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 osvědčené postupy pro rekurzivní nastavení ACL.

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 běhové chybě, restartujte rekurzivní proces seznamu přístupových práv (ACL). ACL lze znovu použít u položek, aniž by došlo k negativnímu dopadu.

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

Pokud při spuštění rekurzivního procesu ACL dojde k výjimce řízení přístupu, nemusí mít váš bezpečnostní objekt AD dostatečná oprávnění k použití ACL na 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 se také rozhodnout restartovat rekurzivní proces ACL. ACL lze znovu použít u položek, aniž by došlo k negativnímu dopadu.

Přihlašovací údaje

Doporučujeme zřídit objekt zabezpečení Microsoft Entra s rolí Vlastník dat objektů blob služby Storage přiřazenou v rámci 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é

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-04-04

Sdílet prostřednictvím

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

Požadavky

Nastavení projektu

Instalace balíčků

Přidejte using direktivy

Připojení k účtu

Nastavení seznamů ACL

Nastavte ACL adresáře

Nastavit ACL souboru

Rekurzivní nastavení seznamů ACL

Aktualizace ACL

Aktualizace ACL

Rekurzivní aktualizace seznamů ACL

Odebrat položky ACL

Odstranit položku v seznamu ACL

Rekurzivně odeberte položky ACL

Zotavení po selháních

Osvědčené postupy

Zpracování chyb za běhu

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

Přihlašovací údaje

Výkon

Omezení seznamu ACL

Viz také

Váš názor

Další materiály

Přidejte `using` direktivy