使用 Azure CLI 管理 Azure Data Lake Storage Gen2 中的 ACL

本文介绍如何使用 Azure CLI 来获取、设置和更新目录和文件的访问控制列表。

ACL 继承已可用于在父目录下创建的新子项。 但是你也可以为父目录的现有子项以递归方式添加、更新和删除 ACL，而不必为每个子项单独进行这些更改。

参考 | 示例 | 提供反馈

先决条件

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

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

• Azure CLI 版本 2.14.0 或更高版本。

• 以下安全权限之一：

  • 一个预配的 Microsoft Entra ID 安全主体，它已分配有存储 Blob 数据所有者角色，并且范围限定为目标容器、存储帐户、父资源组或订阅。

  • 计划将 ACL 设置应用到的目标容器或目录的拥有用户。 为了以递归方式设置 ACL，这包括目标容器或目录中的所有子项。

  • 存储帐户密钥。

确保安装正确版本的 Azure CLI

1. 如果在本地安装了 Azure CLI，请打开命令控制台应用程序，例如 Windows PowerShell。

2. 使用以下命令验证安装的 Azure CLI 版本是否是 2.14.0 或更高版本。

    az --version
   

   如果 Azure CLI 版本低于 2.14.0，则安装更高版本。 有关详细信息，请参阅安装 Azure CLI。

连接到帐户

1. 如果在本地使用 Azure CLI，请运行 login 命令。

   az login
   

   如果 CLI 可以打开默认浏览器，它将这样做并加载 Azure 登录页。

   否则，请在 https://aka.ms/deviceloginchina 处打开浏览器页，然后输入终端中显示的授权代码。 然后，在浏览器中使用帐户凭据登录。

   若要详细了解不同的身份验证方法，请参阅使用 Azure CLI 授权访问 blob 或队列数据。

2. 如果你的标识与多个订阅相关联，请将你的活动订阅设置为将托管静态网站的存储帐户的订阅。

   az account set --subscription <subscription-id>
   

   将 <subscription-id> 占位符值替换为你的订阅 ID。

获取 ACL

使用 az storage fs access show 命令获取目录的 ACL。

下面的示例获取目录的 ACL，然后将 ACL 打印到控制台。

az storage fs access show -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login

使用 az storage fs access show 命令获取文件的访问权限。

下面的示例获取文件的 ACL，然后将 ACL 打印到控制台。

az storage fs access show -p my-directory/upload.txt -f my-file-system --account-name mystorageaccount --auth-mode login

下图显示了获取目录 ACL 后的输出。

在本示例中，负责人用户具有读取、写入和执行权限。 负责人组仅具有读取和执行权限。 有关访问控制列表的详细信息，请参阅 Azure Data Lake Storage Gen2 中的访问控制。

设置 ACL

设置 ACL 时，你将替换整个 ACL，包括其所有条目。 如果要更改安全主体的权限级别，或将新的安全主体添加到 ACL 而不影响其他现有项，则应改为更新 ACL。 若要更新 ACL 而不是替换它，请参阅本文的更新 ACL 部分。

如果选择设置 ACL，则必须为责任用户添加一个条目，为责任组添加一个条目，为所有其他用户添加一个条目。 若要详细了解责任用户、责任组和所有其他用户，请参阅用户和标识。

本节介绍如何完成下列操作：

• 设置 ACL
• 以递归方式设置 ACL

设置 ACL

使用 az storage fs access set 命令设置目录的 ACL。

下面的示例在目录中为负责人用户、负责人组或其他用户设置 ACL，然后将 ACL 打印到控制台。

az storage fs access set --acl "user::rw-,group::rw-,other::-wx" -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login

下面的示例在目录中为负责人用户、负责人组或其他用户设置默认 ACL，然后将 ACL 打印到控制台。

az storage fs access set --acl "default:user::rw-,group::rw-,other::-wx" -p my-directory -f my-file-system --account-name mystorageaccount --auth-mode login

使用 az storage fs access set 命令设置文件的 ACL。

下面的示例在文件中为负责人用户、负责人组或其他用户设置 ACL，然后将 ACL 打印到控制台。

az storage fs access set --acl "user::rw-,group::rw-,other::-wx" -p my-directory/upload.txt -f my-file-system --account-name mystorageaccount --auth-mode login

下图显示了设置文件 ACL 后的输出。

在本示例中，负责人用户和负责人组只有读取和写入权限。 所有其他用户都具有写入和执行权限。 有关访问控制列表的详细信息，请参阅 Azure Data Lake Storage Gen2 中的访问控制。

以递归方式设置 ACL

使用 az storage fs access set-recursive 命令以递归方式设置 ACL。

此示例设置名为 my-parent-directory 的目录的 ACL。 这些条目为所有者用户提供读取、写入和执行权限，仅为负责人组授予读取和执行权限，不为所有其他用户提供任何访问权限。 此示例中的最后一个 ACL 条目为对象 ID 为“xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”的特定用户提供读取和执行权限。

az storage fs access set-recursive --acl "user::rwx,group::r-x,other::---,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

更新 ACL

更新 ACL 时，你将修改 ACL 而非替换 ACL。 例如，你可以将一个新的安全主体添加到 ACL，而不影响 ACL 中列出的其他安全主体。 若要替换 ACL 而不是更新它，请参阅本文的 设置 ACL 部分。

若要更新 ACL，请创建包含要更新的 ACL 条目的一个新的 ACL 对象，然后在“更新 ACL”操作中使用该对象。 不要获取现有 ACL，只需要提供要更新的 ACL 条目。

本节介绍如何完成下列操作：

• 更新 ACL
• 以递归方式更新 ACL

更新 ACL

使用 az storage fs access update-recursive 命令更新文件的 ACL。

此示例以写入权限更新某个 ACL 条目。

az storage fs access update-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx" -p my-parent-directory/myfile.txt -f my-container --account-name mystorageaccount --auth-mode login

若要更新特定组或用户的 ACL，请使用其各自的对象 ID。 例如，group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 或 user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。

以递归方式更新 ACL

使用 az storage fs access update-recursive 命令以递归方式更新 ACL。

此示例以写入权限更新某个 ACL 条目。

az storage fs access update-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

以递归方式删除 ACL 条目

你可以采用递归方式删除一个或多个 ACL 条目。 若要删除 ACL 条目，请为要删除的 ACL 条目创建一个新的 ACL 对象，然后在“删除 ACL”操作中使用该对象。 不要获取现有 ACL，只需要提供要删除的 ACL 条目。

使用 az storage fs access remove-recursive 命令删除 ACL 条目。

此示例从容器的根目录中删除 ACL 条目。

az storage fs access remove-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

从故障中恢复

以递归方式修改 ACL 时，可能会遇到运行时或权限错误。 对于运行时错误，请从头开始重启此过程。 如果安全主体没有足够的权限修改要修改的目录层次结构中的目录或文件的 ACL，则会出现权限错误。 请解决权限问题，然后选择通过使用继续标记从故障点继续执行此过程，或者从头重启此过程。 如果希望从头开始重启，则无需使用继续标记。 你可以重新应用 ACL 条目，而不会产生任何负面影响。

发生故障时，你可以通过将 --continue-on-failure 参数设置为 false 来返回一个延续令牌。 解决错误后，你可以从故障点继续执行该过程，方法是：再次运行命令，然后将 --continuation 参数设置为该延续令牌，

az storage fs access set-recursive --acl "user::rw-,group::r-x,other::---" --continue-on-failure false --continuation xxxxxxx -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login  

如果你希望过程继续完成而不被权限错误中断，则可以指定它。

若要确保过程无中断地完成，请将 --continue-on-failure 参数设置为 true。

az storage fs access set-recursive --acl "user::rw-,group::r-x,other::---" --continue-on-failure true --continuation xxxxxxx -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login  

最佳实践

本部分提供了有关以递归方式设置 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 中的访问控制。

另请参阅

• 示例
• 提供反馈
• 已知问题
• Azure Data Lake Storage Gen2 中的访问控制模型
• Azure Data Lake Storage Gen2 中的访问控制列表 (ACL)