Udostępnij za pomocą

Zarządzanie listami ACL w usłudze Azure Data Lake Storage przy użyciu języka Python

W tym artykule pokazano, jak używać języka Python 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 (Python Package Index) | Przykłady | Rekursywne przykłady ACL | Dokumentacja 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ć.
  • Python 3.8+
  • Wersja platformy Azure CLI 2.6.0 lub nowsza.
  • 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 rekurencyjnie ustawić listy ACL, obejmuje to wszystkie elementy podrzędne w kontenerze docelowym lub katalogu.
    • Klucz konta przechowywania.

konfigurowanie projektu

Ta sekcja przeprowadzi Cię przez proces przygotowywania projektu do pracy z biblioteką klienta usługi Azure Data Lake Storage dla języka Python.

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

pip install azure-storage-file-datalake azure-identity

Następnie otwórz plik kodu i dodaj niezbędne instrukcje importu. W tym przykładzie dodamy następujący kod do naszego pliku .py :

from azure.identity import DefaultAzureCredential
from azure.storage.filedatalake import DataLakeServiceClient

Nawiązywanie połączenia z kontem

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

Możesz użyć biblioteki klienta tożsamości platformy Azure dla języka Python 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 opartych na rolach (Azure RBAC) platformy Azure do głównego obiektu zabezpieczeń:

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

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

def get_service_client_token_credential(self, account_name) -> DataLakeServiceClient:
    account_url = f"https://{account_name}.dfs.core.windows.net"
    token_credential = DefaultAzureCredential()

    service_client = DataLakeServiceClient(account_url, credential=token_credential)

    return service_client

Aby dowiedzieć się więcej na temat używania wartości DefaultAzureCredential do autoryzowania dostępu do danych, zobacz Omówienie: Uwierzytelnianie aplikacji języka Python na platformie Azure przy użyciu zestawu Azure SDK.

Ustaw ACL

Kiedy ustawisz listę ACL, zastępujesz całą listę ACL, łącznie 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.

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

  • Ustaw listę ACL katalogu
  • Ustaw ACL pliku

Ustaw listę ACL katalogu

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

Ten przykład pobiera i ustawia listę kontroli dostępu (ACL) katalogu o nazwie my-directory. Ciąg rwxr-xrw- daje właścicielowi uprawnienia do odczytu, zapisu i wykonywania, nadaje grupie właściciela tylko uprawnienia do odczytu i wykonywania oraz nadaje wszystkim innym uprawnienia do odczytu i zapisu.

def manage_directory_permissions():
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-file-system")

        directory_client = file_system_client.get_directory_client("my-directory")
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])
        
        new_dir_permissions = "rwxr-xrw-"
        
        directory_client.set_access_control(permissions=new_dir_permissions)
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])
    
    except Exception as e:
     print(e)

Możesz również pobrać i ustawić listę ACL katalogu głównego kontenera. Aby uzyskać katalog główny, wywołaj metodę FileSystemClient._get_root_directory_client .

Ustaw ACL pliku

Pobierz listę kontroli dostępu (ACL) pliku, wywołując metodę DataLakeFileClient.get_access_control i ustawiając listę ACL przez wywołanie metody DataLakeFileClient.set_access_control.

Ten przykład pokazuje, jak pobierać i ustawiać listę ACL (lista kontroli dostępu) pliku o nazwie my-file.txt. Ciąg rwxr-xrw- daje właścicielowi uprawnienia do odczytu, zapisu i wykonywania, nadaje grupie właściciela tylko uprawnienia do odczytu i wykonywania oraz nadaje wszystkim innym uprawnienia do odczytu i zapisu.

def manage_file_permissions():
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-file-system")

        directory_client = file_system_client.get_directory_client("my-directory")
        
        file_client = directory_client.get_file_client("uploaded-file.txt")

        acl_props = file_client.get_access_control()
        
        print(acl_props['permissions'])
        
        new_file_permissions = "rwxr-xrw-"
        
        file_client.set_access_control(permissions=new_file_permissions)
        
        acl_props = file_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

Rekursywne ustawianie list kontroli dostępu

Kiedy ustawisz listę ACL, zastępujesz całą listę ACL, łącznie 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ę kontroli dostępu zamiast jej zastąpić, zobacz sekcję Update ACLs recursively tego artykułu.

Ustaw listy ACL rekursywnie, wywołując metodę DataLakeDirectoryClient.set_access_control_recursive .

Jeśli chcesz ustawić domyślny wpis ACL, dodaj ciąg default: na początku każdego wpisu ACL.

W tym przykładzie ustawiono listę kontroli dostępu (ACL) katalogu o nazwie my-parent-directory.

Ta metoda akceptuje parametr logiczny o nazwie is_default_scope , który określa, czy ustawić domyślną listę ACL. Jeśli ten parametr to True, lista wpisów listy ACL jest poprzedzona ciągiem default:. Wpisy w tym przykładzie przyznają następujące uprawnienia: uprawnienia do odczytu, zapisu i wykonywania dla użytkownika będącego właścicielem, uprawnienia do odczytu i wykonywania dla grupy właścicielskiej oraz uprawnienia do odczytu dla wszystkich pozostałych. Ostatni wpis na liście ACL w tym przykładzie przyznaje określonemu użytkownikowi uprawnienia do odczytu dla identyfikatora obiektu xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

def set_permission_recursively(is_default_scope):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")

        acl = 'user::rwx,group::r-x,other::r--,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'   

        if is_default_scope:
           acl = 'default:user::rwx,default:group::r-x,default:other::r--,default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        directory_client.set_access_control_recursive(acl=acl)
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

Aby zobaczyć przykład, który przetwarza listy ACL cyklicznie w partiach, określając rozmiar partii, zobacz przykład języka Python.

Rekursywne aktualizowanie listy kontroli dostępu (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.

Aby zaktualizować listę ACL rekursywnie, utwórz nowy obiekt 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.update_access_control_recursive . Jeśli chcesz zaktualizować domyślny wpis listy ACL, dodaj ciąg default: na początku każdego ciągu wpisu listy ACL.

W tym przykładzie zaktualizowano wpis ACL z uprawnieniami do zapisu.

W tym przykładzie ustawiono listę kontroli dostępu (ACL) katalogu o nazwie my-parent-directory. Ta metoda akceptuje parametr logiczny o nazwie is_default_scope , który określa, czy zaktualizować domyślną listę ACL. jeśli ten parametr to True, zaktualizowany wpis listy ACL jest poprzedzony ciągiem default:.

def update_permission_recursively(is_default_scope):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx'   

        if is_default_scope:
           acl = 'default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx'

        directory_client.update_access_control_recursive(acl=acl)

        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

Aby zobaczyć przykład, który przetwarza listy ACL cyklicznie w partiach, określając rozmiar partii, zobacz przykład języka Python.

Usuń wpisy ACL rekursyjnie

Można usunąć jeden lub więcej wpisów listy ACL. Aby usunąć wpisy ACL rekursywnie, utwórz nowy obiekt ACL dla wpisu ACL do usunięcia, a następnie użyj tego obiektu w operacji usuwania ACL. Nie pobieraj istniejącej listy ACL, wystarczy podać wpisy listy ACL do usunięcia.

Usuń wpisy ACL, wywołując metodę DataLakeDirectoryClient.remove_access_control_recursive. Jeśli chcesz usunąć domyślny wpis listy ACL, dodaj ciąg default: na początku ciągu wpisu listy ACL.

W tym przykładzie usunięto wpis z listy ACL katalogu o nazwie my-parent-directory. Ta metoda akceptuje parametr logiczny o nazwie is_default_scope , który określa, czy usunąć wpis z domyślnej listy ACL. Jeśli ten parametr to True, zaktualizowany wpis listy ACL jest poprzedzony ciągiem default:.

def remove_permission_recursively(is_default_scope):

    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")

        acl = 'user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

        if is_default_scope:
           acl = 'default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

        directory_client.remove_access_control_recursive(acl=acl)

    except Exception as e:
     print(e)

Aby zobaczyć przykład, który przetwarza listy ACL cyklicznie w partiach, określając rozmiar partii, zobacz przykład języka Python.

Odzyskiwanie po awariach

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 element zabezpieczeń nie ma wystarczających uprawnień do modyfikowania ACL katalogu lub pliku, który znajduje się w hierarchii katalogów modyfikowanych. 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 żadnego 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ść None parametru tokenu kontynuacji.

def resume_set_acl_recursive(continuation_token):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user::rwx,group::rwx,other::rwx,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        acl_change_result = directory_client.set_access_control_recursive(acl=acl, continuation=continuation_token)

        continuation_token = acl_change_result.continuation

        return continuation_token
        
    except Exception as e:
     print(e) 
     return continuation_token

Aby zobaczyć przykład, który przetwarza listy ACL cyklicznie w partiach, określając rozmiar partii, zobacz przykład języka Python.

Jeśli chcesz, aby proces został ukończony bez przerywania przez błędy uprawnień, możesz to zdefiniować.

Aby upewnić się, że proces zakończy się nieprzerwanie, nie przekazuj tokenu kontynuacji do metody DataLakeDirectoryClient.set_access_control_recursive .

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 drukuje się liczbę niepowodzeń na konsolę.

def continue_on_failure():
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user::rwx,group::rwx,other::rwx,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        acl_change_result = directory_client.set_access_control_recursive(acl=acl)

        print("Summary: {} directories and {} files were updated successfully, {} failures were counted."
          .format(acl_change_result.counters.directories_successful, acl_change_result.counters.files_successful,
                  acl_change_result.counters.failure_count))
        
    except Exception as e:
     print(e)

Aby zobaczyć przykład, który przetwarza listy ACL cyklicznie w partiach, określając rozmiar partii, zobacz przykład języka Python.

Najlepsze rozwiązania

Ta sekcja zawiera wytyczne najlepszych praktyk dotyczące rekursywnego 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 wykonania, uruchom ponownie rekurencyjny proces ACL. Zasady 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 wykonywania rekursywnego procesu ACL, podmiot zabezpieczeń AD może nie mieć wystarczających uprawnień do zastosowania 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ż wybrać ponowne uruchomienie rekurencyjnego procesu ACL. Zasady ACL można ponownie zastosować do elementów bez negatywnego wpływu.

Poświadczenia

Zalecamy utworzenie podmiotu zabezpieczeń Microsoft Entra, 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 rekursywnego procesu ACL w maszynie wirtualnej Azure, która znajduje 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