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

本文将向您展示如何使用PowerShell获取、设置和更新目录和文件的访问控制列表（ACL）。

你在父目录下创建的新子项会自动继承 ACL。 不过，你也可以递归地在父目录的现有子项上添加、更新和移除 ACL，而无需对每个子项单独做这些更改。

引用 | 提供反馈

先决条件

• Azure 订阅。 有关详细信息，请参阅获取 Azure 试用版。

• 已启用分层命名空间 (HNS) 的存储帐户。 按这些说明创建一个。

• 以下安全权限之一：

  • 一个已预配的 Microsoft Entra ID 安全主体，已被赋予 存储 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 -Environment AzureChinaCloud
   

2. 如果你的身份关联多个订阅，且没有提示选择订阅，请将你的活跃订阅设置为你想使用的存储账户的订阅。 在此示例中，请将 <subscription-id> 占位符值替换为你的订阅 ID。

   Select-AzSubscription -SubscriptionId <subscription-id>
   

3. 获取存储账户上下文。

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

获取访问控制列表

使用 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 条目为对象 ID 为“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。 然后，使用 Set-AzDataLakeGen2ItemAclObject cmdlet 添加或更新 ACL 条目。 使用 Update-AzDataLakeGen2Item cmdlet 提交 ACL。

此示例为用户在 directory 上创建或更新 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 不会产生负面影响。

凭据

建议你预配一个 Microsoft Entra 安全主体，该主体已在目标存储帐户或容器范围内被分配了 存储 Blob 数据所有者 角色。

性能

为了减少延迟，建议你在与存储帐户位于同一区域中的 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)