適用于 .NET 的 Azure 儲存體檔案 Data Lake 用戶端程式庫 - 12.13.1 版

發行項
04/03/2023

伺服器版本：2021-02-12、2020-12-06、2020-10-02、 2020-08-04、2020-06-12、2020-04-08、2020-02-10、2019-12-12、2019-07-07 和 2019-02-02

Azure Data Lake 內含的功能可讓開發人員、資料科學家以及分析師的工作更加輕鬆，範圍包括儲存任何大小、形狀及速率的資料，以及跨各平台和語言進行任何類型的處理及分析。其移除了內嵌及儲存所有資料所帶來的複雜性，同時可讓啟動並執行批次、串流及互動式分析變得更加迅速。

| 原始程式碼套件 (NuGet) | API 參考檔 | REST API 檔 | 產品檔

開始使用

安裝套件

使用 NuGet安裝適用于 .NET 的 Azure 儲存體檔案 Data Lake 用戶端程式庫：

dotnet add package Azure.Storage.Files.DataLake

必要條件

您需要 Azure 訂用帳戶和儲存體帳戶才能使用此套件。

若要建立新的儲存體帳戶，您可以使用Azure 入口網站、Azure PowerShell或Azure CLI。以下是使用 Azure CLI 的範例：

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

重要概念

DataLake Storage Gen2 的設計目的是：

服務數 PB 的資訊，同時維持數百 GB 的輸送量
可讓您輕鬆地管理大量資料

DataLake Storage Gen2 的主要功能包括：

Hadoop 相容存取
POSIX 許可權的超集合
在低成本儲存體容量和交易方面符合成本效益
巨量資料分析的優化驅動程式

Data Lake Storage Gen2 的基礎部分是新增至 Blob 儲存體的階層命名空間。階層命名空間會將物件/檔案組織成目錄階層，讓資料存取更有效率。

以往雲端式分析必須在效能、管理及安全性方面妥協。 Data Lake Storage Gen2 透過下列方式解決這些方面的問題：

效能經過最佳化，因為您不需要複製或轉換資料作為分析的必要條件。階層命名空間大幅提高目錄管理作業的效能，從而提高整體作業效能。
管理更容易，因為您可以透過目錄和子目錄整理和操作檔案。
安全性是強制的，因為您可以在目錄或個人檔案上定義 POSIX 權限。
符合成本效益，因為 Data Lake Storage Gen2 建立在低成本的 Azure Blob 儲存體上。額外功能進一步降低了在 Azure 上執行巨量資料分析的擁有權總成本。

Data Lake Storage Gen2提供兩種類型的資源：

透過 'DataLakeFileSystemClient' 使用的檔案系統
透過 'DataLakeFileClient' 或 'DataLakeDirectoryClient' 使用的路徑

ADLS Gen2	Blob
Filesystem	容器
路徑 (檔案或目錄)	Blob

注意：此用戶端程式庫不支援 (HNS) 停用儲存體帳戶的階層命名空間。

執行緒安全

我們保證所有用戶端實例方法都是安全線程，且彼此獨立 (指導方針) 。這可確保重複使用用戶端實例的建議一律是安全的，即使是跨執行緒也一樣。

其他概念

範例

建立 DataLakeServiceClient

StorageSharedKeyCredential sharedKeyCredential = new StorageSharedKeyCredential(storageAccountName, storageAccountKey);

// Create DataLakeServiceClient using StorageSharedKeyCredentials
DataLakeServiceClient serviceClient = new DataLakeServiceClient(serviceUri, sharedKeyCredential);

建立 DataLakeFileSystemClient

StorageSharedKeyCredential sharedKeyCredential = new StorageSharedKeyCredential(storageAccountName, storageAccountKey);

// Create DataLakeServiceClient using StorageSharedKeyCredentials
DataLakeServiceClient serviceClient = new DataLakeServiceClient(serviceUri, sharedKeyCredential);

// Create a DataLake Filesystem
DataLakeFileSystemClient filesystem = serviceClient.GetFileSystemClient(Randomize("sample-filesystem"));
filesystem.Create();

建立 DataLakeDirectoryClient

StorageSharedKeyCredential sharedKeyCredential = new StorageSharedKeyCredential(storageAccountName, storageAccountKey);

// Create DataLakeServiceClient using StorageSharedKeyCredentials
DataLakeServiceClient serviceClient = new DataLakeServiceClient(serviceUri, sharedKeyCredential);

// Get a reference to a filesystem named "sample-filesystem-append" and then create it
DataLakeFileSystemClient filesystem = serviceClient.GetFileSystemClient(Randomize("sample-filesystem-append"));
filesystem.Create();

// Create
DataLakeDirectoryClient directory = filesystem.GetDirectoryClient(Randomize("sample-file"));
directory.Create();

建立 DataLakeFileClient

從 DataLakeDirectoryClient 建立 DataLakeFileClient

// Create a DataLake Directory
DataLakeDirectoryClient directory = filesystem.CreateDirectory(Randomize("sample-directory"));
directory.Create();

// Create a DataLake File using a DataLake Directory
DataLakeFileClient file = directory.GetFileClient(Randomize("sample-file"));
file.Create();

從 DataLakeFileSystemClient 建立 DataLakeFileClient

// Create a DataLake Filesystem
DataLakeFileSystemClient filesystem = serviceClient.GetFileSystemClient(Randomize("sample-filesystem"));
filesystem.Create();

// Create a DataLake file using a DataLake Filesystem
DataLakeFileClient file = filesystem.GetFileClient(Randomize("sample-file"));
file.Create();

將資料附加至 DataLake 檔案

// Create a file
DataLakeFileClient file = filesystem.GetFileClient(Randomize("sample-file"));
file.Create();

// Append data to the DataLake File
file.Append(File.OpenRead(sampleFilePath), 0);
file.Flush(SampleFileContent.Length);

從 DataLake 檔案讀取資料

Response<FileDownloadInfo> fileContents = file.Read();

列出/周遊 DataLake 檔案系統

foreach (PathItem pathItem in filesystem.GetPaths())
{
    names.Add(pathItem.Name);
}

設定 DataLake 檔案的許可權

// Create a DataLake file so we can set the Access Controls on the files
DataLakeFileClient fileClient = filesystem.GetFileClient(Randomize("sample-file"));
fileClient.Create();

// Set the Permissions of the file
PathPermissions pathPermissions = PathPermissions.ParseSymbolicPermissions("rwxrwxrwx");
fileClient.SetPermissions(permissions: pathPermissions);

在 DataLake 檔案上設定存取控制 (ACL)

// Create a DataLake file so we can set the Access Controls on the files
DataLakeFileClient fileClient = filesystem.GetFileClient(Randomize("sample-file"));
fileClient.Create();

// Set Access Control List
IList<PathAccessControlItem> accessControlList
    = PathAccessControlExtensions.ParseAccessControlList("user::rwx,group::r--,mask::rwx,other::---");
fileClient.SetAccessControlList(accessControlList);

在 DataLake 檔案上取得存取控制 (ACL)

// Get Access Control List
PathAccessControl accessControlResponse = fileClient.GetAccessControl();

重新命名 DataLake 檔案

DataLakeFileClient renamedFileClient = fileClient.Rename("sample-file2");

重新命名 DataLake 目錄

DataLakeDirectoryClient renamedDirectoryClient = directoryClient.Rename("sample-directory2");

取得 DataLake 檔案上的屬性

// Get Properties on a File
PathProperties filePathProperties = fileClient.GetProperties();

取得 DataLake Directory 上的屬性

// Get Properties on a Directory
PathProperties directoryPathProperties = directoryClient.GetProperties();

疑難排解

所有檔案 DataLake 服務作業都會在失敗時擲回RequestFailedException，但很有説明ErrorCode 。這些錯誤有許多是可復原的。

下一步

開始使用我們的 DataLake 範例：

Hello World：附加、讀取和列出 DataLake 檔案 (或非同步)
驗證：使用公用存取、共用金鑰、共用存取簽章和 Azure Active Directory 進行驗證。

參與

如需建置、測試和參與此程式庫的詳細資訊，請參閱儲存體 CONTRIBUTING.md 。

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資訊，請造訪 cla.microsoft.com。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

曝光數

共用方式為