使用 Node.js 中的 JavaScript SDK 來管理 Azure Data Lake Storage Gen2 中的 ACL

此文章說明如何使用 Node.js 來取得、設定及更新目錄和檔案的存取控制清單。

套件 (節點套件管理員) (英文) | 範例 (英文) | 提供意見反應 (英文)

必要條件

• Azure 訂用帳戶。 如需詳細資訊，請參閱取得 Azure 免費試用。

• 已啟用階層命名空間 (HNS) 的儲存體帳戶。 遵循下列指示以建立帳戶。

• Azure CLI 2.6.0 版或更高版本。

• 下列其中一個安全性權限：

  • 已佈建的 Microsoft Entra ID 安全性主體，該主體已獲派儲存體 Blob 資料擁有者角色，且範圍設定為目標容器、儲存體帳戶、上層資源群組或訂用帳戶。

  • 您計劃套用 ACL 設定的目標容器或目錄的擁有使用者。 若要以遞迴方式設定 ACL，這包括目標容器或目錄中的所有子項目。

  • 儲存體帳戶金鑰。

設定您的專案

開啟終端視窗，然後輸入下列命令，以安裝適用於 JavaScript 的 Data Lake 用戶端程式庫。

npm install @azure/storage-file-datalake

將此陳述式放在程式碼檔案的頂端，以匯入 storage-file-datalake 套件。

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

連線到帳戶

若要使用此文章中的程式碼片段，您必須建立代表儲存體帳戶的 DataLakeServiceClient 執行個體。

使用 Microsoft Entra ID 進行連線

注意

如果您使用 Microsoft Entra ID 來授權存取，則需確定已將儲存體 Blob 資料擁有者角色指派給您的安全性主體。 若要深入了解如何套用 ACL 權限以及變更權限的效果，請參閱 Azure Data Lake Storage Gen2 中的存取控制模型 (部分機器翻譯)。

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

首先，您必須將下列其中一個 Azure 角色型存取控制 (Azure RBAC) 角色指派給您的安全性主體：

角色	ACL 設定功能
儲存體 Blob 資料擁有者	帳戶中的所有目錄和檔案。
儲存體 Blob 資料參與者	只有安全性主體所擁有的目錄和檔案。

接著，建立 DataLakeServiceClient 執行個體，並傳入 DefaultAzureCredential 類別的新執行個體。

function GetDataLakeServiceClientAD(accountName) {

  const dataLakeServiceClient = new DataLakeServiceClient(
      `https://${accountName}.dfs.core.windows.net`,
      new DefaultAzureCredential()
  );

  return dataLakeServiceClient;
}

若要深入了解如何使用 DefaultAzureCredential 來授權存取資料，請參閱概觀：使用 Azure SDK 向 Azure 驗證 JavaScript 應用程式。

使用帳戶金鑰來連線

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

function GetDataLakeServiceClient(accountName, accountKey) {

  const sharedKeyCredential =
     new StorageSharedKeyCredential(accountName, accountKey);

  const dataLakeServiceClient = new DataLakeServiceClient(
      `https://${accountName}.dfs.core.windows.net`, sharedKeyCredential);

  return dataLakeServiceClient;
}

警告

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

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

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

取得和設定目錄 ACL

此範例會取得並設定名為 my-directory 之目錄的 ACL。 此範例會為擁有使用者提供讀取、寫入及執行權限，僅為擁有群組提供讀取和執行權限，並為所有其他人員提供讀取權限。

注意

如果您的應用程式使用 Microsoft Entra ID 來授與存取權，則需確定您的應用程式用來授權存取的安全性主體已獲指派儲存體 Blob 資料擁有者角色。 若要深入了解如何套用 ACL 權限以及變更權限的效果，請參閱 Azure Data Lake Storage Gen2 中的存取控制 (部分機器翻譯)。

async function ManageDirectoryACLs(fileSystemClient) {

    const directoryClient = fileSystemClient.getDirectoryClient("my-directory");
    const permissions = await directoryClient.getAccessControl();

    console.log(permissions.acl);

    const acl = [
    {
      accessControlType: "user",
      entityId: "",
      defaultScope: false,
      permissions: {
        read: true,
        write: true,
        execute: true
      }
    },
    {
      accessControlType: "group",
      entityId: "",
      defaultScope: false,
      permissions: {
        read: true,
        write: false,
        execute: true
      }
    },
    {
      accessControlType: "other",
      entityId: "",
      defaultScope: false,
      permissions: {
        read: true,
        write: true,
        execute: false
      }

    }

  ];

  await directoryClient.setAccessControl(acl);
}

您也可以取得和設定容器根目錄的 ACL。 若要取得根目錄，請將空字串 (/) 傳遞到 DataLakeFileSystemClient.getDirectoryClient 方法。

取得和設定檔案 ACL

此範例會取得並設定名為 upload-file.txt 之檔案的 ACL。 此範例會為擁有使用者提供讀取、寫入及執行權限，僅為擁有群組提供讀取和執行權限，並為所有其他人員提供讀取權限。

注意

如果您的應用程式使用 Microsoft Entra ID 來授與存取權，則需確定您的應用程式用來授權存取的安全性主體已獲指派儲存體 Blob 資料擁有者角色。 若要深入了解如何套用 ACL 權限以及變更權限的效果，請參閱 Azure Data Lake Storage Gen2 中的存取控制 (部分機器翻譯)。

async function ManageFileACLs(fileSystemClient) {

  const fileClient = fileSystemClient.getFileClient("my-directory/uploaded-file.txt");
  const permissions = await fileClient.getAccessControl();

  console.log(permissions.acl);

  const acl = [
  {
    accessControlType: "user",
    entityId: "",
    defaultScope: false,
    permissions: {
      read: true,
      write: true,
      execute: true
    }
  },
  {
    accessControlType: "group",
    entityId: "",
    defaultScope: false,
    permissions: {
      read: true,
      write: false,
      execute: true
    }
  },
  {
    accessControlType: "other",
    entityId: "",
    defaultScope: false,
    permissions: {
      read: true,
      write: true,
      execute: false
    }

  }

];

await fileClient.setAccessControl(acl);
}

另請參閱

• 套件 (節點套件管理員)
• 範例
• 提供意見反應
• Azure Data Lake Storage Gen2 中的存取控制模型
• Azure Data Lake Storage Gen2 中的存取控制清單 (ACL)