Sdílet prostřednictvím

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

  • Článek

V tomto článku se dozvíte, jak pomocí Pythonu 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.

Package (Python Package Index) | Samples | Recursive ACL samples | API reference | Gen1 to Gen2 mapping | Give Feedback

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.
  • Python 3.8 nebo novější
  • 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

Tato část vás provede přípravou projektu pro práci s klientskou knihovnou Azure Data Lake Storage pro Python.

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

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

Pak otevřete soubor kódu a přidejte potřebné příkazy importu. V tomto příkladu přidáme do souboru .py následující položky:

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

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.

K ověření aplikace pomocí Microsoft Entra ID můžete použít klientskou knihovnu identit Azure pro Python .

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.

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

Další informace o použití DefaultAzureCredential k autorizaci přístupu k datům najdete v tématu Přehled: Ověřování aplikací Pythonu v Azure pomocí sady Azure SDK.

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.

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

  • Nastavení seznamu ACL adresáře
  • Nastavení seznamu ACL souboru

Nastavení seznamu ACL adresáře

Získejte seznam řízení přístupu (ACL) adresáře voláním metody DataLakeDirectoryClient.get_access_control a nastavením seznamu ACL voláním metody DataLakeDirectoryClient.set_access_control .

Tento příklad získá a nastaví seznam ACL adresáře s názvem my-directory. Řetězec rwxr-xrw- 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.

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)

Můžete také získat a nastavit seznam ACL kořenového adresáře kontejneru. Pokud chcete získat kořenový adresář, zavolejte metodu FileSystemClient._get_root_directory_client .

Nastavení seznamu ACL souboru

Získejte seznam řízení přístupu (ACL) souboru voláním metody DataLakeFileClient.get_access_control a nastavením seznamu ACL voláním metody DataLakeFileClient.set_access_control .

Tento příklad získá a nastaví seznam ACL souboru s názvem my-file.txt. Řetězec rwxr-xrw- 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.

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)

Rekurzivní 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 seznam ACL místo nahrazení aktualizovat, přečtěte si část Aktualizovat seznamy ACL v tomto článku rekurzivně .

Nastavte seznamy ACL rekurzivně voláním metody DataLakeDirectoryClient.set_access_control_recursive .

Pokud chcete nastavit výchozí položku seznamu ACL, přidejte řetězec default: na začátek každého vstupního řetězce seznamu ACL.

Tento příklad nastaví seznam ACL adresáře s názvem my-parent-directory.

Tato metoda přijímá logický parametr s názvem is_default_scope , který určuje, zda se má nastavit výchozí seznam ACL. Pokud je Truetento parametr , seznam položek seznamu ACL jsou před řetězcem default:. Položky v tomto příkladu udělují následující oprávnění: čtení, zápis a spouštění oprávnění pro vlastnícího uživatele, čtení a spouštění oprávnění pro vlastnící skupinu a oprávnění ke čtení pro všechny ostatní. Poslední položka seznamu ACL v tomto příkladu poskytuje konkrétnímu uživateli s oprávněními ke čtení ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx objektu.

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)

Příklad, který zpracovává seznamy ACL rekurzivně v dávkách zadáním velikosti dávky, najdete v ukázce Pythonu.

Rekurzivní 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.

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.update_access_control_recursive . Pokud chcete aktualizovat výchozí položku seznamu ACL, přidejte řetězec default: na začátek každého vstupního řetězce seznamu ACL.

Tento příklad aktualizuje položku seznamu ACL oprávněním k zápisu.

Tento příklad nastaví seznam ACL adresáře s názvem my-parent-directory. Tato metoda přijímá logický parametr s názvem is_default_scope , který určuje, zda se má aktualizovat výchozí seznam ACL. pokud je Truetento parametr , je před aktualizovanou položkou seznamu ACL uveden řetězec 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)

Příklad, který zpracovává seznamy ACL rekurzivně v dávkách zadáním velikosti dávky, najdete v ukázce Pythonu.

Rekurzivní odebrání položek seznamu ACL

Můžete odebrat jednu nebo více 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. Stávající seznam ACL nezískáte, stačí zadat položky seznamu ACL, které se mají odebrat.

Odeberte položky seznamu ACL voláním metody DataLakeDirectoryClient.remove_access_control_recursive . Pokud chcete odebrat výchozí položku seznamu ACL, přidejte řetězec default: na začátek vstupního řetězce seznamu ACL.

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 is_default_scope , který určuje, zda má být položka odebrána z výchozího seznamu ACL. Pokud je Truetento parametr , je před aktualizovanou položkou seznamu ACL řetězec 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)

Příklad, který zpracovává seznamy ACL rekurzivně v dávkách zadáním velikosti dávky, najdete v ukázce Pythonu.

Zotavení po selháních

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 None parametru tokenu pokračování.

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

Příklad, který zpracovává seznamy ACL rekurzivně v dávkách zadáním velikosti dávky, najdete v ukázce Pythonu.

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

Aby se zajistilo, že se proces dokončí bez přerušení, nepředávejte do metody DataLakeDirectoryClient.set_access_control_recursive token pro pokračování.

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.

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)

Příklad, který zpracovává seznamy ACL rekurzivně v dávkách zadáním velikosti dávky, najdete v ukázce Pythonu.

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é