Bagikan melalui

Menggunakan PowerShell untuk mengelola ACL di Azure Data Lake Storage

  • Artikel

Artikel ini menunjukkan kepada Anda cara menggunakan PowerShell 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.

Referensi | Berikan 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:

    • Perwakilan keamanan MICROSOFT Entra ID yang disediakan yang telah ditetapkan peran Pemilik Data Blob Penyimpanan, terlingkup 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.

Menginstal modul PowerShell

  1. Pastikan bahwa PowerShell yang telah diinstal adalah versi 5.1 atau lebih tinggi dengan menggunakan perintah berikut.

    echo $PSVersionTable.PSVersion.ToString()

    Untuk memutakhirkan versi PowerShell Anda, lihat Memutakhirkan Windows PowerShell yang sudah ada

  2. Pasang modul Az.Storage.

    Install-Module Az.Storage -Repository PSGallery -Force

    Untuk informasi selengkapnya tentang cara menginstal modul PowerShell, lihat Menginstal modul Azure PowerShell

Sambungkan ke akun

Pilih bagaimana Anda ingin perintah Anda mendapatkan otorisasi ke akun penyimpanan.

Opsi 1: Dapatkan otorisasi 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 bagaimana izin ACL diterapkan dan efek mengubahnya, lihat Model kontrol akses di Azure Data Lake Storage.

Dengan pendekatan ini, sistem memastikan bahwa akun pengguna Anda memiliki penetapan kontrol akses berbasis peran Azure (Azure RBAC) dan izin ACL yang sesuai.

  1. Buka jendela perintah Windows PowerShell, lalu masuk ke langganan Azure Anda dengan Connect-AzAccount perintah dan ikuti petunjuk di layar.

    Connect-AzAccount

  2. Jika identitas Anda dikaitkan dengan lebih dari satu langganan, aturlah langganan aktif Anda ke langganan akun penyimpanan tempat Anda ingin membuat dan mengelola direktori. Dalam contoh ini, gantilah <subscription-id> nilai tempat penampung dengan ID langganan Anda.

    Select-AzSubscription -SubscriptionId <subscription-id>

  3. Dapatkan konteks akun penyimpanan.

    $ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -UseConnectedAccount

Opsi 2: Dapatkan otorisasi dengan menggunakan kunci akun penyimpanan

Dengan pendekatan ini, sistem tidak memeriksa izin Azure RBAC atau ACL. Dapatkan konteks akun penyimpanan dengan menggunakan kunci akun.

$ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -StorageAccountKey '<storage-account-key>'

Dapatkan ACL

Dapatkan ACL direktori atau file dengan menggunakan Get-AzDataLakeGen2Item cmdlet.

Contoh ini mendapatkan ACL dari direktori root kontainer dan kemudian mencetak ACL ke konsol.

$filesystemName = "my-file-system"
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

Contoh ini mendapatkan ACL dari directory, lalu mencetak ACL ke konsol.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

Contoh ini mendapatkan ACL dari sebuah file dan kemudian mencetak ACL ke konsol.

$filePath = "my-directory/upload.txt"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

Gambar berikut menunjukkan output setelah mendapatkan ACL direktori.

Dapatkan output ACL untuk direktori

Dalam contoh ini, pengguna pemilik mempunyai izin membaca, menulis, dan menjalankan. Grup pemilik hanya memiliki izin membaca dan menjalankan. Untuk informasi selengkapnya tentang daftar kontrol akses, lihat Kontrol akses di Azure Data Lake Storage.

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.

Jika Anda memilih untuk mengatur ACL, Anda harus menambahkan entri untuk pengguna pemilik, entri untuk grup pemilik, dan entri untuk semua pengguna lain. Untuk mempelajari selengkapnya tentang pengguna yang memiliki, grup pemilik, dan semua pengguna lainnya, lihat Pengguna dan identitas.

Bagian ini memperlihatkan kepada Anda cara:

  • Mengatur ACL
  • Menetapkan ACL secara rekursif

Mengatur ACL

Gunakan Set-AzDataLakeGen2ItemAclObject cmdlet untuk membuat ACL untuk pengguna yang memiliki, memiliki grup, atau pengguna lain. Kemudian, gunakan Update-AzDataLakeGen2Item cmdlet untuk melakukan penerapan ACL.

Contoh ini mengatur ACL pada direktori akar dari kontainer untuk pengguna pemilik, grup pemilik, atau pengguna lain, lalu mencetak ACL ke konsol.

$filesystemName = "my-file-system"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Acl $acl
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

Contoh ini mengatur ACL pada directory untuk pengguna pemilik, grup pemilik, atau pengguna lain, lalu mencetak ACL ke konsol.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

Catatan

Jika Anda ingin mengatur entri ACL default, gunakan parameter -DefaultScope saat Anda menjalankan perintah Set-AzDataLakeGen2ItemAclObject. Misalnya: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope.

Contoh ini mengatur ACL pada file untuk pengguna pemilik, grup pemilik, atau pengguna lain, lalu mencetak ACL ke konsol.

$filesystemName = "my-file-system"
$filePath = "my-directory/upload.txt"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "-wx" -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath -Acl $acl
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

Catatan

Untuk mengatur ACL grup atau pengguna tertentu, perwakilan layanan, atau identitas terkelola, gunakan ID objek masing-masing. Misalnya, untuk mengatur ACL grup, gunakan group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Untuk mengatur ACL pengguna, gunakan user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Gambar berikut menunjukkan output setelah mengatur ACL file.

Dapatkan output ACL untuk file

Dalam contoh ini, pengguna pemilik dan grup pemilik hanya memiliki izin membaca dan menulis. Semua pengguna lain memiliki izin menulis dan menjalankan. Untuk informasi selengkapnya tentang daftar kontrol akses, lihat Kontrol akses di Azure Data Lake Storage.

Menetapkan ACL secara rekursif

Atur ACL secara berulang dengan menggunakan cmdlet Set-AzDataLakeGen2AclRecursive.

Contoh ini mengatur ACL direktori dengan nama my-parent-directory. Entri ACL memberi pengguna pemilik izin membaca, menulis, dan menjalankan, memberi grup pemilik hanya izin membaca dan menjalankan, dan tidak memberi akses ke semua orang lain. Entri ACL terakhir dalam contoh ini memberikan pengguna tertentu ID objek "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" izin membaca dan menjalankan.

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission r-x -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "---" -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission r-x -InputObject $acl

Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Catatan

Jika Anda ingin mengatur entri ACL default, gunakan parameter -DefaultScope saat Anda menjalankan perintah Set-AzDataLakeGen2ItemAclObject. Misalnya: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope.

Untuk melihat contoh yang menetapkan ACL secara berulang dalam batch dengan menentukan ukuran batch, lihat artikel referensi Set-AzDataLakeGen2AclRecursive.

Perbarui ACL

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.

Bagian ini memperlihatkan kepada Anda cara:

  • Perbarui ACL
  • Perbarui ACL secara berulang

Perbarui ACL

Pertama, dapatkan ACL. Kemudian, gunakan Set-AzDataLakeGen2ItemAclObject cmdlet untuk menambahkan atau memperbarui entri ACL. Gunakan Update-AzDataLakeGen2Item cmdlet untuk melakukan penerapan ACL.

Contoh ini membuat atau memperbarui ACL pada direktori untuk pengguna.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = (Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname).ACL
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Catatan

Jika Anda ingin mengatur entri ACL default, gunakan parameter -DefaultScope saat Anda menjalankan perintah Set-AzDataLakeGen2ItemAclObject. Misalnya: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -DefaultScope.

Perbarui ACL secara berulang

Perbarui ACL secara berulang dengan menggunakan cmdlet Update-AzDataLakeGen2AclRecursive.

Contoh ini memperbarui entri ACL dengan izin tulis.

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission rwx

Update-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Catatan

Untuk mengatur ACL grup atau pengguna tertentu, perwakilan layanan, atau identitas terkelola, gunakan ID objek masing-masing. Misalnya, untuk mengatur ACL grup, gunakan group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Untuk mengatur ACL pengguna, gunakan user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Untuk melihat contoh yang menetapkan ACL secara berulang dalam batch dengan menentukan ukuran batch, lihat artikel referensi Update-AzDataLakeGen2AclRecursive.

Hapus entri ACL

Bagian ini memperlihatkan kepada Anda cara:

  • Menghapus entri ACL
  • Hapus entri ACL secara rekursif

Menghapus entri ACL

Contoh ini akan menghapus entri dari ACL yang ada.

$id = "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Create the new ACL object.
[Collections.Generic.List[System.Object]]$aclnew =$acl

foreach ($a in $aclnew)
{
    if ($a.AccessControlType -eq "User" -and $a.DefaultScope -eq $false -and $a.EntityId -eq $id)
    {
        $aclnew.Remove($a);
        break;
    }
}
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $aclnew

Hapus entri ACL secara rekursif

Anda dapat menghapus satu entri ACL atau lebih secara berulang. Untuk menghapus entri ACL, buat objek ACL baru untuk entri ACL yang akan dihapus, lalu gunakan objek tersebut untuk menghapus operasi ACL. Jangan ambil ACL yang ada, cukup sediakan entri ACL yang akan dihapus.

Hapus entri ACL dengan menggunakan cmdlet Remove-AzDataLakeGen2AclRecursive.

Contoh ini menghapus entri ACL dari direktori akar kontainer.

$filesystemName = "my-container"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---"

Remove-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName  -Acl $acl

Catatan

Jika Anda ingin mengatur entri ACL default, gunakan parameter -DefaultScope saat Anda menjalankan perintah Set-AzDataLakeGen2ItemAclObject. Misalnya: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---" -DefaultScope.

Untuk melihat contoh yang menetapkan ACL secara berulang dalam batch dengan menentukan ukuran batch, lihat artikel referensi Remove-AzDataLakeGen2AclRecursive.

Memulihkan dari kegagalan

Anda mungkin mengalami kesalahan runtime atau izin saat memodifikasi ACL secara berulang.

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 hasil ke variabel, lalu pipa gagal entri ke tabel yang diformat.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$result
$result.FailedEntries | ft

Berdasarkan output tabel, Anda dapat memperbaiki kesalahan izin apa pun, lalu melanjutkan eksekusi dengan menggunakan token kelanjutan.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinuationToken $result.ContinuationToken
$result

Untuk melihat contoh yang menetapkan ACL secara berulang dalam batch dengan menentukan ukuran batch, lihat artikel referensi Set-AzDataLakeGen2AclRecursive.

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

Contoh ini menggunakan ContinueOnFailure parameter sehingga eksekusi berlanjut meskipun operasi menemui kesalahan izin.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinueOnFailure

echo "[Result Summary]"
echo "TotalDirectoriesSuccessfulCount: `t$($result.TotalFilesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalDirectoriesSuccessfulCount)"
echo "TotalFailureCount: `t`t`t`t`t$($result.TotalFailureCount)"
echo "FailedEntries:"$($result.FailedEntries | ft)

Untuk melihat contoh yang menetapkan ACL secara berulang dalam batch dengan menentukan ukuran batch, lihat artikel referensi Set-AzDataLakeGen2AclRecursive.

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.

Informasi Masuk

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.

Lihat juga