Bagikan melalui

Menggunakan PowerShell untuk mengelola ACL di Azure Data Lake Storage

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) yang diaktifkan. Ikuti petunjuk berikut untuk membuatnya.

  • Azure CLI versi 2.6.0 atau lebih tinggi.

  • Salah satu izin keamanan berikut ini:

    • Prinsipal keamanan Microsoft Entra ID yang telah ditetapkan peran Pemilik Data Blob Penyimpanan, dibatasi ke target kontainer, 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.

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

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

    Connect-AzAccount

  2. Jika identitas Anda dikaitkan dengan lebih dari satu langganan, dan Anda tidak diminta untuk memilih langganan, maka atur langganan aktif Anda ke langganan akun penyimpanan yang ingin Anda operasikan. Dalam contoh ini, gantilah nilai <subscription-id> dengan ID langganan Anda.

    Select-AzSubscription -SubscriptionId <subscription-id>

  3. Dapatkan konteks akun penyimpanan.

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

Dapatkan ACL

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

Contoh ini mendapatkan ACL dari direktori akar 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 dari 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 Daftar Kontrol Akses
  • Menetapkan ACL secara rekursif

Mengatur Daftar Kontrol Akses (ACL)

Gunakan cmdlet Set-AzDataLakeGen2ItemAclObject untuk membuat ACL untuk pengguna pemilik, grup pemilik, atau pengguna lain. Kemudian, gunakan cmdlet Update-AzDataLakeGen2Item untuk menerapkan 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 memberikan akses kepada yang lainnya. 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 cmdlet Set-AzDataLakeGen2ItemAclObject untuk menambahkan atau memperbarui entri ACL. Gunakan cmdlet Update-AzDataLakeGen2Item untuk menerapkan 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 aaaaaaaa-bbbb-cccc-1111-222222222222 -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 aaaaaaaa-bbbb-cccc-1111-222222222222 -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 memperbarui ACL secara rekursif dalam batch dengan menentukan ukuran batch, lihat artikel acuan Update-AzDataLakeGen2AclRecursive.

Hapus entri Daftar Kontrol Akses

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 menghapus 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 menghapus ACL secara rekursif 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 mengarahkan entri yang gagal 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 waktu jalan

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 entitas 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

  • Last updated on