Gunakan Python untuk mengelola ACL di Azure Data Lake Storage Gen2

  • Artikel

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. Namun Anda juga dapat menambahkan, memperbarui, dan menghapus ACL secara berulang pada item anak yang ada dari direktori induk tanpa harus melakukan perubahan ini satu per satu untuk setiap item anak.

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

Prasyarat

  • Langganan Azure. Untuk informasi selengkapnya, lihat Dapatkan uji coba gratis Azure.

  • Akun penyimpanan dengan namespace hierarkis (HNS) aktif. Ikuti petunjuk berikut untuk membuatnya.

  • Azure CLI versi 2.6.0 atau lebih tinggi.

  • Salah satu izin keamanan berikut ini:

    • Prinsip keamanan MICROSOFT Entra ID yang disediakan yang telah ditetapkan peran Pemilik Data Blob Penyimpanan, dilingkupkan ke kontainer target, akun penyimpanan, grup sumber daya induk, atau langganan.

    • Pengguna pemilik kontainer target atau direktori tempat Anda berencana menerapkan pengaturan ACL. Untuk mengatur ACL secara berulang, ini mencakup semua item anak dalam kontainer atau direktori target.

    • Kunci akun penyimpanan.

Menyiapkan proyek Anda

Instal pustaka klien Azure Data Lake Storage untuk Python dengan menggunakan pip.

pip install azure-storage-file-datalake

Tambahkan pernyataan impor ini ke bagian atas file kode Anda.

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

Sambungkan ke akun

Untuk menggunakan cuplikan dalam artikel ini, Anda harus membuat instance DataLakeServiceClient yang mewakili akun penyimpanan.

Koneksi dengan menggunakan ID Microsoft Entra

Catatan

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

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

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

Peran Kapabilitas pengaturan ACL
Pemilik Data Blob Penyimpanan Semua direktori dan file dalam akun tersebut.
Data blob penyimpanan kontributor Hanya direktori dan file yang dimiliki oleh prinsipal keamanan.

Selanjutnya, buat instans DataLakeServiceClient dan teruskan instans baru 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.

Sambungkan dengan menggunakan kunci akun

Anda dapat mengotorisasi akses ke data menggunakan kunci akses akun Anda (Kunci Bersama). Contoh ini membuat instans DataLakeServiceClient yang diotorisasi dengan kunci akun.

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

Perhatian

Otorisasi dengan Kunci Bersama tidak disarankan karena mungkin kurang aman. Untuk keamanan optimal, nonaktifkan otorisasi melalui Kunci Bersama untuk akun penyimpanan Anda, seperti yang dijelaskan dalam Mencegah otorisasi Kunci Bersama untuk akun Azure Storage.

Penggunaan kunci akses dan string koneksi harus dibatasi pada bukti awal aplikasi konsep atau prototipe pengembangan yang tidak mengakses data produksi atau sensitif. Jika tidak, kelas autentikasi berbasis token yang tersedia di Azure SDK harus selalu disukai saat mengautentikasi ke sumber daya Azure.

Microsoft menyarankan agar klien menggunakan ID Microsoft Entra atau tanda tangan akses bersama (SAS) untuk mengotorisasi akses ke data di Azure Storage. Untuk informasi selengkapnya, lihat Mengotorisasi operasi untuk akses data.

Atur ACL

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

Bagian ini memperlihatkan kepada Anda cara:

  • Atur ACL direktori
  • Mengatur ACL file

Atur ACL direktori

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

Contoh ini mendapatkan dan menetapkan ACL direktori bernama my-directory. String rwxr-xrw- memberi pengguna pemilik izin baca, tulis, dan eksekusi, memberikan grup pemilik hanya izin baca dan eksekusi, dan memberi semua orang lain izin baca dan tulis.

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 root kontainer. Untuk mendapatkan direktori root, panggil metode FileSystemClient._get_root_directory_client ini.

Mengatur ACL file

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

Contoh ini mendapatkan dan menetapkan ACL direktori bernama my-file.txt. String rwxr-xrw- memberi pengguna pemilik izin baca, tulis, dan eksekusi, memberikan grup pemilik hanya izin baca dan eksekusi, dan memberi semua orang lain izin baca dan tulis.

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)

Menetapkan ACL secara rekursif

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

Atur ACL secara rekursif dengan memanggil metode DataLakeDirectoryClient.set_access_control_recursive ini.

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

Contoh ini mengatur ACL direktori dengan nama my-parent-directory.

Metode ini menerima parameter boolean dengan nama 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 pengguna tertentu dengan izin baca ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx objek.

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.

Perbarui ACL secara berulang

Saat memperbarui ACL, Anda mengubah ACL, dan bukan mengganti ACL. Misalnya, Anda dapat menambahkan perwakilan keamanan baru ke ACL tanpa memengaruhi perwakilan 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 pembaruan ACL. Jangan ambil ACL yang ada, cukup sediakan entri ACL yang akan diperbarui. Perbarui ACL secara rekursif dengan memanggil metode DataLakeDirectoryClient.update_access_control_recursive ini. Jika Anda ingin memperbarui entri ACL default, lalu menambahkan string default: ke awal setiap string entri ACL.

Contoh ini memperbarui entri ACL dengan izin tulis.

Contoh ini mengatur ACL direktori dengan nama my-parent-directory. Metode ini menerima parameter boolean bernama is_default_scope yang menentukan apakah akan memperbarui ACL default. jika parameternya 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.

Hapus entri ACL secara rekursif

Anda bisa 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 ambil ACL yang ada, cukup sediakan entri ACL yang akan dihapus.

Hapus entri ACL dengan memanggil metode DataLakeDirectoryClient.remove_access_control_recursive ini. Jika Anda ingin menghapus entri ACL default, lalu menambahkan string default: ke awal setiap string entri ACL.

Contoh ini menghapus entri ACL dari ACL direktori dengan nama my-parent-directory. Metode ini menerima parameter boolean dengan nama is_default_scope yang menentukan apakah akan menghapus entri dari ACL default. jika parameternya 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.

Memulihkan dari kegagalan

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

Contoh ini mengembalikan token kelanjutan jika terjadi kegagalan. Aplikasi dapat memanggil metode contoh ini lagi setelah kesalahan telah diatasi, dan meneruskan token kelanjutan. Jika metode contoh ini dipanggil untuk pertama kalinya, aplikasi dapat meloloskan 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 bisa menentukannya.

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

Contoh ini menetapkan entri ACL secara rekursif. Jika kode ini menemui kesalahan izin, maka akan merekam kegagalan tersebut dan melanjutkan eksekusi. Contoh ini mencetak jumlah kegagalan pada 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 menyediakan beberapa panduan praktik terbaik untuk mengatur ACL secara rekursif.

Menangani kesalahan runtime bahasa umum

Kesalahan runtime dapat terjadi karena berbagai alasan (Misalnya: ketidaktersediaan 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 menemukan 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.

Kredensial

Kami menyarankan agar Anda menyediakan perwakilan keamanan Microsoft Entra yang telah ditetapkan peran Pemilik Data Blob Penyimpanan dalam cakupan akun penyimpanan target atau kontainer.

Performa

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

Batas 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.

Baca juga