Python gebruiken om ACL's te beheren in Azure Data Lake Storage

In dit artikel leest u hoe u python gebruikt om de toegangsbeheerlijsten van mappen en bestanden op te halen, in te stellen en bij te werken.

ACL-overname is al beschikbaar voor nieuwe onderliggende items die onder een bovenliggende map zijn gemaakt. U kunt echter ook ACL's recursief toevoegen, bijwerken en verwijderen op de bestaande onderliggende items van een bovenliggende map zonder dat u deze wijzigingen afzonderlijk hoeft aan te brengen voor elk onderliggend item.

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

Vereisten

• Azure-abonnement: maak er gratis een.
• Azure Storage-account waarvoor HNS (hiërarchische naamruimte) is ingeschakeld. Volg deze instructies om er een te maken.
• Python 3.8+
• Azure CLI-versie 2.6.0 of hoger.
• Een van de volgende beveiligingsmachtigingen:
  • Een ingerichte Microsoft Entra ID-beveiligingsprincipaal waaraan de rol Eigenaar van opslagblobgegevens is toegewezen, die is gericht op de doelcontainer, het opslagaccount, de bovenliggende resourcegroep of het abonnement.
  • De gebruiker die eigenaar is van de doelcontainer of map waarop u ACL-instellingen wilt toepassen. Als u ACL's recursief wilt instellen, omvat dit alle onderliggende items in de doelcontainer of map.
  • Sleutel van opslagaccount.

Uw project instellen

In deze sectie wordt uitgelegd hoe u een project voorbereidt voor gebruik met de Azure Data Lake Storage-clientbibliotheek voor Python.

Installeer vanuit uw projectmap pakketten voor de Azure Data Lake Storage- en Azure Identity-clientbibliotheken met behulp van de pip install opdracht. Het azure-identity-pakket is nodig voor verbindingen zonder wachtwoord met Azure-services.

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

Open vervolgens het codebestand en voeg de benodigde importinstructies toe. In dit voorbeeld voegen we het volgende toe aan het bestand .py :

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

Verbinding maken met het account

Als u de codevoorbeelden in dit artikel wilt uitvoeren, moet u een DataLakeServiceClient-exemplaar maken dat het opslagaccount vertegenwoordigt. U kunt het clientobject autoriseren met Microsoft Entra ID-referenties of met een accountsleutel.

Microsoft Entra-id (aanbevolen)

U kunt de Azure Identity-clientbibliotheek voor Python gebruiken om uw toepassing te verifiëren met Microsoft Entra-id.

Notitie

Als u de Microsoft Entra-id gebruikt om toegang te verlenen, moet u ervoor zorgen dat de rol van de eigenaar van de opslagblobgegevens is toegewezen aan uw beveiligingsprincipaal. Zie het Access Control-model in Azure Data Lake Storage voor meer informatie over hoe ACL-machtigingen worden toegepast en wat de gevolgen zijn van het wijzigen ervan.

Wijs eerst een van de volgende azure RBAC-rollen (op rollen gebaseerd toegangsbeheer) toe aan uw beveiligingsprincipaal:

Role	ACL-instellingsmogelijkheid
Eigenaar van opslagblobgegevens	Alle mappen en bestanden in het account.
Inzender van opslag-blobgegevens	Alleen mappen en bestanden die eigendom zijn van de beveiligingsprincipaal.

Maak vervolgens een DataLakeServiceClient-exemplaar en geef een nieuw exemplaar van de klasse DefaultAzureCredential door .

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

Zie Overzicht: Python-apps verifiëren bij Azure met behulp van de Azure SDK voor meer informatie over het gebruik van DefaultAzureCredential om toegang tot gegevens te autoriseren.

Accountsleutel

U kunt toegang tot gegevens autoriseren met behulp van uw accounttoegangssleutels (gedeelde sleutel). In dit voorbeeld wordt een DataLakeServiceClient-exemplaar gemaakt dat is geautoriseerd met de accountsleutel.

def get_service_client_account_key(self, account_name, account_key) -> DataLakeServiceClient:
    account_url = f"https://{account_name}.dfs.core.windows.net"
    service_client = DataLakeServiceClient(account_url, credential=account_key)

    return service_client

Let op

Autorisatie met gedeelde sleutel wordt niet aanbevolen omdat deze mogelijk minder veilig is. Schakel voor optimale beveiliging autorisatie uit via een gedeelde sleutel voor uw opslagaccount, zoals beschreven in Autorisatie van gedeelde sleutels voorkomen voor een Azure Storage-account.

Het gebruik van toegangssleutels en verbindingsreeks s moet worden beperkt tot het eerste bewijs van concept-apps of prototypen voor ontwikkeling die geen toegang hebben tot productie- of gevoelige gegevens. Anders moeten de verificatieklassen op basis van tokens die beschikbaar zijn in de Azure SDK altijd de voorkeur krijgen bij het verifiëren bij Azure-resources.

Microsoft raadt aan dat clients Microsoft Entra ID of sas (Shared Access Signature) gebruiken om toegang tot gegevens in Azure Storage te autoriseren. Zie Bewerkingen autoriseren voor gegevenstoegang voor meer informatie.

ACL's instellen

Wanneer u een ACL instelt, vervangt u de volledige ACL, inclusief alle vermeldingen. Als u het machtigingsniveau van een beveiligingsprincipaal wilt wijzigen of een nieuwe beveiligingsprincipaal wilt toevoegen aan de ACL zonder dat dit van invloed is op andere bestaande vermeldingen, moet u in plaats daarvan de ACL bijwerken . Als u een ACL wilt bijwerken in plaats van deze te vervangen, raadpleegt u de sectie ACL's bijwerken van dit artikel.

In deze sectie ziet u hoe u het volgende kunt doen:

• De ACL van een map instellen
• De ACL van een bestand instellen

De ACL van een map instellen

Haal de toegangsbeheerlijst (ACL) van een directory op door de DataLakeDirectoryClient.get_access_control methode aan te roepen en de ACL in te stellen door de DataLakeDirectoryClient.set_access_control methode aan te roepen.

In dit voorbeeld wordt de ACL van een map met de naam my-directoryopgehaald en ingesteld. De tekenreeks rwxr-xrw- geeft de gebruiker lees-, schrijf- en uitvoermachtigingen, geeft de groep die eigenaar is alleen lees- en uitvoermachtigingen en geeft alle andere lees- en schrijfmachtigingen.

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)

U kunt ook de ACL van de hoofdmap van een container ophalen en instellen. Als u de hoofdmap wilt ophalen, roept u de FileSystemClient._get_root_directory_client-methode aan.

De ACL van een bestand instellen

Haal de toegangsbeheerlijst (ACL) van een bestand op door de methode DataLakeFileClient.get_access_control aan te roepen en de ACL in te stellen door de DataLakeFileClient.set_access_control methode aan te roepen.

In dit voorbeeld wordt de ACL van een bestand met de naam my-file.txtopgehaald en ingesteld. De tekenreeks rwxr-xrw- geeft de gebruiker lees-, schrijf- en uitvoermachtigingen, geeft de groep die eigenaar is alleen lees- en uitvoermachtigingen en geeft alle andere lees- en schrijfmachtigingen.

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)

ACL's recursief instellen

Wanneer u een ACL instelt, vervangt u de volledige ACL, inclusief alle vermeldingen. Als u het machtigingsniveau van een beveiligingsprincipaal wilt wijzigen of een nieuwe beveiligingsprincipaal wilt toevoegen aan de ACL zonder dat dit van invloed is op andere bestaande vermeldingen, moet u in plaats daarvan de ACL bijwerken . Als u een ACL wilt bijwerken in plaats van deze te vervangen, raadpleegt u de sectie Update-ACL's recursief in dit artikel.

Stel ACL's recursief in door de methode DataLakeDirectoryClient.set_access_control_recursive aan te roepen.

Als u een standaard-ACL-vermelding wilt instellen, voegt u de tekenreeks default: toe aan het begin van elke ACL-invoerreeks.

In dit voorbeeld wordt de ACL van een map met de naam my-parent-directoryingesteld.

Deze methode accepteert een Booleaanse parameter met de naam is_default_scope die aangeeft of de standaard-ACL moet worden ingesteld. Als deze parameter is True, wordt de lijst met ACL-vermeldingen voorafgegaan door de tekenreeks default:. De vermeldingen in dit voorbeeld verlenen de volgende machtigingen: lees-, schrijf- en uitvoermachtigingen voor de gebruiker die eigenaar is, lees- en uitvoermachtigingen voor de groep die eigenaar is en leesmachtigingen voor alle anderen. De laatste ACL-vermelding in dit voorbeeld geeft een specifieke gebruiker met de leesmachtigingen voor de object-id 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)

Als u een voorbeeld wilt zien waarin ACL's recursief worden verwerkt in batches door een batchgrootte op te geven, raadpleegt u het Python-voorbeeld.

ACL's recursief bijwerken

Wanneer u een ACL bijwerkt , wijzigt u de ACL in plaats van de ACL te vervangen. U kunt bijvoorbeeld een nieuwe beveiligingsprincipaal toevoegen aan de ACL zonder dat dit van invloed is op andere beveiligingsprinciplen die worden vermeld in de ACL. Als u de ACL wilt vervangen in plaats van deze bij te werken, raadpleegt u de sectie ACL's instellen van dit artikel.

Als u een ACL recursief wilt bijwerken, maakt u een nieuw ACL-object met de ACL-vermelding die u wilt bijwerken en gebruikt u dat object in de update-ACL-bewerking. Haal de bestaande ACL niet op, geef alleen ACL-vermeldingen op die moeten worden bijgewerkt. Werk een ACL recursief bij door de methode DataLakeDirectoryClient.update_access_control_recursive aan te roepen. Als u een standaard-ACL-vermelding wilt bijwerken, voegt u de tekenreeks default: toe aan het begin van elke ACL-invoerreeks.

In dit voorbeeld wordt een ACL-vermelding bijgewerkt met schrijfmachtigingen.

In dit voorbeeld wordt de ACL van een map met de naam my-parent-directoryingesteld. Deze methode accepteert een Booleaanse parameter met de naam is_default_scope die aangeeft of de standaard-ACL moet worden bijgewerkt. als deze parameter is True, wordt de bijgewerkte ACL-vermelding voorafgegaan door de tekenreeks 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)

Als u een voorbeeld wilt zien waarin ACL's recursief worden verwerkt in batches door een batchgrootte op te geven, raadpleegt u het Python-voorbeeld.

ACL-vermeldingen recursief verwijderen

U kunt een of meer ACL-vermeldingen verwijderen. Als u ACL-vermeldingen recursief wilt verwijderen, maakt u een nieuw ACL-object voor de ACL-vermelding die moet worden verwijderd en gebruikt u dat object in de bewerking ACL verwijderen. Haal de bestaande ACL niet op, geef alleen de ACL-vermeldingen op die moeten worden verwijderd.

Verwijder ACL-vermeldingen door de methode DataLakeDirectoryClient.remove_access_control_recursive aan te roepen. Als u een standaard-ACL-vermelding wilt verwijderen, voegt u de tekenreeks default: toe aan het begin van de ACL-invoerreeks.

In dit voorbeeld wordt een ACL-vermelding verwijderd uit de ACL van de map met de naam my-parent-directory. Deze methode accepteert een Booleaanse parameter met de naam is_default_scope die aangeeft of de vermelding moet worden verwijderd uit de standaard-ACL. Als deze parameter is True, wordt de bijgewerkte ACL-vermelding voorafgegaan door de tekenreeks 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)

Als u een voorbeeld wilt zien waarin ACL's recursief worden verwerkt in batches door een batchgrootte op te geven, raadpleegt u het Python-voorbeeld.

Herstellen na fouten

Er kunnen runtime- of machtigingsfouten optreden. Voor runtimefouten start u het proces opnieuw vanaf het begin. Machtigingsfouten kunnen optreden als de beveiligingsprincipaal niet over voldoende machtigingen beschikt om de ACL te wijzigen van een map of bestand dat zich in de maphiërarchie bevindt die wordt gewijzigd. Los het machtigingsprobleem op en kies er vervolgens voor om het proces te hervatten vanaf het punt van de fout met behulp van een vervolgtoken of start het proces opnieuw vanaf het begin. U hoeft het vervolgtoken niet te gebruiken als u liever opnieuw wilt opstarten vanaf het begin. U kunt ACL-vermeldingen opnieuw gebruiken zonder negatieve gevolgen.

In dit voorbeeld wordt een vervolgtoken geretourneerd in het geval van een fout. De toepassing kan deze voorbeeldmethode opnieuw aanroepen nadat de fout is opgelost en het vervolgtoken doorgeven. Als deze voorbeeldmethode voor het eerst wordt aangeroepen, kan de toepassing een waarde van None de vervolgtokenparameter doorgeven.

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

Als u een voorbeeld wilt zien waarin ACL's recursief worden verwerkt in batches door een batchgrootte op te geven, raadpleegt u het Python-voorbeeld.

Als u wilt dat het proces ononderbroken wordt voltooid door machtigingsfouten, kunt u dat opgeven.

Om ervoor te zorgen dat het proces ononderbroken wordt voltooid, geeft u geen vervolgtoken door aan de methode DataLakeDirectoryClient.set_access_control_recursive .

In dit voorbeeld worden ACL-vermeldingen recursief ingesteld. Als deze code een machtigingsfout tegenkomt, wordt die fout vastgelegd en wordt de uitvoering voortgezet. In dit voorbeeld wordt het aantal fouten in de console afgedrukt.

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)

Als u een voorbeeld wilt zien waarin ACL's recursief worden verwerkt in batches door een batchgrootte op te geven, raadpleegt u het Python-voorbeeld.

Aanbevolen procedures

In deze sectie vindt u enkele aanbevolen richtlijnen voor het recursief instellen van ACL's.

Runtimefouten afhandelen

Een runtimefout kan om verschillende redenen optreden (bijvoorbeeld een storing of een probleem met de clientconnectiviteit). Als er een runtimefout optreedt, start u het recursieve ACL-proces opnieuw. ACL's kunnen opnieuw worden toegepast op items zonder een negatieve impact te veroorzaken.

Machtigingsfouten afhandelen (403)

Als er een uitzondering voor toegangsbeheer optreedt tijdens het uitvoeren van een recursief ACL-proces, beschikt uw AD-beveiligingsprincipaal mogelijk niet over voldoende machtigingen om een ACL toe te passen op een of meer onderliggende items in de adreslijsthiërarchie. Wanneer er een machtigingsfout optreedt, stopt het proces en wordt er een vervolgtoken opgegeven. Los het machtigingsprobleem op en gebruik vervolgens het vervolgtoken om de resterende gegevensset te verwerken. De mappen en bestanden die al zijn verwerkt, hoeven niet opnieuw te worden verwerkt. U kunt er ook voor kiezen om het recursieve ACL-proces opnieuw te starten. ACL's kunnen opnieuw worden toegepast op items zonder een negatieve impact te veroorzaken.

Referentie

U wordt aangeraden een Microsoft Entra-beveiligingsprincipaal in te richten waaraan de rol Eigenaar van opslagblobgegevens is toegewezen in het bereik van het doelopslagaccount of de doelcontainer.

Prestaties

Als u de latentie wilt verminderen, raden we u aan het recursieve ACL-proces uit te voeren op een virtuele Azure-machine (VM) die zich in dezelfde regio bevindt als uw opslagaccount.

ACL-limieten

Het maximum aantal ACL's dat u kunt toepassen op een map of bestand, is 32 toegangs-ACL's en 32 standaard-ACL's. Zie Toegangsbeheer in Azure Data Lake Storage Gen2 voor meer informatie.

Zie ook

• API-referentiedocumentatie
• Pakket (Python-pakketindex)
• Voorbeelden
• Gen1 naar Gen2-toewijzing
• Bekende problemen
• Feedback geven
• Toegangsbeheermodel in Azure Data Lake Storage
• Toegangsbeheerlijsten (ACL's) in Azure Data Lake Storage