Udostępnij za pomocą

Zarządzanie listami ACL w usłudze Azure Data Lake Storage przy użyciu platformy .NET

W tym artykule pokazano, jak używać platformy .NET do pobierania, ustawiania i aktualizowania list kontroli dostępu katalogów i plików.

Dziedziczenie listy ACL jest już dostępne dla nowych elementów podrzędnych utworzonych w katalogu nadrzędnym. Można jednak również rekurencyjnie dodawać, aktualizować i usuwać listy kontroli dostępu (ACL) w istniejących elementach podrzędnych katalogu nadrzędnego, bez konieczności wprowadzania tych zmian osobno dla każdego elementu podrzędnego.

Pakiet (NuGet) | Przykłady | Dokumentacja interfejsu API | Mapowanie Gen1 do Gen2 | Prześlij opinię

Wymagania wstępne

  • Subskrypcja platformy Azure — utwórz bezpłatnie.
  • Konto usługi Azure Storage z włączoną hierarchiczną przestrzenią nazw (HNS). Postępuj zgodnie z tymi instrukcjami , aby je utworzyć.
  • Wersja Azure CLI 2.6.0 lub wyższa.
  • Jedno z następujących uprawnień zabezpieczeń:
    • Provisionowana jednostka zabezpieczeń Microsoft Entra ID, której przypisano rolę właściciela danych obiektu blob usługi Storage, z zakresem określonym na kontener docelowy, konto magazynu, nadrzędną grupę zasobów lub subskrypcję.
    • Użytkownik będący właścicielem docelowego kontenera lub katalogu, do którego planujesz zastosować ustawienia ACL. Aby rekursywnie ustawić uprawnienia ACL, obejmij wszystkie elementy podrzędne w kontenerze docelowym lub katalogu.
    • Klucz konta przechowywania.

konfigurowanie projektu

W tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Storage Data Lake.

Instalowanie pakietów

Z katalogu projektu zainstaluj pakiety dla bibliotek klienckich usługi Azure Storage Data Lake i Azure Identity przy użyciu dotnet add package polecenia . Pakiet Azure.Identity jest wymagany w przypadku połączeń bez hasła z usługami platformy Azure.

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

Dodaj using dyrektywy

Dodaj te using dyrektywy na początku pliku kodu:

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;

Nawiązywanie połączenia z kontem

Aby uruchomić przykłady kodu w tym artykule, należy utworzyć wystąpienie DataLakeServiceClient reprezentujące konto magazynowania. Obiekt klienta można autoryzować przy użyciu poświadczeń Microsoft Entra ID lub klucza konta.

Bibliotekę klienta tożsamości platformy Azure dla platformy .NET można użyć do uwierzytelniania aplikacji za pomocą identyfikatora Entra firmy Microsoft.

Uwaga

Jeśli używasz Microsoft Entra ID do autoryzacji dostępu, upewnij się, że jednostka zabezpieczeń ma przypisaną rolę Właściciela danych usługi Storage Blob. Aby dowiedzieć się więcej na temat sposobu stosowania uprawnień listy ACL i skutków ich zmiany, zobacz Model kontroli dostępu w usłudze Azure Data Lake Storage.

Najpierw przypisz jedną z następujących ról kontroli dostępu platformy Azure (Azure RBAC) dla podmiotu zabezpieczeń.

Rola Możliwość ustawiania ACL
Właściciel danych obiektu blob Storage Wszystkie katalogi i pliki na koncie.
Współautor danych w usłudze Blob Storage Tylko katalogi i pliki należące do podmiotu zabezpieczeń.

Następnie utwórz wystąpienie klasy DataLakeServiceClient i przekaż jako argument nowe wystąpienie klasy DefaultAzureCredential.

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

Aby dowiedzieć się więcej na temat używania wartości DefaultAzureCredential do autoryzowania dostępu do danych, zobacz Jak uwierzytelniać aplikacje platformy .NET za pomocą usług Azure.

Ustaw ACL

Kiedy ustawisz listę ACL, zastępujesz całą listę ACL wraz ze wszystkimi jej wpisami. Jeśli chcesz zmienić poziom uprawnień podmiotu zabezpieczeń lub dodać nowego podmiotu zabezpieczeń do listy ACL bez wpływu na inne istniejące wpisy, należy zaktualizować listę ACL. Aby zaktualizować listę ACL zamiast jej zastąpić, zobacz sekcję Aktualizowanie list ACL w tym artykule.

Jeśli zdecydujesz się ustawić listę ACL, musisz dodać wpis dla użytkownika będącego właścicielem, wpis dla grupy będącej właścicielem i wpis dla wszystkich innych użytkowników. Aby dowiedzieć się więcej na temat użytkownika, grupy właścicieli i wszystkich innych użytkowników, zobacz Użytkownicy i tożsamości.

W tej sekcji pokazano, jak wykonać następujące działania:

  • Ustaw ACL katalogu
  • Ustawianie listy ACL pliku
  • Rekurencyjne ustawianie list kontroli dostępu

Ustaw ACL katalogu

Pobierz listę kontroli dostępu (ACL) katalogu, wywołując metodę DataLakeDirectoryClient.GetAccessControlAsync i ustawiając listę ACL, wywołując metodę DataLakeDirectoryClient.SetAccessControlList.

Ten przykład pobiera i ustawia uprawnienia ACL katalogu o nazwie my-directory. Ciąg user::rwx,group::r-x,other::rw- daje właścicielowi uprawnienia do odczytu, zapisu i wykonywania, nadaje grupie właściciela uprawnienia tylko do odczytu i wykonywania oraz nadaje wszystkim innym uprawnienia do odczytu i zapisu.

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

}

Można również pobrać i ustawić listę ACL katalogu głównego kontenera. Aby uzyskać katalog główny, przekaż pusty ciąg ("") do metody DataLakeFileSystemClient.GetDirectoryClient .

Ustawianie listy ACL pliku

Pobierz listę kontroli dostępu (ACL) pliku, wywołując metodę DataLakeFileClient.GetAccessControlAsync i ustawiając listę ACL, wywołując metodę DataLakeFileClient.SetAccessControlList .

Ten przykład pobiera i ustawia ACL pliku o nazwie my-file.txt. Ciąg user::rwx,group::r-x,other::rw- daje właścicielowi uprawnienia do odczytu, zapisu i wykonywania, nadaje grupie właściciela uprawnienia tylko do odczytu i wykonywania oraz nadaje wszystkim innym uprawnienia do odczytu i zapisu.

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

Rekurencyjne ustawianie list kontroli dostępu

Ustaw listy ACL rekursywnie, wywołując metodę DataLakeDirectoryClient.SetAccessControlRecursiveAsync . Przekaż tej metodzie List elementów typu PathAccessControlItem. Każdy element PathAccessControlItem definiuje wpis listy ACL.

Jeśli chcesz ustawić domyślny wpis listy ACL, możesz ustawić właściwość PathAccessControlItem.DefaultScope właściwości PathAccessControlItem na true.

W tym przykładzie ustawiana jest lista ACL katalogu o nazwie my-parent-directory. Ta metoda akceptuje parametr logiczny o nazwie isDefaultScope, który określa, czy ustawić domyślną listę kontroli dostępu (ACL). Ten parametr jest używany w konstruktorze PathAccessControlItem. Wpisy listy ACL dają właścicielowi uprawnienia do odczytu, zapisu i wykonywania, zapewniają grupie uprawnienia tylko do odczytu i wykonywania, a wszystkim innym nie zapewniają dostępu. Ostatni wpis listy ACL w tym przykładzie nadaje określonemu użytkownikowi z identyfikatorem obiektu xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx uprawnienia do odczytu i wykonywania.

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

Aktualizacja ACL

Podczas aktualizowania listy ACL należy ją zmodyfikować, a nie zastępować. Można na przykład dodać nowego podmiotu zabezpieczeń do listy ACL bez wpływu na inne podmioty zabezpieczeń wymienione na liście ACL. Aby zastąpić listę ACL zamiast ją zaktualizować, zobacz sekcję Ustawianie list ACL w tym artykule.

W tej sekcji pokazano, jak wykonać następujące działania:

  • Zaktualizować listę ACL
  • Rekurencyjne aktualizowanie ACL

Zaktualizować listę ACL

Najpierw pobierz listę ACL katalogu, wywołując metodę DataLakeDirectoryClient.GetAccessControlAsync . Skopiuj wpisy ACL do nowej listy obiektów PathAccessControl. Następnie znajdź wpis, który chcesz zaktualizować i zastąp go na liście. Ustaw listę ACL, wywołując metodę DataLakeDirectoryClient.SetAccessControlList .

Ten przykład aktualizuje główną listę ACL kontenera, zastępując wpis ACL dla wszystkich innych użytkowników.

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

   }

Rekurencyjne aktualizowanie ACL

Aby zaktualizować ACL rekursywnie, utwórz nowy obiekt ACL z wpisem, który chcesz zaktualizować, a następnie użyj tego obiektu w operacji aktualizacji ACL. Nie pobieraj istniejącej listy ACL, po prostu podaj wpisy listy ACL do zaktualizowania.

Zaktualizuj listę ACL rekursywnie, wywołując metodę DataLakeDirectoryClient.UpdateAccessControlRecursiveAsync . Przekaż tej metodzie List elementów typu PathAccessControlItem. Każdy element PathAccessControlItem definiuje wpis listy ACL.

Jeśli chcesz zaktualizować domyślny wpis listy ACL, możesz ustawić właściwość DefaultScope obiektu PathAccessControlItem na true.

W tym przykładzie aktualizuje się wpis listy ACL, dodając uprawnienia do zapisu. Ta metoda akceptuje parametr logiczny o nazwie isDefaultScope , który określa, czy zaktualizować domyślną listę ACL. Ten parametr jest używany w konstruktorze 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);

}

Usuń wpisy ACL

Można usunąć jeden lub więcej wpisów listy ACL. W tej sekcji pokazano, jak wykonać następujące działania:

  • Usuń wpis ACL
  • Rekursywne usuwanie wpisów listy ACL

Usuń wpis ACL

Najpierw pobierz listę ACL katalogu, wywołując metodę DataLakeDirectoryClient.GetAccessControlAsync . Skopiuj wpisy ACL do nowej listy obiektów PathAccessControl. Następnie znajdź wpis, który chcesz usunąć, i wywołaj metodę Remove kolekcji. Ustaw zaktualizowaną listę ACL, wywołując metodę DataLakeDirectoryClient.SetAccessControlList .

Ten przykład aktualizuje główną listę ACL kontenera, zastępując wpis ACL dla wszystkich innych użytkowników.

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

}

Rekursywne usuwanie wpisów listy ACL

Aby usunąć wpisy ACL rekursywnie, utwórz nowy obiekt ACL dla wpisu do usunięcia, a następnie użyj tego obiektu w operacji usuwania wpisu ACL. Nie pobieraj istniejącej listy ACL, po prostu podaj wpisy listy ACL, które mają zostać usunięte.

Usuń wpisy ACL, wywołując metodę DataLakeDirectoryClient.RemoveAccessControlRecursiveAsync. Przekaż tej metodzie List elementów typu PathAccessControlItem. Każdy element PathAccessControlItem definiuje wpis listy ACL.

Jeśli chcesz usunąć domyślny wpis listy ACL, możesz ustawić właściwość PathAccessControlItem.DefaultScope obiektu PathAccessControlItem na true.

W tym przykładzie usunięto wpis ACL z listy ACL katalogu o nazwie my-parent-directory. Ta metoda akceptuje parametr logiczny o nazwie isDefaultScope , który określa, czy usunąć wpis z domyślnej listy ACL. Ten parametr jest używany w konstruktorze 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);

}

Odzyskiwanie po awariach

Podczas cyklicznego modyfikowania list ACL mogą wystąpić błędy środowiska uruchomieniowego lub uprawnień. W przypadku błędów środowiska uruchomieniowego uruchom ponownie proces od początku. Błędy uprawnień mogą wystąpić, jeśli podmiot zabezpieczeń nie ma wystarczających uprawnień do modyfikowania listy kontroli dostępu (ACL) katalogu lub pliku, którego hierarchia jest zmieniana. Rozwiąż problem z uprawnieniami, a następnie wybierz, aby wznowić proces od punktu awarii przy użyciu tokenu kontynuacji lub uruchomić ponownie proces od początku. Jeśli wolisz ponownie uruchomić od początku, nie musisz używać tokenu kontynuacji. Możesz ponownie zastosować wpisy listy kontroli dostępu (ACL) bez negatywnego wpływu.

Ten przykład zwraca token kontynuacji w przypadku awarii. Aplikacja może wywołać tę przykładową metodę ponownie po usunięciu błędu i przekazać token kontynuacji. Jeśli ta przykładowa metoda jest wywoływana po raz pierwszy, aplikacja może przekazać wartość null parametru tokenu kontynuacji.

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

}

Jeśli chcesz, aby proces zakończył się bez przerywania przez błędy uprawnień, możesz to ustawić.

Aby upewnić się, że proces zakończy się nieprzerwanie, przekaż obiekt AccessControlChangedOptions

W tym przykładzie rekursywnie ustawiane są wpisy listy ACL. Jeśli ten kod napotka błąd uprawnień, rejestruje ten błąd i kontynuuje wykonywanie. W tym przykładzie liczba niepowodzeń jest drukowana na konsolę.

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

Najlepsze rozwiązania

Ta sekcja zawiera wskazówki dotyczące najlepszych praktyk dotyczących rekursywnego ustawiania list kontroli dostępu (ACL).

Obsługa błędów środowiska uruchomieniowego

Błąd środowiska uruchomieniowego może wystąpić z wielu powodów (na przykład: awaria lub problem z łącznością klienta). Jeśli wystąpi błąd środowiska uruchomieniowego, uruchom ponownie rekursywny proces ACL. ACL można ponownie zastosować do elementów bez negatywnego skutku.

Obsługa błędów uprawnień (403)

Jeśli podczas uruchamiania rekurencyjnego procesu ACL wystąpi wyjątek kontroli dostępu, Twój podmiot zabezpieczeń AD może nie mieć wystarczających uprawnień do zastosowania ACL do jednego lub więcej elementów podrzędnych w hierarchii katalogów. Po wystąpieniu błędu uprawnień proces zostanie zatrzymany i zostanie udostępniony token kontynuacji. Rozwiąż problem z uprawnieniami, a następnie użyj tokenu kontynuacji, aby przetworzyć pozostały zestaw danych. Katalogi i pliki, które zostały już pomyślnie przetworzone, nie będą musiały zostać ponownie przetworzone. Możesz również zdecydować się na ponowne uruchomienie rekursyjnego procesu ACL. ACL można ponownie zastosować do elementów bez negatywnego skutku.

Poświadczenia

Zalecamy aprowizację podmiotu zabezpieczającego w usłudze Microsoft Entra, któremu przypisano rolę Właściciela danych obiektu blob w zakresie docelowego konta magazynu lub kontenera.

Wydajność

Aby zmniejszyć opóźnienia, zalecamy uruchomienie rekursywnego procesu ACL na maszynie wirtualnej platformy Azure znajdującej się w tym samym regionie co konto magazynu.

Limity listy ACL

Maksymalna liczba list ACL, które można zastosować do katalogu lub pliku, to 32 listy ACL dostępu i 32 domyślne listy ACL. Aby uzyskać więcej informacji, zobacz Kontrola dostępu w usłudze Azure Data Lake Storage Gen2.

Zobacz też

  • Last updated on