使用 PowerShell 管理 Azure Data Lake Storage 中的 ACL

本文將教你如何使用 PowerShell 取得、設定及更新目錄和檔案的存取控制清單（ACL）。

你在父目錄下建立的新子項目會自動繼承 ACL。 不過，你也可以遞迴地在父目錄的現有子項目上新增、更新和移除 ACL，而不必對每個子項目單獨做這些變更。

參考 | 提供意見反應

必要條件

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

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

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

  • 一個已配置的 Microsoft Entra ID 安全主體，該主體被指派為 Storage Blob 資料擁有者角色，範圍涵蓋目標容器、儲存帳號、父資源群組或訂閱。

  • 您計劃套用 ACL 設定的目標容器或目錄的擁有者使用者。 若要遞迴設定 ACL，此使用者會包含目標容器或目錄中的所有子項目。

安裝 PowerShell 模組

1. 請使用以下指令確認你安裝的 PowerShell 版本是否為 5.1 或更高版本。

   echo $PSVersionTable.PSVersion.ToString()
   

   要升級您的 PowerShell 版本，請參見升級現有 Windows PowerShell。

2. 安裝 Az.Storage 模組。

   Install-Module Az.Storage -Repository PSGallery -Force  
   

   欲了解更多如何安裝 PowerShell 模組的資訊，請參閱「安裝 Azure PowerShell 模組」。

連線到帳戶

1. 開啟 Windows PowerShell 命令視窗，然後使用 Connect-AzAccount 命令登入您的 Azure 訂用 帳戶 ，然後遵循螢幕上的指示。

   Connect-AzAccount
   

2. 如果你的身份與多個訂閱綁定，且沒有提示選擇訂閱，請將你的有效訂閱設定為你想使用的儲存帳號的訂閱。 在此範例中，使用訂用帳戶識別碼取代 <subscription-id> 預留位置值。

   Select-AzSubscription -SubscriptionId <subscription-id>
   

3. 取得儲存體帳戶脈絡。

   $ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -UseConnectedAccount
   

取得 ACL

使用 Get-AzDataLakeGen2Item Cmdlet 取得目錄或檔案的 ACL。

在 Azure Data Lake Storage 中，容器也稱為檔案系統。 -FileSystem以下範例中使用的參數取用你的容器名稱。

以下範例取得 容器 根目錄的 ACL，然後將 ACL 印出到主控台。

$filesystemName = "my-file-system"
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

以下範例取得 目錄的 ACL，然後將 ACL 列印到主控台。

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

以下範例取得 檔案 的 ACL，然後將 ACL 列印到主控台。

$filePath = "my-directory/upload.txt"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

下圖顯示取得目錄的 ACL 之後的輸出。

在此範例中，擁有使用者具有讀取、寫入和執行權限。 擁有者群組僅有讀取和執行權限。 如需訪問控制清單的詳細資訊，請參閱 Azure Data Lake Storage 中的訪問控制。

設定 ACL

當你 設定 ACL 時，會 取代 整個 ACL，包括其中所有項目。 如果你想更改安全主體的權限層級或新增安全主體到ACL，且不影響其他現有條目，請更新ACL。 若要更新 ACL 而非取代，請參閱本文的更新 ACL 一節。

如果您選擇設定 ACL，則必須為擁有者使用者新增一個項目、為擁有者群組新增一個項目，以及為所有其他使用者新增一個項目。 若要深入了解擁有使用者、擁有群組和所有其他使用者，請參閱使用者和身分識別。

本節說明如何：

• 設定 ACL
• 以遞迴方式設定 ACL

設定 ACL

使用 Set-AzDataLakeGen2ItemAclObject Cmdlet 來為擁有者使用者、擁有者群組或其他使用者建立 ACL。 然後，使用 Update-AzDataLakeGen2Item cmdlet 提交 ACL。

此範例會針對擁有使用者、擁有群組，或其他使用者，在容器的根目錄上設定 ACL，然後將 ACL 列印到主控台。

$filesystemName = "my-file-system"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Acl $acl
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

此範例會在目錄上為擁有者使用者、擁有者群組或其他使用者設定 ACL，然後將 ACL 輸出到主控台。

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

此範例會為檔案的擁有者、所屬群組或其他使用者設定 ACL，然後將 ACL 輸出至主控台。

$filesystemName = "my-file-system"
$filePath = "my-directory/upload.txt"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "-wx" -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath -Acl $acl
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

下圖顯示設定檔案的 ACL 之後的輸出。

在此範例中，擁有者使用者和擁有者群組只有讀取和寫入權限。 所有其他使用者具備寫入和執行權限。 如需訪問控制清單的詳細資訊，請參閱 Azure Data Lake Storage 中的訪問控制。

以遞迴方式設定 ACL

使用 Set-AzDataLakeGen2AclRecursive Cmdlet 以遞迴方式設定 ACL。

此範例會設定名為 my-parent-directory 目錄的 ACL。 這些條目賦予擁有者使用者讀取、寫入和執行權限，擁有群組僅有讀取與執行權限，其他群組則無法存取。 此範例的最後一個 ACL 項目會提供物件識別碼 "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 讀取和執行權限給特定使用者。

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission r-x -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "---" -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission r-x -InputObject $acl

Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

若要查看藉由指定批次大小以遞迴方式批次設定 ACL 的範例，請參閱 Set-AzDataLakeGen2AclRecursive 參考文章。

更新 ACL 清單

當您更新 ACL 時，您會修改 ACL 而不是取代 ACL。 例如，您可以將新的安全性主體新增至 ACL，而不會影響 ACL 中列出的其他安全性主體。 若要取代 ACL 而不是更新，請參閱這篇文章的設定 ACL 一節。

本節說明如何：

• 更新 ACL
• 以遞迴方式更新 ACL

更新 ACL

首先，取得存取控制清單（ACL）。 然後，使用 Set-AzDataLakeGen2ItemAclObject Cmdlet 來新增或更新 ACL 專案。 使用 Update-AzDataLakeGen2Item cmdlet 來提交 ACL。

此範例會為使用者建立或更新目錄上的 ACL。

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = (Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname).ACL
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID aaaaaaaa-bbbb-cccc-1111-222222222222 -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

以遞迴方式更新 ACL

使用 Update-AzDataLakeGen2AclRecursive Cmdlet 以遞迴方式更新 ACL。

此範例會使用寫入權限更新 ACL 項目。

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission rwx

Update-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

若要查看藉由指定批次大小以遞迴方式批次更新 ACL 的範例，請參閱 Update-AzDataLakeGen2AclRecursive 參考文章。

移除 ACL 項目

本節說明如何：

• 移除 ACL 項目
• 以遞迴方式移除 ACL 項目

移除 ACL 項目

此範例會從現有的 ACL 中移除項目。 它會重複使用本文前面各節中建立的 $ctx 儲存體帳戶內容，以及 $acl、$filesystemName 和 $dirname 變數。

$id = "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Create the new ACL object.
[Collections.Generic.List[System.Object]]$aclnew =$acl

foreach ($a in $aclnew)
{
    if ($a.AccessControlType -eq "User" -and $a.DefaultScope -eq $false -and $a.EntityId -eq $id)
    {
        $aclnew.Remove($a);
        break;
    }
}
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $aclnew

以遞迴方式移除 ACL 項目

您能以遞迴方式移除一或多個 ACL 項目。 要移除 ACL 項目，請為你想移除的 ACL 項目建立一個新的 ACL 物件，然後在移除 ACL 操作中使用該物件。 不要取得既有的 ACL，直接提供要移除的 ACL 項目即可。

使用 Remove-AzDataLakeGen2AclRecursive Cmdlet 移除 ACL 項目。

此範例會從容器的根目錄移除 ACL 項目。

$filesystemName = "my-container"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---"

Remove-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName  -Acl $acl

若要查看藉由指定批次大小以遞迴方式批次移除 ACL 的範例，請參閱 Remove-AzDataLakeGen2AclRecursive 參考文章。

從失敗中復原

以遞迴方式修改 ACL 時，您可能會遇到執行階段或權限錯誤。 本節中的範例會重複使用 $ctx 儲存體帳戶內容，以及本文前面各節中建立的 $filesystemName、$dirname 和 $acl 變數。

如果是執行階段錯誤，請從頭開始重新啟動程序。 如果安全主體沒有足夠的權限修改你所修改的目錄階層中目錄或檔案的 ACL，就可能發生權限錯誤。 解決權限問題後，選擇從失敗點使用延續標記恢復程序，或從頭開始。 如果您想要從頭開始重新啟動，就不需要使用接續權杖。 您可以重新套用 ACL 項目，而不會產生負面影響。

此範例將結果回傳給變數，然後將失敗的條目導管至格式化的表格。

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$result
$result.FailedEntries | ft

根據資料表的輸出，您可以修正任何權限錯誤，然後使用接續權杖來繼續執行。

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinuationToken $result.ContinuationToken
$result

若要查看藉由指定批次大小以遞迴方式批次設定 ACL 的範例，請參閱 Set-AzDataLakeGen2AclRecursive 參考文章。

如果你想讓程序不被權限錯誤中斷地完成，可以設定成這樣。

這個範例會使用 ContinueOnFailure 參數，即使作業遇到權限錯誤，還是會繼續執行。

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinueOnFailure

echo "[Result Summary]"
echo "TotalDirectoriesSuccessfulCount: `t$($result.TotalDirectoriesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalFilesSuccessfulCount)"
echo "TotalFailureCount: `t`t`t`t`t$($result.TotalFailureCount)"
echo "FailedEntries:"$($result.FailedEntries | ft)

若要查看藉由指定批次大小以遞迴方式批次設定 ACL 的範例，請參閱 Set-AzDataLakeGen2AclRecursive 參考文章。

最佳作法

本節提供您以遞迴方式設定 ACL 的一些最佳做法指導方針。

處理執行階段錯誤

有許多原因可能會發生執行階段錯誤 (例如：中斷或用戶端連線問題)。 如果您遇到執行階段錯誤，請重新啟動遞迴 ACL 程序。 ACL 可重新套用到項目上，且不會造成負面影響。

處理權限錯誤 (403)

如果您在執行遞迴 ACL 程序時遇到存取控制例外狀況，則您的 AD 安全性主體可能沒有足夠權限可將 ACL 套用至目錄階層中的一或多個子項目。 發生權限錯誤時，程序會停止，並提供接續權杖。 修正權限問題，然後使用接續權杖來處理剩餘的資料集。 已成功處理的目錄和檔案不需要重新處理。 您也可以選擇重新啟動遞迴 ACL 程序。 ACL 可重新套用到項目上，且不會造成負面影響。

認證

建議您在目標儲存體帳戶或容器的範圍中，佈建已獲指派儲存體 Blob 資料擁有者角色的 Microsoft Entra 安全性主體。

效能

若要減少延遲，建議您在位於與儲存體帳戶相同區域中的 Azure 虛擬機器 (VM) 中執行遞迴 ACL 程序。

ACL 限制

您可以套用至目錄或檔案的 ACL 數目上限是 32 個存取 ACL 和 32 個預設 ACL。 如需詳細資訊，請參閱 Azure Data Lake Storage Gen2 中的存取控制。

另請參閱

• 已知問題
• 儲存體 PowerShell Cmdlet
• Azure Data Lake Storage 中的存取控制模型
• Azure Data Lake Storage 中的存取控制清單 (ACL)