Usar o PowerShell para gerenciar diretórios e arquivos no Azure Data Lake Storage Gen2

  • Artigo

Este artigo mostra como usar o PowerShell para criar e gerenciar diretórios e arquivos nas contas de armazenamento que têm um namespace hierárquico.

Para saber mais sobre como obter, definir e atualizar as ACLs (listas de controle de acesso) de diretórios e arquivos, confira Usar o PowerShell para gerenciar ACLs no Azure Data Lake Storage Gen2.

Referência | Mapeamento de Gen1 para Gen2 | Dar feedback

Pré-requisitos

  • Uma assinatura do Azure. Para obter mais informações, confira Obter a avaliação gratuita do Azure.

  • Uma conta de armazenamento precisa ter o namespace hierárquico habilitado. Siga estas instruções para criar um.

  • .NET Framework é a versão 4.7.2 ou superior instalada. Para obter mais informações, confira Baixar o .NET Framework.

  • PowerShell versão 5.1 ou posterior.

Instalar o módulo do PowerShell

  1. Verifique se a versão do PowerShell instalada é 5.1 ou superior usando o comando a seguir.

    echo $PSVersionTable.PSVersion.ToString()

    Para atualizar sua versão do PowerShell, confira Atualizando o Windows PowerShell existente

  2. Instale o módulo Az.Storage.

    Install-Module Az.Storage -Repository PSGallery -Force

    Para obter mais informações sobre como instalar os módulos PowerShell, confira Instalar e configurar o módulo Azure PowerShell

Conectar à conta

Escolha como você deseja que os comandos obtenham autorização para a conta de armazenamento.

Opção 1: obter autorização usando o Microsoft Entra ID

Com essa abordagem, o sistema garante que sua conta de usuário tenha as atribuições apropriadas do RBAC do Azure (controle de acesso baseado em função do Azure) e permissões de ACL.

  1. Abra uma janela Comando do Windows PowerShell e entre em sua assinatura do Azure com o comando Connect-AzAccount e siga as instruções na tela.

    Connect-AzAccount

  2. Se sua identidade estiver associada a mais de uma assinatura, defina a assinatura ativa para a assinatura da conta de armazenamento para na qual deseja criar e gerenciar diretórios. Neste exemplo, substitua o valor do espaço reservado <subscription-id> pela ID da sua assinatura.

    Select-AzSubscription -SubscriptionId <subscription-id>

  3. Obtenha o contexto da conta de armazenamento.

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

Opção 2: obter autorização usando a chave de conta de armazenamento

Com essa abordagem, o sistema não verifica as permissões de ACL ou RBAC do Azure. Obtenha o contexto da conta de armazenamento usando uma chave de conta.

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

Criar um contêiner

Um contêiner atua como um sistema de arquivos para seus arquivos. Você pode criar um usando o cmdlet New-AzStorageContainer.

Este exemplo cria um contêiner chamado my-file-system.

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

Criar um diretório

Crie uma referência de diretório usando o cmdlet New-AzDataLakeGen2Item.

Este exemplo adiciona um diretório chamado my-directory a um contêiner.

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

Este exemplo adiciona o mesmo diretório, mas também define as permissões, umask, valores de propriedade e valores de metadados.

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

Obter propriedades do diretório

Este exemplo obtém um diretório usando o cmdlet Get-AzDataLakeGen2Item e imprime valores de propriedade no 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

Observação

Para obter o diretório raiz do contêiner, omita o parâmetro -Path.

Renomear ou mover um diretório

Renomeie ou mova um diretório usando o cmdlet Move-AzDataLakeGen2Item.

Este exemplo renomeia um diretório de my-directory para 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

Observação

Use o parâmetro -Force se você quiser substituir sem prompts.

Este exemplo move um diretório chamado my-directory para um subdiretório de my-directory-2 chamado my-subdirectory.

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

Excluir um diretório

Exclui um diretório usando o cmdlet Remove-AzDataLakeGen2Item.

Este exemplo exclui um diretório chamado my-directory.

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

Você pode usar o parâmetro -Force para remover o arquivo sem um prompt.

Baixar de um diretório

Baixe um arquivo de um diretório usando o cmdlet Get-AzDataLakeGen2ItemContent.

Este exemplo baixa um arquivo chamado upload.txt de um diretório chamado my-directory.

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

Listar conteúdo do diretório

Liste o conteúdo de um diretório usando o cmdlet Get-AzDataLakeGen2ChildItem. Você pode usar o parâmetro opcional -OutputUserPrincipalName para obter o nome (em vez da ID de objeto) de usuários.

Este exemplo lista o conteúdo de um sistema de arquivos chamado my-directory.

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

O exemplo a seguir lista as propriedades ACL, Permissions, Group e Owner de cada item no diretório. O parâmetro -FetchProperty é necessário para obter valores para a propriedade ACL.

$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

Observação

Para listar o conteúdo do diretório raiz do contêiner, omita o parâmetro -Path.

Carregar um arquivo em um diretório

Carregue um arquivo para um diretório usando o cmdlet New-AzDataLakeGen2Item.

Este exemplo carrega um arquivo chamado upload.txt em um diretório chamado 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

Este exemplo carrega o mesmo arquivo, mas, em seguida, define permissões, umask, valores de propriedade e valores de metadados do arquivo de destino. Este exemplo também imprime esses valores no 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

Observação

Para carregar um arquivo no diretório raiz do contêiner, omita o parâmetro -Path.

Mostrar propriedades do arquivo

Este exemplo obtém um arquivo usando o cmdlet Get-AzDataLakeGen2Item e imprime valores de propriedade no 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

Excluir um arquivo

Exclua um arquivo usando o cmdlet Remove-AzDataLakeGen2Item.

Este exemplo exclui um arquivo chamado upload.txt.

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

Você pode usar o parâmetro -Force para remover o arquivo sem um prompt.

Mapeamento de Gen1 para Gen2

A tabela a seguir mostra como os cmdlets usados para Data Lake Storage Gen1 são mapeados para os cmdlets para Data Lake Storage Gen2.

Observação

O Azure Data Lake Storage Gen1 foi desativado. Veja o anúncio da desativação aqui. Os recursos do Data Lake Storage Gen1 não estão mais acessíveis. Se precisar de assistência especial, entre em contato conosco.

cmdlet do Data Lake Storage Gen1 cmdlet do Data Lake Storage Gen2 Observações
Get-AzDataLakeStoreChildItem Get-AzDataLakeGen2ChildItem Por padrão, o cmdlet Get-AzDataLakeGen2ChildItem lista apenas os itens filho de primeiro nível. O parâmetro -Recurse lista os itens filho recursivamente.
Get-AzDataLakeStoreItem
Get-AzDataLakeStoreItemAclEntry
Get-AzDataLakeStoreItemOwner
Get-AzDataLakeStoreItemPermission		 Get-AzDataLakeGen2Item Os itens de saída do cmdlet Get-AzDataLakeGen2Item têm estas propriedades: Acl, Proprietário, Grupo, Permissão.
Get-AzDataLakeStoreItemContent Get-AzDataLakeGen2FileContent O cmdlet Get-AzDataLakeGen2FileContent baixar o conteúdo do arquivo para o arquivo local.
Move-AzDataLakeStoreItem Move-AzDataLakeGen2Item
New-AzDataLakeStoreItem New-AzDataLakeGen2Item Esse cmdlet carrega o novo conteúdo do arquivo de um arquivo local.
Remove-AzDataLakeStoreItem Remove-AzDataLakeGen2Item
Set-AzDataLakeStoreItemOwner
Set-AzDataLakeStoreItemPermission
Set-AzDataLakeStoreItemAcl		 Update-AzDataLakeGen2Item O cmdlet Update-AzDataLakeGen2Item atualiza apenas um item e não recursivamente. Se você quiser atualizar recursivamente, liste os itens usando o cmdlet Get-AzDataLakeStoreChildItem e então use um pipeline para o cmdlet Update-AzDataLakeGen2Item.
Test-AzDataLakeStoreItem Get-AzDataLakeGen2Item O cmdlet Get-AzDataLakeGen2Item reporta um erro se o item não existir.

Confira também