Gunakan .NET untuk mengelola direktori dan file di Azure Data Lake Storage Gen2

Artikel
10/18/2023

Artikel ini menunjukkan cara menggunakan .NET untuk membuat dan mengelola direktori dan file di akun penyimpanan yang memiliki namespace hierarkis.

Untuk mempelajari cara mendapatkan, mengatur, dan memperbarui daftar kontrol akses (ACL) direktori dan file, lihat Gunakan .NET untuk mengelola ACL di Azure Data Lake Storage Gen2.

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 aktif. Ikuti petunjuk berikut untuk membuatnya.

Menyiapkan proyek Anda

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

Untuk informasi selengkapnya tentang cara menginstal paket NuGet, lihat Menginstal dan mengelola paket di Visual Studio menggunakan NuGet Package Manager.

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

using Azure;
using Azure.Storage.Files.DataLake;
using Azure.Storage.Files.DataLake.Models;
using Azure.Storage;
using System.IO;

Catatan

Akses multi-protokol pada Data Lake Storage memungkinkan aplikasi menggunakan API Blob dan API Data Lake Storage Gen2 untuk bekerja dengan data di akun penyimpanan dengan namespace hierarkis (HNS) diaktifkan. Saat bekerja dengan kemampuan yang unik untuk Data Lake Storage Gen2, seperti operasi direktori dan ACL, gunakan API Data Lake Storage Gen2, seperti yang ditunjukkan dalam artikel ini.

Saat memilih API mana yang akan digunakan dalam skenario tertentu, pertimbangkan beban kerja dan kebutuhan aplikasi Anda, bersama dengan masalah yang diketahui dan dampak HNS pada beban kerja dan aplikasi.

Mengotorisasi akses dan menyambungkan ke sumber daya data

Untuk bekerja dengan contoh kode dalam artikel ini, Anda perlu membuat instans DataLakeServiceClient resmi yang mewakili akun penyimpanan. Anda dapat mengotorisasi DataLakeServiceClient objek menggunakan ID Microsoft Entra, kunci akses akun, atau tanda tangan akses bersama (SAS).

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

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.

Untuk menggunakan token tanda tangan akses bersama (SAS), berikan token sebagai string dan inisialisasi objek DataLakeServiceClient . Jika URL akun Anda menyertakan token SAS, hilangkan parameter kredensial.

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

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        new AzureSasCredential(sasToken));

    return dataLakeServiceClient;
}

Untuk mempelajari selengkapnya tentang membuat dan mengelola token SAS, lihat artikel berikut ini:

Berikan akses terbatas ke sumber daya Azure Storage menggunakan tanda tangan akses bersama (SAS)

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.

Membuat kontainer

Kontainer bertindak sebagai sistem file untuk file Anda. Anda dapat membuat kontainer dengan menggunakan metode berikut:

DataLakeServiceClient.CreateFileSystem

Contoh kode berikut membuat kontainer dan mengembalikan objek DataLakeFileSystemClient untuk digunakan nanti:

public async Task<DataLakeFileSystemClient> CreateFileSystem(
    DataLakeServiceClient serviceClient,
    string fileSystemName)
{
    return await serviceClient.CreateFileSystemAsync(fileSystemName);
}

Membuat direktori

Anda dapat membuat referensi direktori dalam kontainer dengan menggunakan metode berikut:

DataLakeFileSystemClient.CreateDirectoryAsync

Contoh kode berikut menambahkan direktori ke kontainer, lalu menambahkan subdirektori dan mengembalikan objek DataLakeDirectoryClient untuk digunakan nanti:

public async Task<DataLakeDirectoryClient> CreateDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName,
    string subdirectoryName)
{
    DataLakeDirectoryClient directoryClient =
        await fileSystemClient.CreateDirectoryAsync(directoryName);

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

Ganti nama atau pindahkan direktori

Anda dapat mengganti nama atau memindahkan direktori dengan menggunakan metode berikut:

DataLakeDirectoryClient.RenameAsync

Lewati jalur direktori yang diinginkan sebagai parameter. Contoh kode berikut menunjukkan cara mengganti nama subdirektori:

public async Task<DataLakeDirectoryClient> RenameDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryPath,
    string subdirectoryName,
    string subdirectoryNameNew)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(string.Join('/', directoryPath, subdirectoryName));

    return await directoryClient.RenameAsync(string.Join('/', directoryPath, subdirectoryNameNew));
}

Contoh kode berikut menunjukkan cara memindahkan subdirektori dari satu direktori ke direktori lain:

public async Task<DataLakeDirectoryClient> MoveDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryPathFrom,
    string directoryPathTo,
    string subdirectoryName)
{
    DataLakeDirectoryClient directoryClient =
         fileSystemClient.GetDirectoryClient(string.Join('/', directoryPathFrom, subdirectoryName));

    return await directoryClient.RenameAsync(string.Join('/', directoryPathTo, subdirectoryName));
}

Unggah file ke direktori

Anda dapat mengunggah konten ke file baru atau yang sudah ada dengan menggunakan metode berikut:

DataLakeFileClient.UploadAsync

Contoh kode berikut menunjukkan cara mengunggah file lokal ke direktori menggunakan UploadAsync metode :

public async Task UploadFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    string localPath)
{
    DataLakeFileClient fileClient = 
        directoryClient.GetFileClient(fileName);

    FileStream fileStream = File.OpenRead(localPath);

    await fileClient.UploadAsync(content: fileStream, overwrite: true);
}

Anda dapat menggunakan metode ini untuk membuat dan mengunggah konten ke file baru, atau Anda dapat mengatur overwrite parameter ke true untuk menimpa file yang ada.

Menambahkan data ke file

Anda dapat mengunggah data untuk ditambahkan ke file dengan menggunakan metode berikut:

DataLakeFileClient.AppendAsync

Contoh kode berikut menunjukkan cara menambahkan data ke akhir file menggunakan langkah-langkah berikut:

Buat objek DataLakeFileClient untuk mewakili sumber daya file yang sedang Anda kerjakan.
Unggah data ke file menggunakan metode DataLakeFileClient.AppendAsync .
Selesaikan unggahan dengan memanggil metode DataLakeFileClient.FlushAsync untuk menulis data yang diunggah sebelumnya ke file.

public async Task AppendDataToFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    Stream stream)
{
    DataLakeFileClient fileClient = 
        directoryClient.GetFileClient(fileName);

    long fileSize = fileClient.GetProperties().Value.ContentLength;

    await fileClient.AppendAsync(stream, offset: fileSize);

    await fileClient.FlushAsync(position: fileSize + stream.Length);
}

Unduh dari direktori

Contoh kode berikut menunjukkan cara mengunduh file dari direktori ke file lokal menggunakan langkah-langkah berikut:

Buat instans DataLakeFileClient untuk mewakili file yang ingin Anda unduh.
Gunakan metode DataLakeFileClient.ReadAsync, lalu uraikan nilai pengembalian untuk mendapatkan objek Stream. Gunakan API pemrosesan file .NET untuk menyimpan byte dari stream ke file.

Contoh ini menggunakan BinaryReader dan FileStream untuk menyimpan byte ke file.

public async Task DownloadFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    string localPath)
{
    DataLakeFileClient fileClient =
        directoryClient.GetFileClient(fileName);

    Response<FileDownloadInfo> downloadResponse = await fileClient.ReadAsync();

    BinaryReader reader = new BinaryReader(downloadResponse.Value.Content);

    FileStream fileStream = File.OpenWrite(localPath);

    int bufferSize = 4096;

    byte[] buffer = new byte[bufferSize];

    int count;

    while ((count = reader.Read(buffer, 0, buffer.Length)) != 0)
    {
        fileStream.Write(buffer, 0, count);
    }

    await fileStream.FlushAsync();

    fileStream.Close();
}

Daftar isi direktori

Anda dapat mencantumkan konten direktori dengan menggunakan metode berikut dan menghitung hasilnya:

FileSystemClient.GetPathsAsync

Menghitung jalur dalam hasil dapat membuat beberapa permintaan ke layanan sambil mengambil nilai.

Contoh kode berikut mencetak nama setiap file yang terletak di direktori:

public async Task ListFilesInDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    IAsyncEnumerator<PathItem> enumerator =
        fileSystemClient.GetPathsAsync(directoryName).GetAsyncEnumerator();

    await enumerator.MoveNextAsync();

    PathItem item = enumerator.Current;

    while (item != null)
    {
        Console.WriteLine(item.Name);

        if (!await enumerator.MoveNextAsync())
        {
            break;
        }

        item = enumerator.Current;
    }

}

Hapus direktori

Anda dapat menghapus direktori dengan menggunakan metode berikut:

DataLakeDirectoryClient.Delete

Contoh kode berikut menunjukkan cara menghapus direktori:

public async Task DeleteDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(directoryName);

    await directoryClient.DeleteAsync();
}

Memulihkan direktori yang dihapus sementara

Anda dapat menggunakan pustaka klien Azure Storage untuk memulihkan direktori yang dihapus sementara. Gunakan metode berikut untuk mencantumkan jalur yang dihapus untuk instans DataLakeFileSystemClient :

GetDeletedPathsAsync

Gunakan metode berikut untuk memulihkan direktori yang dihapus sementara:

UndeletePathAsync

Contoh kode berikut menunjukkan cara mencantumkan jalur yang dihapus dan memulihkan direktori yang dihapus sementara:

public async Task RestoreDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(directoryName);

    // List deleted paths
    List<PathDeletedItem> deletedItems = new List<PathDeletedItem>();
    await foreach (PathDeletedItem deletedItem in fileSystemClient.GetDeletedPathsAsync(directoryName))
    {
        deletedItems.Add(deletedItem);
    }

    // Restore deleted directory
    Response<DataLakePathClient> restoreResponse = await fileSystemClient.UndeletePathAsync(
        deletedItems[0].Path,
        deletedItems[0].DeletionId);
}

Jika Anda mengganti nama direktori yang berisi item yang dihapus sementara, item tersebut akan terputus dari direktori. Jika Anda ingin memulihkan item tersebut, Anda harus mengembalikan nama direktori kembali ke nama aslinya atau membuat direktori terpisah yang menggunakan nama direktori asli. Jika tidak, Anda menerima kesalahan saat mencoba memulihkan item yang dihapus sementara tersebut.

Membuat SAS delegasi pengguna untuk direktori

Untuk bekerja dengan contoh kode di bagian ini, tambahkan direktif berikut using :

using Azure.Storage.Sas;

Contoh kode berikut menunjukkan cara membuat delegasi pengguna SAS untuk direktori saat namespace hierarki diaktifkan untuk akun penyimpanan:

async static Task<Uri> GetUserDelegationSasDirectory(DataLakeDirectoryClient directoryClient)
{
    try
    {
        // Get service endpoint from the directory URI.
        DataLakeUriBuilder dataLakeServiceUri = new DataLakeUriBuilder(directoryClient.Uri)
        {
            FileSystemName = null,
            DirectoryOrFilePath = null
        };

        // Get service client.
        DataLakeServiceClient dataLakeServiceClient =
            new DataLakeServiceClient(dataLakeServiceUri.ToUri(),
                                      new DefaultAzureCredential());

        // Get a user delegation key that's valid for seven days.
        // You can use the key to generate any number of shared access signatures 
        // over the lifetime of the key.
        Azure.Storage.Files.DataLake.Models.UserDelegationKey userDelegationKey =
            await dataLakeServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                                  DateTimeOffset.UtcNow.AddDays(7));

        // Create a SAS token that's valid for seven days.
        DataLakeSasBuilder sasBuilder = new DataLakeSasBuilder()
        {
            // Specify the file system name and path, and indicate that
            // the client object points to a directory.
            FileSystemName = directoryClient.FileSystemName,
            Resource = "d",
            IsDirectory = true,
            Path = directoryClient.Path,
            ExpiresOn = DateTimeOffset.UtcNow.AddDays(7)
        };

        // Specify racwl permissions for the SAS.
        sasBuilder.SetPermissions(
            DataLakeSasPermissions.Read |
            DataLakeSasPermissions.Add |
            DataLakeSasPermissions.Create |
            DataLakeSasPermissions.Write |
            DataLakeSasPermissions.List
            );

        // Construct the full URI, including the SAS token.
        DataLakeUriBuilder fullUri = new DataLakeUriBuilder(directoryClient.Uri)
        {
            Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                                  dataLakeServiceClient.AccountName)
        };

        Console.WriteLine("Directory user delegation SAS URI: {0}", fullUri);
        Console.WriteLine();
        return fullUri.ToUri();
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
        throw;
    }
}

Contoh berikut menguji delegasi pengguna SAS yang dibuat dalam contoh sebelumnya dari aplikasi klien yang disimulasikan. Jika SAS valid, aplikasi klien dapat mencantumkan jalur file untuk direktori ini. Jika SAS tidak valid (misalnya, SAS kedaluwarsa), layanan Penyimpanan mengembalikan kode kesalahan 403 (Terlarang).

private static async Task ListFilesPathsWithDirectorySasAsync(Uri sasUri)
{
    // Try performing an operation using the directory SAS provided.

    // Create a directory client object for listing operations.
    DataLakeDirectoryClient dataLakeDirectoryClient = new DataLakeDirectoryClient(sasUri);

    // List file paths in the directory.
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = dataLakeDirectoryClient.GetPathsAsync(false, false).AsPages();

        // Enumerate the file paths returned with each page.
        await foreach (Page<PathItem> pathPage in resultSegment)
        {
            foreach (PathItem pathItem in pathPage.Values)
            {
                Console.WriteLine("File name: {0}", pathItem.Name);
            }
            Console.WriteLine();
        }

        Console.WriteLine();
        Console.WriteLine("Directory listing operation succeeded for SAS {0}", sasUri);
    }
    catch (RequestFailedException e)
    {
        // Check for a 403 (Forbidden) error. If the SAS is invalid, 
        // Azure Storage returns this error.
        if (e.Status == 403)
        {
            Console.WriteLine("Directory listing operation failed for SAS {0}", sasUri);
            Console.WriteLine("Additional error information: " + e.Message);
            Console.WriteLine();
        }
        else
        {
            Console.WriteLine(e.Message);
            Console.ReadLine();
            throw;
        }
    }
}

Untuk mempelajari selengkapnya tentang membuat SAS delegasi pengguna, lihat Membuat SAS delegasi pengguna dengan .NET.

Buat layanan SAS untuk direktori

Di akun penyimpanan dengan namespace hierarki aktif, Anda dapat membuat layanan SAS untuk direktori. Untuk membuat layanan SAS, pastikan Anda telah menginstal versi 12.5.0 atau yang lebih baru dari paket Azure.Storage.Files.DataLake.

Contoh berikut menunjukkan cara membuat SAS layanan untuk direktori:

private static Uri GetServiceSasUriForDirectory(DataLakeDirectoryClient directoryClient,
                                          string storedPolicyName = null)
{
    if (directoryClient.CanGenerateSasUri)
    {
        // Create a SAS token that's valid for one hour.
        DataLakeSasBuilder sasBuilder = new DataLakeSasBuilder()
        {
            // Specify the file system name, the path, and indicate that
            // the client object points to a directory.
            FileSystemName = directoryClient.FileSystemName,
            Resource = "d",
            IsDirectory = true,
            Path = directoryClient.Path,
        };

        // If no stored access policy is specified, create the policy
        // by specifying expiry and permissions.
        if (storedPolicyName == null)
        {
            sasBuilder.ExpiresOn = DateTimeOffset.UtcNow.AddHours(1);
            sasBuilder.SetPermissions(DataLakeSasPermissions.Read |
                DataLakeSasPermissions.Write |
                DataLakeSasPermissions.List);
        }
        else
        {
            sasBuilder.Identifier = storedPolicyName;
        }

        // Get the SAS URI for the specified directory.
        Uri sasUri = directoryClient.GenerateSasUri(sasBuilder);
        Console.WriteLine("SAS URI for ADLS directory is: {0}", sasUri);
        Console.WriteLine();

        return sasUri;
    }
    else
    {
        Console.WriteLine(@"DataLakeDirectoryClient must be authorized with Shared Key 
                          credentials to create a service SAS.");
        return null;
    }
}

Untuk mempelajari selengkapnya tentang membuat LAYANAN SAS, lihat Membuat LAYANAN SAS dengan .NET.

Bagikan melalui