Gunakan .NET untuk mengelola ACL di Azure Data Lake Storage Gen2

Artikel
06/01/2023

Artikel ini memperlihatkan kepada Anda cara menggunakan .NET 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 (NuGet) | Sampel | Referensi API | Pemetaan Gen1 ke Gen2 | Beri Umpan Balik

Prasyarat

Langganan Azure. Lihat Mendapatkan 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

Untuk memulai, instal paket NuGet Azure.Storage.Files.DataLake.

Buka jendela perintah (Misalnya: Windows PowerShell).

Dari direktori proyek Anda, instal paket pratinjau Azure.Storage.Files.DataLake dengan menggunakan perintah dotnet add package.

dotnet add package Azure.Storage.Files.DataLake -v 12.6.0 -s https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-net/nuget/v3/index.json

Lalu, tambahkan pernyataan ini ke bagian atas file kode Anda.

using Azure;
using Azure.Core;
using Azure.Storage;
using Azure.Storage.Files.DataLake;
using Azure.Storage.Files.DataLake.Models;
using System.Collections.Generic;
using System.Threading.Tasks;

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 .NET untuk mengautentikasi aplikasi Anda dengan ID Microsoft Entra.

Setelah Anda menginstal paket, tambahkan ini menggunakan pernyataan ke bagian atas file kode Anda.

using Azure.Identity;

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 .

public static DataLakeServiceClient GetDataLakeServiceClient(string accountName)
{
    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        new DefaultAzureCredential());

    return dataLakeServiceClient;
}

Untuk mempelajari selengkapnya tentang menggunakan DefaultAzureCredential untuk mengotorisasi akses ke data, lihat Cara mengautentikasi aplikasi .NET dengan layanan Azure.

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.

public static DataLakeServiceClient GetDataLakeServiceClient(string accountName, string accountKey)
{
    StorageSharedKeyCredential sharedKeyCredential =
        new StorageSharedKeyCredential(accountName, accountKey);

    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        sharedKeyCredential);

    return dataLakeServiceClient;
}

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.

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:

Atur ACL direktori
Mengatur ACL file
Menetapkan ACL secara rekursif

Atur ACL direktori

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

Contoh ini mendapatkan dan menetapkan ACL direktori bernama my-directory. String user::rwx,group::r-x,other::rw- 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.

public async Task ManageDirectoryACLs(DataLakeFileSystemClient fileSystemClient)
{
    DataLakeDirectoryClient directoryClient =
      fileSystemClient.GetDirectoryClient("");

    PathAccessControl directoryAccessControl =
        await directoryClient.GetAccessControlAsync();

    foreach (var item in directoryAccessControl.AccessControlList)
    {
        Console.WriteLine(item.ToString());
    }

    IList<PathAccessControlItem> accessControlList
        = PathAccessControlExtensions.ParseAccessControlList
        ("user::rwx,group::r-x,other::rw-");

    directoryClient.SetAccessControlList(accessControlList);

}

Anda juga bisa mendapatkan dan mengatur ACL direktori root kontainer. Untuk mendapatkan direktori root, lewati string kosong ("") ke dalam metode DataLakeFileSystemClient.GetDirectoryClient.

Mengatur ACL file

Dapatkan daftar kontrol akses (ACL) file dengan memanggil metode DataLakeFileClient.GetAccessControlAsync dan atur ACL dengan memanggil DataLakeFileClient.SetAccessControlList.

Contoh ini mendapatkan dan menetapkan ACL direktori bernama my-file.txt. String user::rwx,group::r-x,other::rw- 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.

public async Task ManageFileACLs(DataLakeFileSystemClient fileSystemClient)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient("my-directory");

    DataLakeFileClient fileClient =
        directoryClient.GetFileClient("hello.txt");

    PathAccessControl FileAccessControl =
        await fileClient.GetAccessControlAsync();

    foreach (var item in FileAccessControl.AccessControlList)
    {
        Console.WriteLine(item.ToString());
    }

    IList<PathAccessControlItem> accessControlList
        = PathAccessControlExtensions.ParseAccessControlList
        ("user::rwx,group::r-x,other::rw-");

    fileClient.SetAccessControlList(accessControlList);
}

Menetapkan ACL secara rekursif

Atur ACL secara rekursif dengan memanggil metode DataLakeDirectoryClient.SetAccessControlRecursiveAsync. Luluskan Daftar PathAccessControlItem ke metode ini. Setiap PathAccessControlItem mendefinisikan entri ACL.

Jika Anda ingin mengatur entri ACL default, maka Anda dapat mengatur properti PathAccessControlItem.DefaultScope dari PathAccessControlItem ke true.

Contoh ini mengatur ACL direktori dengan nama my-parent-directory. Metode ini menerima parameter boolean dengan nama isDefaultScope yang menentukan apakah akan mengatur ACL default. Parameter itu digunakan dalam konstruktor PathAccessControlItem. Entri ACL memberi pengguna pemilik izin baca, tulis, dan eksekusi, memberi grup pemilik hanya izin baca dan eksekusi, dan tidak memberi akses ke semua orang lain. Entri ACL terakhir dalam contoh ini memberi pengguna tertentu dengan izin baca dan jalankan ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx objek.

    public async Task SetACLRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
    DataLakeDirectoryClient directoryClient =
        serviceClient.GetFileSystemClient("my-container").
            GetDirectoryClient("my-parent-directory");

    List<PathAccessControlItem> accessControlList =
        new List<PathAccessControlItem>()
    {
new PathAccessControlItem(AccessControlType.User,
    RolePermissions.Read |
    RolePermissions.Write |
    RolePermissions.Execute, isDefaultScope),

new PathAccessControlItem(AccessControlType.Group,
    RolePermissions.Read |
    RolePermissions.Execute, isDefaultScope),

new PathAccessControlItem(AccessControlType.Other,
    RolePermissions.None, isDefaultScope),

new PathAccessControlItem(AccessControlType.User,
    RolePermissions.Read |
    RolePermissions.Execute, isDefaultScope,
    entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
    };

    await directoryClient.SetAccessControlRecursiveAsync
        (accessControlList, null);
}

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 direktori dengan memangil metode DataLakeDirectoryClient.GetAccessControlAsync. Salin daftar entri ACL ke Daftar objek PathAccessControl baru. Lalu temukan entri yang ingin Anda perbarui lalu ganti di dalam daftar. Atur ACL dengan memanggil metode DataLakeDirectoryClient.SetAccessControlList.

Contoh ini memperbarui ACL root kontainer dengan mengganti entri ACL untuk semua pengguna lain.

public async Task UpdateDirectoryACLs(DataLakeFileSystemClient fileSystemClient)
{
    DataLakeDirectoryClient directoryClient =
      fileSystemClient.GetDirectoryClient("");

    PathAccessControl directoryAccessControl =
        await directoryClient.GetAccessControlAsync();

    List<PathAccessControlItem> accessControlListUpdate 
        = (List<PathAccessControlItem>)directoryAccessControl.AccessControlList;

    int index = -1;

    foreach (var item in accessControlListUpdate)
    {
        if (item.AccessControlType == AccessControlType.Other)
        {
            index = accessControlListUpdate.IndexOf(item);
            break;
        }
    }

    if (index > -1)
    {
        accessControlListUpdate[index] = new PathAccessControlItem(AccessControlType.Other,
        RolePermissions.Read |
        RolePermissions.Execute);

        directoryClient.SetAccessControlList(accessControlListUpdate);
    }

   }

Perbarui ACL secara berulang

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.UpdateAccessControlRecursiveAsync. Luluskan Daftar PathAccessControlItem ke metode ini. Setiap PathAccessControlItem mendefinisikan entri ACL.

Jika Anda ingin mengatur entri ACL default, maka Anda dapat mengatur properti PathAccessControlItem.DefaultScope dari PathAccessControlItem ke true.

Contoh ini memperbarui entri ACL dengan izin tulis. Metode ini menerima parameter boolean bernama isDefaultScope yang menentukan apakah akan memperbarui ACL default. Parameter itu digunakan dalam konstruktor PathAccessControlItem.

public async Task UpdateACLsRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
    DataLakeDirectoryClient directoryClient =
        serviceClient.GetFileSystemClient("my-container").
        GetDirectoryClient("my-parent-directory");

    List<PathAccessControlItem> accessControlListUpdate =
        new List<PathAccessControlItem>()
    {
new PathAccessControlItem(AccessControlType.User,
    RolePermissions.Read |
    RolePermissions.Write |
    RolePermissions.Execute, isDefaultScope,
    entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
    };

    await directoryClient.UpdateAccessControlRecursiveAsync
        (accessControlListUpdate, null);

}

Hapus entri ACL

Anda bisa menghapus satu atau beberapa entri ACL. Bagian ini memperlihatkan kepada Anda cara:

Menghapus entri ACL
Hapus entri ACL secara rekursif

Menghapus entri ACL

Pertama, dapatkan ACL direktori dengan memangil metode DataLakeDirectoryClient.GetAccessControlAsync. Salin daftar entri ACL ke Daftar objek PathAccessControl baru. Kemudian temukan entri yang ingin Anda hapus dan panggil metode Hapus milik koleksi. Atur ACL yang diperbarui dengan memanggil metode DataLakeDirectoryClient.SetAccessControlList.

Contoh ini memperbarui ACL root kontainer dengan mengganti entri ACL untuk semua pengguna lain.

public async Task RemoveDirectoryACLEntry
    (DataLakeFileSystemClient fileSystemClient)
{
    DataLakeDirectoryClient directoryClient =
      fileSystemClient.GetDirectoryClient("");

    PathAccessControl directoryAccessControl =
        await directoryClient.GetAccessControlAsync();

    List<PathAccessControlItem> accessControlListUpdate
        = (List<PathAccessControlItem>)directoryAccessControl.AccessControlList;

    PathAccessControlItem entryToRemove = null;

    foreach (var item in accessControlListUpdate)
    {
        if (item.EntityId == "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
        {
            entryToRemove = item;
            break;
        }
    }

    if (entryToRemove != null)
    {
        accessControlListUpdate.Remove(entryToRemove);
        directoryClient.SetAccessControlList(accessControlListUpdate);
    }

}

Hapus entri ACL secara rekursif

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.RemoveAccessControlRecursiveAsync. Luluskan Daftar PathAccessControlItem ke metode ini. Setiap PathAccessControlItem mendefinisikan entri ACL.

Jika Anda ingin mengatur entri ACL default, maka Anda dapat mengatur properti PathAccessControlItem.DefaultScope dari PathAccessControlItem ke true.

Contoh ini menghapus entri ACL dari ACL direktori dengan nama my-parent-directory. Metode ini menerima parameter boolean dengan nama isDefaultScope yang menentukan apakah akan menghapus entri dari ACL default. Parameter itu digunakan dalam konstruktor PathAccessControlItem.

public async Task RemoveACLsRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
    DataLakeDirectoryClient directoryClient =
        serviceClient.GetFileSystemClient("my-container").
            GetDirectoryClient("my-parent-directory");

    List<RemovePathAccessControlItem> accessControlListForRemoval =
        new List<RemovePathAccessControlItem>()
        {
    new RemovePathAccessControlItem(AccessControlType.User, isDefaultScope,
    entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
        };

    await directoryClient.RemoveAccessControlRecursiveAsync
        (accessControlListForRemoval, null);

}

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 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 null untuk parameter token kelanjutan.

public async Task<string> ResumeAsync(DataLakeServiceClient serviceClient,
    DataLakeDirectoryClient directoryClient,
    List<PathAccessControlItem> accessControlList,
    string continuationToken)
{
    try
    {
        var accessControlChangeResult =
            await directoryClient.SetAccessControlRecursiveAsync(
                accessControlList, continuationToken: continuationToken, null);

        if (accessControlChangeResult.Value.Counters.FailedChangesCount > 0)
        {
            continuationToken =
                accessControlChangeResult.Value.ContinuationToken;
        }

        return continuationToken;
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
        return continuationToken;
    }

}

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

Untuk memastikan bahwa proses selesai tanpa gangguan, lewati objek AccessControlChangedOptions dan atur properti ContinueOnFailure dari objek tersebut ke true.

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.

public async Task ContinueOnFailureAsync(DataLakeServiceClient serviceClient,
    DataLakeDirectoryClient directoryClient,
    List<PathAccessControlItem> accessControlList)
{
    var accessControlChangeResult =
        await directoryClient.SetAccessControlRecursiveAsync(
            accessControlList, null, new AccessControlChangeOptions()
            { ContinueOnFailure = true });

    var counters = accessControlChangeResult.Value.Counters;

    Console.WriteLine("Number of directories changed: " +
        counters.ChangedDirectoriesCount.ToString());

    Console.WriteLine("Number of files changed: " +
        counters.ChangedFilesCount.ToString());

    Console.WriteLine("Number of failures: " +
        counters.FailedChangesCount.ToString());
}

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.

Gunakan .NET untuk mengelola ACL di Azure Data Lake Storage Gen2

Prasyarat

Menyiapkan proyek Anda

Sambungkan ke akun

Koneksi dengan menggunakan ID Microsoft Entra

Sambungkan dengan menggunakan kunci akun

Atur ACL

Atur ACL direktori

Mengatur ACL file

Menetapkan ACL secara rekursif

Perbarui ACL

Perbarui ACL

Perbarui ACL secara berulang

Hapus entri ACL

Menghapus entri ACL

Hapus entri ACL secara rekursif

Memulihkan dari kegagalan

Praktik Terbaik

Menangani kesalahan runtime bahasa umum

Menangani kesalahan izin (403)

Kredensial

Performa

Batas ACL

Baca juga

Sumber Daya Tambahan: