適用於 JavaScript 的 Azure 記憶體檔案 Data Lake 用戶端連結庫 - 12.22.0 版

發行項
06/13/2024

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

此專案在 JavaScript 中提供用戶端連結庫，可讓您輕鬆地取用 Microsoft Azure 記憶體 Data Lake 服務。

使用此套件中的用戶端連結庫來：

建立/列出/刪除文件系統
建立/讀取/清單/更新/刪除路徑、目錄和檔案

索引鍵連結：

開始使用

目前支援的環境

LTS 版本的 Node.js
Safari、Chrome、Edge 和 Firefox 的最新版本。

如需詳細資訊，請參閱我們的支援原則。

必要條件

安裝套件

安裝適用於 JavaScript 的 Azure 記憶體 Data Lake 用戶端連結庫的慣用方式是使用 npm 套件管理員。在終端機視窗中輸入下列內容：

npm install @azure/storage-file-datalake

驗證用戶端

Azure 記憶體支援數種方式進行驗證。若要與 Azure Data Lake Storage 服務互動，您必須建立記憶體用戶端的實例 - DataLakeServiceClient、 DataLakeFileSystemClient或 DataLakePathClient 例如。請參閱建立 DataLakeServiceClient的範例，以深入了解驗證。

Azure Active Directory
共用金鑰
共用存取簽章

Azure Active Directory

Azure Data Lake Storage 服務支援使用 Azure Active Directory 來驗證其 API 的要求。套件 @azure/identity 提供各種認證類型，可供您的應用程式用來執行此動作。如需詳細資訊和範例，請參閱自述檔 @azure/identity 以開始使用。

相容性

此連結庫與 Node.js 和瀏覽器相容，並針對 LTS Node.js 版本進行驗證， (>=8.16.0) 和最新版的 Chrome、Firefox 和 Edge。

Web 背景工作

此連結庫需要某些 DOM 對象在瀏覽器中使用時全域可用，而網頁背景工作角色預設不會提供這些物件。您必須進行 polyfill，才能讓此連結庫在 Web 背景工作角色中運作。

如需詳細資訊，請參閱我們的檔，以在 Web 背景工作角色中使用適用於 JS 的 Azure SDK

此連結庫取決於下列 DOM API，這些 API 需要在 Web 背景工作角色中使用時載入外部 polyfill：

Node.js 與瀏覽器之間的差異

Node.js 和瀏覽器運行時間之間有差異。開始使用此連結庫時，請留意標示為 「僅適用於 NODE.JS 運行時間」 或 「僅適用於瀏覽器」的 API 或類別。

如果檔案以或 deflate 格式保存壓縮的數據gzip，且其內容編碼方式會據以設定，則下載行為在 Node.js 和瀏覽器之間會有所不同。在 Node.js 記憶體用戶端會下載其壓縮格式的檔案，而在瀏覽器中，數據將會以解壓縮的格式下載。

功能、介面、類別或函式僅適用於 Node.js

根據帳戶名稱和帳戶金鑰的共用金鑰授權
- StorageSharedKeyCredential
共用存取簽章 (SAS) 產生
- generateAccountSASQueryParameters()
- generateDataLakeSASQueryParameters()
平行上傳和下載。請注意， DataLakeFileClient.upload() Node.js 和瀏覽器皆可使用。
- DataLakeFileClient.uploadFile()
- DataLakeFileClient.uploadStream()
- DataLakeFileClient.readToBuffer()
- DataLakeFileClient.readToFile()

功能、介面、類別或函式只能在瀏覽器中使用

JavaScript 套件組合

若要在瀏覽器中使用此用戶端連結庫，您必須先使用套件組合器。如需如何執行這項操作的詳細資訊，請參閱我們的統合檔。

CORS

如果您需要針對瀏覽器進行開發，您必須為記憶體帳戶設定跨原始來源資源分享 (CORS) 規則。移至 Azure 入口網站和 Azure 記憶體總管，尋找您的記憶體帳戶，為 blob/queue/file/table 服務建立新的 CORS 規則， (s) 。

例如，您可以建立下列 CORS 設定以進行偵錯。但請根據生產環境中的需求，仔細自定義設定。

允許的來源： *
允許的動詞：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允許的標頭： *
公開標頭：*
最長 (秒) ：86400

注意：Data Lake 目前共用 Blob 服務的 CORS 設定。

重要概念

Azure Data Lake 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 提供三種類型的資源：

透過使用的記憶體帳戶DataLakeServiceClient
透過使用的記憶體帳戶中的文件系統DataLakeFileSystemClient
透過 DataLakeDirectoryClient 或使用的文件系統路徑DataLakeFileClient

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

注意：此用戶端連結庫僅支援啟用階層命名空間 (HNS) 的記憶體帳戶。

匯入封裝

若要使用用戶端，請將套件匯入您的檔案：

const AzureStorageDataLake = require("@azure/storage-file-datalake");

或者，選擇性地只匯入您需要的類型：

const {
  DataLakeServiceClient,
  StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");

建立 Data Lake Service 用戶端

DataLakeServiceClient需要 Data Lake 服務的 URL 和存取認證。它也選擇性地接受參數中的 options 某些設定。

`@azure/identity`從套件使用`DefaultAzureCredential`

具現化的建議方式 DataLakeServiceClient

通知。 Azure Data Lake 目前會在下列 AAD OAuth 驗證期間重複使用 Blob 相關角色，例如「記憶體 Blob 數據擁有者」。

設定：參考 - 從用戶端應用程式授權存取 blob (data Lake) 和佇列 - /azure/storage/common/storage-auth-aad-app

註冊新的 AAD 應用程式，並授與代表登入使用者存取 Azure 記憶體的許可權。
- 在 azure-portal) - /azure/active-directory/develop/quickstart-register-app 的 Azure Active Directory (中註冊新的應用程式
- 在區 API permissions 段中，選取 Add a permission 並選擇 Microsoft APIs。
- 挑選 Azure Storage 並選取旁邊的 user_impersonation 複選框，然後按下 Add permissions。這可讓應用程式代表登入的使用者存取 Azure 記憶體。
在 Azure 入口網站中使用 RBAC 授與 Azure Data Lake 數據的存取權
- Blob (Data Lake) 和佇列的 RBAC 角色 - /azure/storage/common/storage-auth-aad-rbac-portal。
- 在 Azure 入口網站中，移至您的記憶體帳戶，並從) azure 入口網站中記憶體帳戶左側導覽列中的索引卷標 (，將記憶體 Blob 數據參與者 角色指派給已註冊的 AAD 應用程式 Access control (IAM) 。
範例的環境設定
- 從 AAD 應用程式的 [概觀] 頁面，記下 CLIENT ID 和 TENANT ID。在 [憑證 & 秘密] 索引標籤中，建立秘密並記下。
- 請確定您有AZURE_TENANT_ID、AZURE_CLIENT_ID AZURE_CLIENT_SECRET作為環境變數，以順利執行範例 (可以利用 process.env) 。

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

如需使用此方法的完整範例，請參閱 Azure AD 驗證範例。

[注意 - 上述步驟僅適用於 Node.js]

使用連接字串

或者，您可以具現化 DataLakeServiceClient 使用 fromConnectionString() 靜態方法搭配完整的連接字串做為自變數。 (可以從 azure portal.) [僅適用於 NODE.JS RUNTIME] 取得連接字串

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

with `StorageSharedKeyCredential`

或者，您可以藉由傳遞 account-name 和 account-key 作為自變數來具現化 DataLakeServiceClientStorageSharedKeyCredential 。 (您可以從 azure 入口網站取得帳戶名稱和帳戶密鑰。) [僅適用於 NODE.JS RUNTIME]

const {
  DataLakeServiceClient,
  StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  sharedKeyCredential
);

使用SAS令牌

此外，您也可以使用共用存取簽章 (SAS) 具現化 DataLakeServiceClient 。您可以從 Azure 入口網站取得 SAS 令牌，或使用來產生。generateAccountSASQueryParameters()

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const serviceClientWithSAS = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`
);

建立新的文件系統

使用 DataLakeServiceClient.getFileSystemClient() 取得檔案系統用戶端實例，然後建立新的文件系統資源。

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  // Create a file system
  const fileSystemName = `newfilesystem${new Date().getTime()}`;
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const createResponse = await fileSystemClient.create();
  console.log(`Create file system ${fileSystemName} successfully`, createResponse.requestId);
}

main();

列出檔案系統

使用 DataLakeServiceClient.listFileSystems() 函式來逐一查看檔案系統，並使用新的 for-await-of 語法：

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let fileSystems = datalakeServiceClient.listFileSystems();
  for await (const fileSystem of fileSystems) {
    console.log(`File system ${i++}: ${fileSystem.name}`);
  }
}

main();

或者，不使用 for-await-of：

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let iter = datalakeServiceClient.listFileSystems();
  let fileSystemItem = await iter.next();
  while (!fileSystemItem.done) {
    console.log(`File System ${i++}: ${fileSystemItem.value.name}`);
    fileSystemItem = await iter.next();
  }
}

main();

此外，也支援透過 byPage()列出分頁：

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  for await (const response of datalakeServiceClient
    .listFileSystems()
    .byPage({ maxPageSize: 20 })) {
    if (response.fileSystemItems) {
      for (const fileSystem of response.fileSystemItems) {
        console.log(`File System ${i++}: ${fileSystem.name}`);
      }
    }
  }
}

main();

建立和刪除目錄

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const directoryClient = fileSystemClient.getDirectoryClient("directory");
  await directoryClient.create();
  await directoryClient.delete();
}

main();

建立檔案

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  const content = "Hello world!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = fileSystemClient.getFileClient(fileName);
  await fileClient.create();
  await fileClient.append(content, 0, content.length);
  await fileClient.flush(content.length);
  console.log(`Create and upload file ${fileName} successfully`);
}

main();

列出檔案系統內的路徑

類似於列出文件系統。

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  let i = 1;
  let paths = fileSystemClient.listPaths();
  for await (const path of paths) {
    console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
  }
}

main();

下載檔案並將其轉換成字串 (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const fileClient = fileSystemClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadResponse.readableStreamBody
  const downloadResponse = await fileClient.read();
  const downloaded = await streamToBuffer(downloadResponse.readableStreamBody);
  console.log("Downloaded file content:", downloaded.toString());

  // [Node.js only] A helper method used to read a Node.js readable stream into a Buffer.
  async function streamToBuffer(readableStream) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on("end", () => {
        resolve(Buffer.concat(chunks));
      });
      readableStream.on("error", reject);
    });
  }
}

main();

下載檔案並將其轉換成字串 (瀏覽器)

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const sas="<sas token>"

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`
);

const fileSystemName = "<file system name>";
const fileName = "<file name>"

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const fileClient = fileSystemClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadResponse.contentAsBlob
  const downloadResponse = await fileClient.read();
  const downloaded = await blobToString(await downloadResponse.contentAsBlob);
  console.log(
    "Downloaded file content",
    downloaded
  );

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob: Blob): Promise<string> {
    const fileReader = new FileReader();
    return new Promise<string>((resolve, reject) => {
      fileReader.onloadend = (ev: any) => {
        resolve(ev.target!.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

疑難排解

啟用記錄有助於找出失敗的相關實用資訊。若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

後續步驟

其他程式代碼範例：

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

曝光數

共用方式為

適用於 JavaScript 的 Azure 記憶體檔案 Data Lake 用戶端連結庫 - 12.22.0 版

開始使用

目前支援的環境

必要條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

Node.js 與瀏覽器之間的差異

功能、介面、類別或函式僅適用於 Node.js

功能、介面、類別或函式只能在瀏覽器中使用

JavaScript 套件組合

CORS

重要概念

範例

匯入封裝

建立 Data Lake Service 用戶端

`@azure/identity`從套件使用`DefaultAzureCredential`

使用連接字串

with `StorageSharedKeyCredential`

使用SAS令牌

建立新的文件系統

列出檔案系統

建立和刪除目錄

建立檔案

列出檔案系統內的路徑

下載檔案並將其轉換成字串 (Node.js)

下載檔案並將其轉換成字串 (瀏覽器)

疑難排解

後續步驟

參與

意見反應

其他資源

共用方式為

適用於 JavaScript 的 Azure 記憶體檔案 Data Lake 用戶端連結庫 - 12.22.0 版

開始使用

目前支援的環境

必要條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

Node.js 與瀏覽器之間的差異

功能、介面、類別或函式僅適用於 Node.js

功能、介面、類別或函式只能在瀏覽器中使用

JavaScript 套件組合

CORS

重要概念

範例

匯入封裝

建立 Data Lake Service 用戶端

@azure/identity從套件使用DefaultAzureCredential

使用連接字串

with StorageSharedKeyCredential

使用SAS令牌

建立新的文件系統

列出檔案系統

建立和刪除目錄

建立檔案

列出檔案系統內的路徑

下載檔案並將其轉換成字串 (Node.js)

下載檔案並將其轉換成字串 (瀏覽器)

疑難排解

後續步驟

參與

意見反應

其他資源

`@azure/identity`從套件使用`DefaultAzureCredential`

with `StorageSharedKeyCredential`