Bagikan melalui

Menggunakan Python untuk mengelola ACL di Azure Data Lake Storage

Artikel ini memperlihatkan kepada Anda cara menggunakan Python untuk mendapatkan, mengatur, dan memperbarui daftar kontrol akses direktori dan file.

Pewarisan ACL sudah tersedia untuk item anak baru yang dibuat di bawah direktori induk. Tetapi Anda juga dapat menambahkan, memperbarui, dan menghapus ACL secara rekursif pada item anak yang ada dari direktori induk tanpa harus membuat perubahan ini satu per satu untuk setiap item anak.

Paket (Indeks Paket Python) | Sampel | Sampel ACL rekursif | Referensi API | Pemetaan Gen1 ke Gen2 | Berikan Umpan Balik

Prerequisites

  • Langganan Azure - membuat langganan secara gratis.
  • Akun penyimpanan Azure yang mengaktifkan namespace hierarkis (HNS). Ikuti instruksi ini untuk membuatnya.
  • Python 3.8+
  • Versi Azure CLI 2.6.0 ke atas.
  • Salah satu izin keamanan berikut:
    • Microsoft Entra ID prinsip keamanan yang telah disediakan dan diberi peran Pemilik Data Blob Penyimpanan, yang berlaku untuk kontainer target, akun penyimpanan, grup sumber daya induk, atau langganan.
    • Pengguna yang memiliki hak akses atas kontainer atau direktori target tempat Anda berencana menerapkan pengaturan ACL. Untuk mengatur ACL secara rekursif, ini mencakup semua item turunan dalam kontainer atau direktori target.
    • Kunci akun penyimpanan.

Menyiapkan proyek Anda

Bagian ini memandu Anda menyiapkan proyek untuk bekerja dengan pustaka klien Azure Data Lake Storage untuk Python.

Dari direktori proyek Anda, instal paket untuk pustaka klien Azure Data Lake Storage dan Azure Identity menggunakan perintah pip install. Paket identitas azure diperlukan untuk koneksi tanpa kata sandi ke layanan Azure.

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

Kemudian buka file kode Anda dan tambahkan pernyataan impor yang diperlukan. Dalam contoh ini, kami menambahkan yang berikut ke file .py kami:

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

Menyambungkan ke akun

Untuk menjalankan contoh kode dalam artikel ini, Anda perlu membuat instans DataLakeServiceClient yang mewakili akun penyimpanan. Anda dapat mengotorisasi objek klien dengan kredensial ID Microsoft Entra atau dengan kunci akun.

Anda dapat menggunakan pustaka klien identitas Azure untuk Python untuk mengautentikasi aplikasi Anda dengan ID Microsoft Entra.

Note

Jika Anda menggunakan ID Microsoft Entra untuk mengotorisasi akses, pastikan bahwa prinsipal keamanan Anda telah diberi peran Pemilik Data Blob Penyimpanan. Untuk mempelajari selengkapnya tentang bagaimana izin ACL diterapkan dan efek mengubahnya, lihat Model kontrol akses di Azure Data Lake Storage.

Pertama, tetapkan salah satu peran kontrol akses berbasis peran Azure (Azure RBAC) berikut ini ke prinsip keamanan Anda:

Role Kemampuan pengaturan ACL
Pemilik Data Blob Penyimpanan Semua direktori dan file di akun.
Kontributor Data untuk Blob Penyimpanan Hanya direktori dan file yang dimiliki oleh perwakilan keamanan.

Selanjutnya, buat instans DataLakeServiceClient dan berikan instance baru dari kelas 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

Untuk mempelajari selengkapnya tentang menggunakan DefaultAzureCredential untuk mengotorisasi akses ke data, lihat Gambaran Umum: Mengautentikasi aplikasi Python ke Azure menggunakan Azure SDK.

Atur ACL

Saat Anda mengatur ACL, Anda mengganti seluruh ACL termasuk semua entrinya. Jika Anda ingin mengubah tingkat izin prinsip keamanan atau menambahkan prinsip keamanan baru ke ACL tanpa memengaruhi entri lain yang ada, Anda harus memperbarui ACL sebagai gantinya. Untuk memperbarui ACL alih-alih menggantinya, lihat bagian Perbarui ACL di artikel ini.

Bagian ini memperlihatkan kepada Anda cara:

  • Mengatur ACL dari direktori
  • Mengatur Daftar Kontrol Akses pada sebuah file

Mengatur ACL dari direktori

Dapatkan daftar kontrol akses (ACL) direktori dengan memanggil metode DataLakeDirectoryClient.get_access_control dan atur ACL dengan memanggil metode DataLakeDirectoryClient.set_access_control .

Contoh ini mendapatkan dan mengatur ACL direktori bernama my-directory. String rwxr-xrw- memberi pengguna pemilik izin baca, tulis, dan jalankan, memberi grup pemilik hanya izin baca dan jalankan, dan memberi semua izin baca dan tulis lainnya.

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)

Anda juga bisa mendapatkan dan mengatur ACL direktori akar kontainer. Untuk mendapatkan direktori akar, panggil metode FileSystemClient._get_root_directory_client .

Mengatur Daftar Kontrol Akses pada sebuah file

Dapatkan daftar kontrol akses (ACL) file dengan memanggil metode DataLakeFileClient.get_access_control dan atur ACL dengan memanggil metode DataLakeFileClient.set_access_control .

Contoh ini mendapatkan dan mengatur ACL file bernama my-file.txt. String rwxr-xrw- memberi pengguna pemilik izin baca, tulis, dan jalankan, memberi grup pemilik hanya izin baca dan jalankan, dan memberi semua izin baca dan tulis lainnya.

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)

Mengatur ACL secara rekursif

Saat Anda mengatur ACL, Anda mengganti seluruh ACL termasuk semua entrinya. Jika Anda ingin mengubah tingkat izin prinsip keamanan atau menambahkan prinsip keamanan baru ke ACL tanpa memengaruhi entri lain yang ada, Anda harus memperbarui ACL sebagai gantinya. Untuk memperbarui ACL alih-alih menggantinya, lihat bagian Memperbarui ACL secara rekursif di artikel ini.

Atur ACL secara rekursif dengan memanggil metode DataLakeDirectoryClient.set_access_control_recursive .

Jika Anda ingin mengatur entri ACL default , tambahkan string default: ke awal setiap string entri ACL.

Contoh ini mengatur ACL direktori bernama my-parent-directory.

Metode ini menerima parameter boolean bernama is_default_scope yang menentukan apakah akan mengatur ACL default. Jika parameter tersebut adalah True, daftar entri ACL didahului dengan string default:. Entri dalam contoh ini memberikan izin berikut: izin baca, tulis, dan jalankan untuk pengguna pemilik, izin baca dan jalankan untuk grup pemilik, dan izin baca untuk semua orang lain. Entri ACL terakhir dalam contoh ini memberi izin baca kepada pengguna tertentu dengan ID objek 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)

Untuk melihat contoh yang memproses ACL secara rekursif dalam batch dengan menentukan ukuran batch, lihat sampel Python.

Memperbarui ACL secara rekursif

Saat memperbarui ACL, Anda memodifikasi ACL alih-alih mengganti ACL. Misalnya, Anda dapat menambahkan prinsip keamanan baru ke ACL tanpa memengaruhi prinsip keamanan lain yang tercantum dalam ACL. Untuk mengganti ACL alih-alih memperbaruinya, lihat bagian Atur ACL di artikel ini.

Untuk memperbarui ACL secara rekursif, buat objek ACL baru dengan entri ACL yang ingin Anda perbarui, lalu gunakan objek tersebut dalam operasi perbarui ACL. Jangan mengambil ACL yang ada; cukup sediakan entri ACL untuk diperbarui. Perbarui ACL secara rekursif dengan memanggil metode DataLakeDirectoryClient.update_access_control_recursive . Jika Anda ingin memperbarui entri ACL default , tambahkan string default: ke awal setiap string entri ACL.

Contoh ini memperbarui entri ACL dengan izin tulis.

Contoh ini mengatur ACL direktori bernama my-parent-directory. Metode ini menerima parameter boolean bernama is_default_scope yang menentukan apakah akan memperbarui ACL default. jika parameter tersebut adalah True, entri ACL yang diperbarui didahului dengan string 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)

Untuk melihat contoh yang memproses ACL secara rekursif dalam batch dengan menentukan ukuran batch, lihat sampel Python.

Menghapus entri ACL secara rekursif

Anda dapat menghapus satu atau beberapa entri ACL. Untuk menghapus entri ACL secara rekursif, buat objek ACL baru untuk entri ACL yang akan dihapus, lalu gunakan objek tersebut dalam operasi hapus ACL. Jangan mengambil ACL yang ada, cukup sediakan entri ACL yang akan dihapus.

Hapus entri ACL dengan memanggil metode DataLakeDirectoryClient.remove_access_control_recursive . Jika Anda ingin menghapus entri ACL default , tambahkan string default: ke awal string entri ACL.

Contoh ini menghapus entri ACL dari ACL direktori bernama my-parent-directory. Metode ini menerima parameter boolean bernama is_default_scope yang menentukan apakah akan menghapus entri dari ACL default. Jika parameter tersebut adalah True, entri ACL yang diperbarui didahului dengan string 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)

Untuk melihat contoh yang memproses ACL secara rekursif dalam batch dengan menentukan ukuran batch, lihat sampel Python.

Pulihkan dari kegagalan

Anda mungkin mengalami kesalahan runtime atau kesalahan izin. Untuk kesalahan runtime, mulai ulang proses dari awal. Kesalahan izin dapat terjadi jika prinsip keamanan tidak memiliki izin yang memadai untuk mengubah ACL direktori atau file yang berada dalam hierarki direktori yang sedang dimodifikasi. Atasi masalah izin, lalu pilih untuk melanjutkan proses dari titik kegagalan dengan menggunakan token kelanjutan, atau mulai ulang proses dari awal. Anda tidak perlu menggunakan token kelanjutan jika Anda lebih suka memulai ulang dari awal. Anda dapat menerapkan kembali entri ACL tanpa dampak negatif.

Contoh ini mengembalikan token kelanjutan jika terjadi kegagalan. Aplikasi dapat memanggil metode contoh ini lagi setelah kesalahan ditangani, dan meneruskan token kelanjutan. Jika metode contoh ini dipanggil untuk pertama kalinya, aplikasi dapat meneruskan nilai None untuk parameter token kelanjutan.

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

Untuk melihat contoh yang memproses ACL secara rekursif dalam batch dengan menentukan ukuran batch, lihat sampel Python.

Jika Anda ingin proses selesai tanpa gangguan oleh kesalahan izin, Anda dapat menentukannya.

Untuk memastikan bahwa proses selesai tanpa gangguan, jangan meneruskan token kelanjutan ke dalam metode DataLakeDirectoryClient.set_access_control_recursive .

Contoh ini mengatur entri ACL secara rekursif. Jika kode ini mengalami kesalahan izin, kode ini mencatat kegagalan tersebut dan melanjutkan eksekusi. Contoh ini mencetak jumlah kegagalan yang terjadi ke layar 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)

Untuk melihat contoh yang memproses ACL secara rekursif dalam batch dengan menentukan ukuran batch, lihat sampel Python.

Praktik terbaik

Bagian ini memberi Anda beberapa panduan praktik terbaik untuk mengatur ACL secara rekursif.

Menangani kesalahan runtime

Kesalahan runtime dapat terjadi karena banyak alasan (Misalnya: pemadaman atau masalah konektivitas klien). Jika Anda mengalami kesalahan runtime, mulai ulang proses ACL rekursif. ACL dapat diterapkan kembali ke item tanpa menyebabkan dampak negatif.

Menangani kesalahan izin (403)

Jika Anda mengalami pengecualian kontrol akses saat menjalankan proses ACL rekursif, prinsip keamanan AD Anda mungkin tidak memiliki izin yang memadai untuk menerapkan ACL ke satu atau beberapa item anak dalam hierarki direktori. Ketika kesalahan izin terjadi, proses berhenti dan token kelanjutan disediakan. Perbaiki masalah izin, lalu gunakan token kelanjutan untuk memproses himpunan data yang tersisa. Direktori dan file yang telah berhasil diproses tidak perlu diproses lagi. Anda juga dapat memilih untuk memulai ulang proses ACL rekursif. ACL dapat diterapkan kembali ke item tanpa menyebabkan dampak negatif.

Credentials

Kami menyarankan agar Anda menyediakan prinsipal keamanan Microsoft Entra yang telah diberi peran Pemilik Data Blob Penyimpanan dalam lingkup akun penyimpanan atau kontainer target.

Performance

Untuk mengurangi latensi, kami sarankan Anda menjalankan proses ACL rekursif di Azure Virtual Machine (VM) yang terletak di wilayah yang sama dengan akun penyimpanan Anda.

Pembatasan ACL

Jumlah maksimum ACL yang dapat Anda terapkan ke direktori atau file adalah 32 ACL akses dan 32 ACL default. Untuk informasi selengkapnya, lihat Kontrol akses di Azure Data Lake Storage Gen2.

Lihat juga

  • Last updated on