使用 PowerShell 管理 Azure Data Lake Storage Gen2 中的目录、文件和 ACLUse PowerShell to manage directories, files, and ACLs in Azure Data Lake Storage Gen2

• 09/28/2020
• • 

本文介绍如何使用 PowerShell 在启用了分层命名空间 (HNS) 的存储帐户中创建和管理目录、文件与权限。This article shows you how to use PowerShell to create and manage directories, files, and permissions in storage accounts that has hierarchical namespace (HNS) enabled.

引用 | 提供反馈 |Reference | Give feedback |

先决条件Prerequisites

安装 PowerShell 模块Install the PowerShell module

1. 使用以下命令验证安装的 PowerShell 版本是否为 5.1 或以上。Verify that the version of PowerShell that have installed is 5.1 or higher by using the following command.

   echo $PSVersionTable.PSVersion.ToString() 
   

   若要升级 PowerShell 版本，请参阅升级现有的 Windows PowerShellTo upgrade your version of PowerShell, see Upgrading existing Windows PowerShell

2. 安装 Az.Storage 模块。Install Az.Storage module.

   Install-Module Az.Storage -Repository PSGallery -Force  
   

   有关如何安装 PowerShell 模块的详细信息，请参阅安装 Azure PowerShell 模块For more information about how to install PowerShell modules, see Install the Azure PowerShell module

连接到帐户Connect to the account

打开 Windows PowerShell 命令窗口，使用 Connect-AzAccount 命令登录到 Azure 订阅，然后按照屏幕上的指示进行操作。Open a Windows PowerShell command window, and then sign in to your Azure subscription with the Connect-AzAccount command and follow the on-screen directions.

Connect-AzAccount -Environment AzureChinaCloud

如果你的标识已关联到多个订阅，请将活动订阅设置为要在其中创建和管理目录的存储帐户的订阅。If your identity is associated with more than one subscription, then set your active subscription to subscription of the storage account that you want create and manage directories in. 在此示例中，请将 <subscription-id> 占位符值替换为你的订阅 ID。In this example, replace the <subscription-id> placeholder value with the ID of your subscription.

Select-AzSubscription -SubscriptionId <subscription-id>

接下来，选择希望命令如何获取存储帐户的授权。Next, choose how you want your commands to obtain authorization to the storage account.

选项 1：使用 Azure Active Directory (AD) 获取授权Option 1: Obtain authorization by using Azure Active Directory (AD)

如果使用此方法，系统可确保用户帐户具有适当的基于角色的访问控制 (RBAC) 分配和 ACL 权限。With this approach, the system ensures that your user account has the appropriate role-based access control (RBAC) assignments and ACL permissions.

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

选项 2：使用存储帐户密钥获取授权Option 2: Obtain authorization by using the storage account key

如果使用此方法，系统不会检查 RBAC 或 ACL 权限。With this approach, the system doesn't check RBAC or ACL permissions.

$storageAccount = Get-AzStorageAccount -ResourceGroupName "<resource-group-name>" -AccountName "<storage-account-name>"
$ctx = $storageAccount.Context

创建容器Create a container

容器充当文件的文件系统。A container acts as a file system for your files. 可以使用 New-AzStorageContainer cmdlet 创建一个文件系统。You can create one by using the New-AzStorageContainer cmdlet.

此示例创建一个名为 my-file-system 的容器。This example creates a container named my-file-system.

$filesystemName = "my-file-system"
New-AzStorageContainer -Context $ctx -Name $filesystemName

创建目录Create a directory

使用 New-AzDataLakeGen2Item cmdlet 创建目录引用。Create a directory reference by using the New-AzDataLakeGen2Item cmdlet.

此示例将名为 my-directory 的目录添加到容器中。This example adds a directory named my-directory to a container.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
New-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Directory

此示例添加相同的目录，但同时还会设置权限、umask、属性值和元数据值。This example adds the same directory, but also sets the permissions, umask, property values, and metadata values.

$dir = New-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Directory -Permission rwxrwxrwx -Umask ---rwx---  -Property @{"ContentEncoding" = "UDF8"; "CacheControl" = "READ"} -Metadata  @{"tag1" = "value1"; "tag2" = "value2" }

显示目录属性Show directory properties

此示例使用 Get-AzDataLakeGen2Item cmdlet 获取目录，然后将属性值输出到控制台。This example gets a directory by using the Get-AzDataLakeGen2Item cmdlet, and then prints property values to the console.

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

重命名或移动目录Rename or move a directory

使用 Move-AzDataLakeGen2Item cmdlet 重命名或移动目录。Rename or move a directory by using the Move-AzDataLakeGen2Item cmdlet.

此示例将目录的名称 my-directory 重命名为 my-new-directory。This example renames a directory from the name my-directory to the name my-new-directory.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dirname2 = "my-new-directory/"
Move-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -DestFileSystem $filesystemName -DestPath $dirname2

此示例将名为 my-directory 的目录移到名为 my-subdirectory 的 my-directory-2 子目录。This example moves a directory named my-directory to a subdirectory of my-directory-2 named my-subdirectory.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dirname2 = "my-directory-2/my-subdirectory/"
Move-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname1 -DestFileSystem $filesystemName -DestPath $dirname2

删除目录Delete a directory

使用 Remove-AzDataLakeGen2Item cmdlet 删除目录。Delete a directory by using the Remove-AzDataLakeGen2Item cmdlet.

此示例删除名为 my-directory 的目录。This example deletes a directory named my-directory.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
Remove-AzDataLakeGen2Item  -Context $ctx -FileSystem $filesystemName -Path $dirname 

可以使用 -Force 参数删除文件，而不会看到提示。You can use the -Force parameter to remove the file without a prompt.

从目录下载Download from a directory

使用 Get-AzDataLakeGen2ItemContent cmdlet 从目录中下载文件。Download a file from a directory by using the Get-AzDataLakeGen2ItemContent cmdlet.

此示例从名为 my-directory 的目录中下载名为 upload.txt 的文件。This example downloads a file named upload.txt from a directory named my-directory.

$filesystemName = "my-file-system"
$filePath = "my-directory/upload.txt"
$downloadFilePath = "download.txt"
Get-AzDataLakeGen2ItemContent -Context $ctx -FileSystem $filesystemName -Path $filePath -Destination $downloadFilePath

列出目录内容List directory contents

使用 Get-AzDataLakeGen2ChildItem cmdlet 列出目录的内容。List the contents of a directory by using the Get-AzDataLakeGen2ChildItem cmdlet. 可以使用可选参数 -OutputUserPrincipalName 来获取用户的名称（而不是对象 ID）。You can use the optional parameter -OutputUserPrincipalName to get the name (instead of the object ID) of users.

此示例列出名为 my-directory 的目录的内容。This example lists the contents of a directory named my-directory.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
Get-AzDataLakeGen2ChildItem -Context $ctx -FileSystem $filesystemName -Path $dirname -OutputUserPrincipalName

下面的示例列出目录中每个项的 ACL、Permissions、Group 和 Owner 属性。The following example lists the ACL, Permissions, Group, and Owner properties of each item in the directory. 获取 ACL 属性的值需要 -FetchProperty 参数。The -FetchProperty parameter is required to get values for the ACL property.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$properties = Get-AzDataLakeGen2ChildItem -Context $ctx -FileSystem $filesystemName -Path $dirname -Recurse -FetchProperty
$properties.ACL
$properties.Permissions
$properties.Group
$properties.Owner

将文件上传到目录Upload a file to a directory

使用 New-AzDataLakeGen2Item cmdlet 将文件上传到目录。Upload a file to a directory by using the New-AzDataLakeGen2Item cmdlet.

此示例将名为 upload.txt 的文件上传到名为 my-directory 的目录。This example uploads a file named upload.txt to a directory named my-directory.

$localSrcFile =  "upload.txt"
$filesystemName = "my-file-system"
$dirname = "my-directory/"
$destPath = $dirname + (Get-Item $localSrcFile).Name
New-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $destPath -Source $localSrcFile -Force 

此示例上传同一文件，但随后会设置目标文件的权限、umask、属性值和元数据值。This example uploads the same file, but then sets the permissions, umask, property values, and metadata values of the destination file. 此示例还会将这些值输出到控制台。This example also prints these values to the console.

$file = New-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $destPath -Source $localSrcFile -Permission rwxrwxrwx -Umask ---rwx--- -Property @{"ContentEncoding" = "UDF8"; "CacheControl" = "READ"} -Metadata  @{"tag1" = "value1"; "tag2" = "value2" }
$file1
$file1.Properties
$file1.Properties.Metadata

显示文件属性Show file properties

此示例使用 Get-AzDataLakeGen2Item cmdlet 获取文件，然后将属性值输出到控制台。This example gets a file by using the Get-AzDataLakeGen2Item cmdlet, and then prints property values to the console.

$filepath =  "my-directory/upload.txt"
$filesystemName = "my-file-system"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filepath
$file
$file.ACL
$file.Permissions
$file.Group
$file.Owner
$file.Properties
$file.Properties.Metadata

删除文件Delete a file

使用 Remove-AzDataLakeGen2Item cmdlet 删除文件。Delete a file by using the Remove-AzDataLakeGen2Item cmdlet.

此示例删除名为 upload.txt 的文件。This example deletes a file named upload.txt.

$filesystemName = "my-file-system"
$filepath = "upload.txt"
Remove-AzDataLakeGen2Item  -Context $ctx -FileSystem $filesystemName -Path $filepath 

可以使用 -Force 参数删除文件，而不会看到提示。You can use the -Force parameter to remove the file without a prompt.

管理访问权限Manage access permissions

可以获取、设置和更新目录与文件的访问权限。You can get, set, and update access permissions of directories and files. 这些权限在访问控制列表 (ACL) 中捕获。These permissions are captured in access control lists (ACLs).

获取 ACLGet an ACL

使用 Get-AzDataLakeGen2Item cmdlet 获取目录或文件的 ACL。Get the ACL of a directory or file by using the Get-AzDataLakeGen2Itemcmdlet.

此示例获取某个容器根目录的 ACL，然后将该 ACL 输出到控制台。This example gets the ACL of the root directory of a container and then prints the ACL to the console.

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

此示例获取某个目录的 ACL，然后将 ACL 输出到控制台。This example gets the ACL of a directory, and then prints the ACL to the console.

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

此示例获取某个文件的 ACL，然后将 ACL 输出到控制台。This example gets the ACL of a file and then prints the ACL to the console.

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

下图显示了获取目录 ACL 后的输出。The following image shows the output after getting the ACL of a directory.

在本示例中，负责人用户具有读取、写入和执行权限。In this example, the owning user has read, write, and execute permissions. 负责人组仅具有读取和执行权限。The owning group has only read and execute permissions. 有关访问控制列表的详细信息，请参阅 Azure Data Lake Storage Gen2 中的访问控制。For more information about access control lists, see Access control in Azure Data Lake Storage Gen2.

设置 ACLSet an ACL

使用 set-AzDataLakeGen2ItemAclObject cmdlet 为所有者用户、所有者组或其他用户创建 ACL。Use the set-AzDataLakeGen2ItemAclObject cmdlet to create an ACL for the owning user, owning group, or other users. 然后使用 Update-AzDataLakeGen2Item cmdlet 提交 ACL。Then, use the Update-AzDataLakeGen2Item cmdlet to commit the ACL.

此示例针对所有者用户、所有者组或其他用户的容器根目录设置 ACL，然后将 ACL 输出到控制台。This example sets the ACL on the root directory of a container for the owning user, owning group, or other users, and then prints the ACL to the console.

$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 输出到控制台。This example sets the ACL on a directory for the owning user, owning group, or other users, and then prints the ACL to the console.

$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 输出到控制台。This example sets the ACL on a file for the owning user, owning group, or other users, and then prints the ACL to the console.

$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 后的输出。The following image shows the output after setting the ACL of a file.

在本示例中，负责人用户和负责人组只有读取和写入权限。In this example, the owning user and owning group have only read and write permissions. 所有其他用户都具有写入和执行权限。All other users have write and execute permissions. 有关访问控制列表的详细信息，请参阅 Azure Data Lake Storage Gen2 中的访问控制。For more information about access control lists, see Access control in Azure Data Lake Storage Gen2.

添加或更新 ACL 条目Add or update an ACL entry

首先，获取 ACL。First, get the ACL. 然后，使用 set-AzDataLakeGen2ItemAclObject cmdlet 添加或更新 ACL 条目。Then, use the set-AzDataLakeGen2ItemAclObject cmdlet to add or update an ACL entry. 使用 Update-AzDataLakeGen2Item cmdlet 提交 ACL。Use the Update-AzDataLakeGen2Item cmdlet to commit the ACL.

此示例创建或更新用户目录的 ACL。This example creates or updates the ACL on a directory for a user.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = (Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname).ACL
$acl = set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -InputObject $acl 
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

删除 ACL 条目Remove an ACL entry

此示例从现有 ACL 中删除条目。This example removes an entry from an existing ACL.

$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（预览）Set an ACL recursively (preview)

你可以为父目录的现有子项以递归方式添加、更新和删除 ACL，而不必为每个子项单独进行这些更改。You can add, update, and remove ACLs recursively on the existing child items of a parent directory without having to make these changes individually for each child item. 有关详细信息，请参阅以递归方式为 Azure Data Lake Storage Gen2 设置访问控制列表 (ACL)。For more information, see Set access control lists (ACLs) recursively for Azure Data Lake Storage Gen2.

另请参阅See also

• 已知问题Known issues
• 存储 PowerShell cmdlet。Storage PowerShell cmdlets.