Sdílet prostřednictvím

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

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

Dědičnost ACL je již dostupná pro nové podřízené položky vytvořené v rámci nadřazeného adresáře. 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) | Ukázky | Rekurzivní ukázky ACL | Referenční příručka k API | Mapování Gen1 na Gen2 | Poskytnout 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.
  • 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ý bezpečnostní objekt Microsoft Entra ID, kterému byla přiřazena role Vlastník dat Storage Blob a je 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 aplikovat nastavení řízení přístupu. 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 byla vašemu bezpečnostnímu principálu 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í ACL
Vlastník dat Storage Blob Všechny adresáře a soubory v účtu.
Přispěvatel úložiště Blob dat 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:

  • Nastavit ACL adresáře
  • Nastavte ACL souboru

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

Nastavte 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í 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)

Nastavit ACL rekurzivně

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 tento parametr True, seznam položek ACL je 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 uděluje konkrétnímu uživateli s ID objektu xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx oprávnění ke čtení.

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)

Pokud chcete vidět příklad, který rekurzivně zpracovává ACL v dávkách podle určené velikosti dávky, podívejte se na ukázku 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. Nepožadujte stávající záznamy ACL, pouze zadejte položky ACL, které je třeba 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 záznam ACL s 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)

Pokud chcete vidět příklad, který rekurzivně zpracovává ACL v dávkách podle určené velikosti dávky, podívejte se na ukázku Pythonu.

Rekurzivně odebrat položky 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. Nezískávejte stávající seznam ACL, pouze uveďte 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 ze seznamu oprávnění 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 tento parametr True, aktualizovanou položku seznamu ACL předchází ř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)

Pokud chcete vidět příklad, který rekurzivně zpracovává ACL v dávkách podle určené velikosti dávky, podívejte se na ukázku 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 příklad metody znovu volat až bude chyba vyřešena 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

Pokud chcete vidět příklad, který rekurzivně zpracovává ACL v dávkách podle určené velikosti dávky, podívejte se na ukázku Pythonu.

Pokud chcete, aby proces dokončil nepřerušený kvůli chybám 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)

Pokud chcete vidět příklad, který rekurzivně zpracovává ACL v dávkách podle určené velikosti dávky, podívejte se na ukázku Pythonu.

Osvědčené postupy

Tato část poskytuje pokyny pro osvědčené postupy při rekurzivním nastavení seznamů řízení přístupu (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 chybě při runtime, restartujte rekurzivní proces ACL. 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 ACL dojde k výjimce při řízení přístupu, nemusí mít bezpečnostní hlavní objekt AD dostatečná oprávnění k použití ACL na jednu nebo více podřízených položek v hierarchii adresáře. 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 řízení přístupu (ACL). 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 ACL ve virtuálním počítači ve službě Azure, který se nachází ve stejné oblasti jako vaše ú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é

  • Last updated on