Gunakan .NET untuk mengelola direktori dan file di Azure Data Lake Storage Gen2
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.
Membuat kontainer
Kontainer bertindak sebagai sistem file untuk file Anda. Anda dapat membuat kontainer dengan menggunakan metode berikut:
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:
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:
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:
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:
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:
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:
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 :
Gunakan metode berikut untuk memulihkan direktori yang dihapus sementara:
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.