使用 .NET 來管理 Azure Data Lake Storage Gen2 中的目錄和檔案

發行項
04/09/2024

此文章說明如何使用 .NET，在具有階層命名空間的儲存體帳戶中建立及管理目錄和檔案。

若要了解如何取得、設定及更新目錄和檔案的存取控制清單 (ACL)，請參閱使用 .NET 管理 Azure Data Lake Storage Gen2 中的 ACL。

套件 (NuGet) | 範例 | API 參考 | Gen1 對 Gen2 對應 | 提供意見反應

必要條件

Azure 訂用帳戶。請參閱取得 Azure 免費試用。
已啟用階層命名空間的儲存體帳戶。遵循下列指示以建立帳戶。

設定您的專案

若要開始使用，請安裝 Azure.Storage.Files.DataLake NuGet 套件。

如需如何安裝 NuGet 套件的詳細資訊，請參閱使用 NuGet 套件管理員在 Visual Studio 中安裝和管理套件。

然後，使用陳述式在程式碼檔案頂端加入下列命令。

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

注意

Data Lake 儲存體上的多重通訊協定存取可讓應用程式同時使用 Blob API 和 Data Lake 儲存體 Gen2 API，以使用已啟用階層命名空間（HNS）的記憶體帳戶中的數據。使用 Data Lake 儲存體 Gen2 特有的功能時，例如目錄作業和 ACL，請使用 Data Lake 儲存體 Gen2 API，如本文所示。

選擇要在指定案例中使用的 API 時，請考慮應用程式的工作負載和需求，以及 HNS 對工作負載和應用程式的已知問題和影響。

授權存取權並連線到資料資源

若要使用此文章中的程式碼範例，您必須建立代表儲存體帳戶的已授權 DataLakeServiceClient 執行個體。您可以使用 Microsoft Entra ID、帳戶存取密鑰或共用存取簽章 (SAS) 來授權 DataLakeServiceClient 物件。

您可以使用適用於 .NET 的 Azure 身分識別用戶端程式庫，以 Microsoft Entra ID 驗證應用程式。

建立 DataLakeServiceClient 執行個體，並傳入 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;
}

若要深入了解如何使用 DefaultAzureCredential 來授權存取資料，請參閱如何向 Azure 服務驗證 .NET 應用程式。

若要使用共用存取簽章 (SAS) 權杖，請提供權杖作為字串，並初始化 DataLakeServiceClient 物件。如果您的帳戶 URL 包含 SAS 權杖，請省略認證參數。

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;
}

若要深入了解如何產生和管理 SAS 權杖，請參閱下列文章：

使用共用存取簽章 (SAS) 對 Azure 儲存體資源授與有限存取權

您可以使用帳戶存取金鑰 (共用金鑰) 授權資料存取權。此範例會建立使用帳戶金鑰授權的 DataLakeServiceClient 執行個體。

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;
}

警告

不建議使用「共用金鑰」來進行授權，因為它可能不太安全。為了獲得最佳的安全性，請停用透過「共用金鑰」對您的儲存體帳戶進行授權，如「防止 Azure 儲存體帳戶的共用金鑰授權」中所述。

使用存取金鑰和連接字串應僅限於未存取生產或敏感性資料的初始概念證明應用程式或開發原型。否則，在對 Azure 資源進行驗證時，應一律優先使用 Azure SDK 中所提供的權杖型驗證類別。

Microsoft 建議用戶端使用 Microsoft Entra ID 或共用存取簽章 (SAS) 來授權存取 Azure 儲存體中的資料。如需詳細資訊，請參閱授權資料存取的作業。

建立容器

容器可作為您檔案的檔案系統。您可以使用下列方法建立容器：

DataLakeServiceClient.CreateFileSystem

下列程式碼範例會建立容器，並傳回 DataLakeFileSystemClient 物件以供稍後使用：

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

建立目錄

您可以使用下列方法在容器中建立目錄參考：

DataLakeFileSystemClient.CreateDirectoryAsync

下列程式碼範例將目錄新增至容器，接著新增子目錄並傳回 DataLakeDirectoryClient 物件以供稍後使用：

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

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

您可以使用下列方法來重新命名或移動目錄：

DataLakeDirectoryClient.RenameAsync

將所需目錄的路徑作為參數傳遞。下列程式碼範例示範如何重新命名子目錄：

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));
}

下列程式碼範例示範如何將子目錄從一個目錄移至另一個目錄：

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));
}

將檔案上傳至目錄

您可以使用下列方法將內容上傳至現有或新的檔案：

DataLakeFileClient.UploadAsync

下列程式碼範例示範如何使用 UploadAsync 方法將本機檔案上傳至目錄：

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);
}

您可以使用此方法建立內容並上傳至新檔案，或者將 overwrite 參數設為 true 以覆寫現有檔案。

將資料附加至檔案

您可以使用下列方法將資料上傳附加至檔案：

DataLakeFileClient.AppendAsync

下列程式碼範例示範如何使用以下步驟將資料附加至檔案結尾處：

建立 DataLakeFileClient 物件來代表您正在使用的檔案資源。
使用 DataLakeFileClient.AppendAsync 方法將資料上傳至檔案。
呼叫 DataLakeFileClient.FlushAsync 方法來完成上傳，以將先前上傳的資料寫入檔案。

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);
}

從目錄下載

下列程式碼範例示範如何使用以下步驟將檔案從目錄下載至本機檔案：

建立 DataLakeFileClient 執行個體，代表您要下載的檔案。
使用 DataLakeFileClient.ReadAsync 方法，然後剖析傳回值以取得 Stream 物件。使用任何 .NET 檔案處理 API，將資料流中的位元組儲存至檔案。

此範例會使用 BinaryReader 和 FileStream 將位元組儲存至檔案。

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();
}

列出目錄內容

您可以使用下列方法列出目錄內容並列舉結果：

FileSystemClient.GetPathsAsync

列舉結果中的路徑可能會在擷取值時產生多個要求。

下列程式碼範例會列印位於目錄中的每個檔案名稱：

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;
    }

}

刪除目錄

您可以使用下列方法刪除目錄：

DataLakeDirectoryClient.Delete

下列程式碼範例示範如何刪除目錄：

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

    await directoryClient.DeleteAsync();
}

還原虛刪除的目錄

您可以使用 Azure 儲存體用戶端程式庫來還原虛刪除的目錄。使用下列方法來列出 DataLakeFileSystemClient 執行個體的已刪除路徑：

GetDeletedPathsAsync

使用下列方法來還原虛刪除的目錄：

UndeletePathAsync

下列程式碼範例示範如何列出已刪除的路徑並還原虛刪除的目錄：

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);
}

如果您重新命名包含虛刪除項目的目錄，這些項目就會與目錄中斷連接。如果您想要還原這些項目，您必須將目錄的名稱還原回其原始名稱，或建立使用原始目錄名稱的不同目錄。否則，當您嘗試還原這些虛刪除的項目時，將會收到錯誤。

建立目錄的使用者委派 SAS

若要使用本節中的程式碼範例，請新增下列 using 指示詞：

using Azure.Storage.Sas;

下列程式碼範例示範如何在針對儲存體帳戶啟用階層命名空間時，產生目錄的使用者委派 SAS：

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;
    }
}

下列範例會測試從模擬用戶端應用程式在上一個範例中建立的使用者委派 SAS。如果 SAS 有效，用戶端應用程式就可以列出此目錄的檔案路徑。如果 SAS 無效 (例如 SAS 已過期)，儲存體服務會傳回錯誤碼 403 (禁止)。

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;
        }
    }
}

若要深入了解如何建立使用者委派 SAS，請參閱使用 .NET 建立使用者委派 SAS。

建立目錄的服務 SAS

在啟用階層命名空間的儲存體帳戶中，您可以建立目錄的服務 SAS。若要建立服務 SAS，請確定您已安裝 12.5.0 版或更新版本的 Azure.Storage.Files.DataLake 套件。

下列範例示範如何建立目錄的服務 SAS：

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;
    }
}

若要深入了解如何建立服務 SAS，請參閱使用 .NET 建立服務 SAS。

共用方式為