Udostępnij za pośrednictwem

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

  • Artykuł

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ż dodawać, aktualizować i usuwać listy ACL cyklicznie w istniejących elementach podrzędnych katalogu nadrzędnego bez konieczności wprowadzania tych zmian indywidualnie dla każdego elementu podrzędnego.

Package (NuGet)Samples | API reference Gen1 to Gen2 mapping Give Feedback (Dokumentacja interfejsu API pakietów (NuGet) | Dokumentacja | interfejsu API gen1 do mapowania | gen2

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 interfejsu wiersza polecenia platformy Azure lub nowsza 2.6.0 .
  • Jedno z następujących uprawnień zabezpieczeń:
    • Aprowizowana jednostka zabezpieczeń identyfikatora entra firmy Microsoft, która została przypisana do roli właściciela danych obiektu blob usługi Storage, w zakresie kontenera docelowego, konta magazynu, nadrzędnej grupy zasobów lub subskrypcji.
    • Właścicielem kontenera docelowego lub katalogu, do którego planujesz zastosować ustawienia listy ACL. Aby ustawić listy ACL cyklicznie, obejmuje to wszystkie elementy podrzędne w kontenerze docelowym lub katalogu.
    • Klucz konta magazynu.

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

Dodawanie using dyrektyw

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 magazynu. Obiekt klienta można autoryzować przy użyciu poświadczeń identyfikatora entra firmy Microsoft 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 identyfikatora Entra firmy Microsoft do autoryzowania dostępu, upewnij się, że podmiot zabezpieczeń ma przypisaną rolę Właściciela danych obiektu blob usługi Storage. 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 na podstawie ról (RBAC) platformy Azure do podmiotu zabezpieczeń:

Rola Możliwość ustawiania listy ACL
Właściciel danych obiektu blob usługi 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ż 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 platformy Azure.

Ustawianie list ACL

Po ustawieniu listy ACL należy zastąpić całą listę ACL wraz ze wszystkimi jego 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 właścicieli 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:

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

Ustawianie listy 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 listę 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 użytkownika, nadaje grupie właściciel tylko uprawnienia do odczytu i wykonywania oraz nadaje wszystkim innym uprawnienie 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);

}

Listę ACL katalogu głównego kontenera można również pobrać i ustawić. 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 listę 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 użytkownika, nadaje grupie właściciel tylko uprawnienia do odczytu i wykonywania oraz nadaje wszystkim innym uprawnienie 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);
}

Cykliczne ustawianie list kontroli dostępu

Ustaw listy ACL rekursywnie, wywołując metodę DataLakeDirectoryClient.SetAccessControlRecursiveAsync . Przekaż tę metodę listą 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 ustawiono listę ACL katalogu o nazwie my-parent-directory. Ta metoda akceptuje parametr logiczny o nazwie isDefaultScope , który określa, czy ustawić domyślną listę ACL. Ten parametr jest używany w konstruktorze PathAccessControlItem. Wpisy listy ACL dają właścicielowi uprawnienia do odczytu, zapisu i wykonywania, zapewniają uprawnienia tylko do odczytu i wykonywania grupy, a także zapewniają wszystkim innym użytkownikom dostęp bez dostępu. Ostatni wpis listy ACL w tym przykładzie daje określonego użytkownika z uprawnieniami do odczytu i wykonywania identyfikatora xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx obiektu.

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

Aktualizowanie list ACL

Podczas aktualizowania listy ACL należy zmodyfikować listę ACL zamiast zastąpić listę ACL. 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:

  • Aktualizowanie listy ACL
  • Rekursywne aktualizowanie list ACL

Aktualizowanie listy ACL

Najpierw pobierz listę ACL katalogu, wywołując metodę DataLakeDirectoryClient.GetAccessControlAsync . Skopiuj listę wpisów listy 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 listy 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);
    }

   }

Rekursywne aktualizowanie list ACL

Aby zaktualizować listę ACL rekursywnie, utwórz nowy obiekt listy ACL z wpisem listy ACL, który chcesz zaktualizować, a następnie użyj tego obiektu w operacji aktualizacji listy 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ż tę metodę listą pathAccessControlItem. Każdy element PathAccessControlItem definiuje wpis listy ACL.

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

W tym przykładzie zaktualizowano wpis listy ACL z uprawnieniami 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);

}

Usuwanie wpisów listy ACL

Można usunąć co najmniej jeden wpis listy ACL. W tej sekcji pokazano, jak wykonać następujące działania:

  • Usuwanie wpisu listy ACL
  • Usuwanie wpisów listy ACL rekursywnie

Usuwanie wpisu listy ACL

Najpierw pobierz listę ACL katalogu, wywołując metodę DataLakeDirectoryClient.GetAccessControlAsync . Skopiuj listę wpisów listy 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 listy 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);
    }

}

Usuwanie wpisów listy ACL rekursywnie

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

Usuń wpisy listy ACL, wywołując metodę DataLakeDirectoryClient.RemoveAccessControlRecursiveAsync . Przekaż tę metodę listą 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 właściwości PathAccessControlItem na true.

W tym przykładzie usunięto wpis listy 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 ACL katalogu lub pliku, który znajduje się w hierarchii katalogów, które są modyfikowane. 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 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 był nieprzerwany przez błędy uprawnień, możesz to określić.

Aby upewnić się, że proces zakończy się nieprzerwanie, przekaż obiekt AccessControlChangedOptions i ustaw właściwość ContinueOnFailure tego obiektu na true.

W tym przykładzie cyklicznie ustawiane są wpisy listy ACL. Jeśli ten kod napotka błąd uprawnień, rejestruje ten błąd i kontynuuje wykonywanie. W tym przykładzie jest drukowana liczba niepowodzeń w konsoli programu .

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 rozwiązań dotyczących cyklicznego ustawiania list 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 cyklicznego procesu listy ACL. Listy ACL można ponownie zastosować do elementów bez negatywnego wpływu.

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

Jeśli wystąpi wyjątek kontroli dostępu podczas uruchamiania cyklicznego procesu listy ACL, podmiot zabezpieczeń usługi AD może nie mieć wystarczających uprawnień do zastosowania listy ACL do co najmniej jednego elementu podrzędnego 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ż ponownie uruchomić cyklicznego procesu listy ACL. Listy ACL można ponownie zastosować do elementów bez negatywnego wpływu.

Referencja

Zalecamy aprowizację podmiotu zabezpieczeń firmy Microsoft, któremu przypisano rolę Właściciela danych obiektu blob usługi Storage w zakresie docelowego konta magazynu lub kontenera.

Wydajność

Aby zmniejszyć opóźnienie, zalecamy uruchomienie cyklicznego procesu listy 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ż