Usar o PowerShell para gerenciar ACLs no Azure Data Lake Storage

Este artigo mostra como usar o PowerShell para obter, definir e atualizar as listas de controle de acesso (ACLs) de diretórios e arquivos.

Os itens filhos que você cria em um diretório pai herdam as ACLs automaticamente. No entanto, mas você também pode adicionar, atualizar e remover ACLs recursivamente nos itens filho existentes de um diretório pai sem precisar fazer essas alterações individualmente em cada item filho.

Referência | Fazer comentários

Pré-requisitos

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

• Uma conta de armazenamento com HNS (namespace hierárquico) habilitado. Siga estas instruções para criar um.

• Uma das seguintes permissões de segurança:

  • Uma entidade de segurança do Microsoft Entra ID provisionada à qual foi atribuída a função Proprietário de Dados do Storage Blob, com escopo no contêiner de destino, na conta de armazenamento, no grupo de recursos pai ou na assinatura.

  • Usuário proprietário do contêiner ou diretório de destino ao qual você planeja aplicar as configurações de ACL. Para definir ACLs recursivamente, esse usuário inclui todos os itens filho no contêiner ou diretório de destino.

Instalar o módulo do PowerShell

1. Verifique se a versão do PowerShell que você instalou é 5.1 superior ou superior usando o seguinte comando.

   echo $PSVersionTable.PSVersion.ToString()
   

   Para atualizar sua versão do PowerShell, veja Atualizar o PowerShell existente do Windows.

2. Instale o módulo Az.Storage.

   Install-Module Az.Storage -Repository PSGallery -Force  
   

   Para mais informações sobre como instalar módulos PowerShell, veja Instalar o módulo Azure PowerShell.

Conectar à conta

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 e você não for solicitado a selecioná-la, defina sua assinatura ativa para a assinatura da conta de armazenamento que deseja usar. 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
   

Obter ACLs

Obtenha a ACL de um diretório ou arquivo usando o cmdlet Get-AzDataLakeGen2Item.

No Azure Data Lake Storage, um container também é chamado de sistema de arquivos. O -FileSystem parâmetro usado nos exemplos a seguir recebe o nome do seu container.

O exemplo a seguir obtém a ACL do diretório raiz de um contêiner e então imprime a ACL no console.

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

O exemplo a seguir obtém a ACL de um diretório e então imprime a ACL no console.

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

O exemplo a seguir obtém a ACL de um arquivo e depois imprime a ACL no console.

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

A imagem a seguir mostra a saída depois de obter a ACL de um diretório.

Neste exemplo, o usuário proprietário tem permissões de leitura, gravação e execução. O grupo proprietário tem permissões de somente leitura e execução. Para obter mais informações sobre as listas de controle de acesso, confira Controle de Acesso no Azure Data Lake Storage.

Definir ACLs

Quando você define uma ACL, você substitui toda a ACL, incluindo todas as suas entradas. Se quiser alterar o nível de permissão de um principal de segurança ou adicionar um novo principal de segurança à ACL sem afetar outras entradas existentes, atualize a ACL em vez disso. Para atualizar uma ACL em vez de substituí-la, confira a seção Atualizar ACLs deste artigo.

Se você optar pordefinira ACL, deverá adicionar uma entrada para o usuário proprietário, uma entrada para o grupo proprietário e uma entrada para todos os outros usuários. Para saber mais sobre o usuário proprietário, o grupo proprietário e todos os outros usuários, confira Usuários e identidades.

Esta seção mostra como:

• Definir uma ACL
• Definir ACLs recursivamente

Definir uma ACL

Use o cmdlet Set-AzDataLakeGen2ItemAclObject para criar uma ACL para o usuário proprietário, o grupo proprietário ou outros usuários. Em seguida, use o cmdlet Update-AzDataLakeGen2Item para confirmar a ACL.

Este exemplo define a ACL em um diretório raiz de um contêiner para o usuário proprietário, o grupo proprietário ou outros usuários e imprime a ACL no 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

Este exemplo define a ACL em um diretório para o usuário proprietário, o grupo proprietário ou outros usuários e imprime a ACL no 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

Este exemplo define a ACL em um arquivo para o usuário proprietário, o grupo proprietário ou outros usuários e imprime a ACL no 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

A imagem a seguir mostra a saída depois de definir a ACL de um arquivo.

Neste exemplo, o usuário proprietário e o grupo proprietário têm permissões de somente leitura e gravação. Todos os outros usuários têm permissões de gravação e execução. Para obter mais informações sobre as listas de controle de acesso, confira Controle de Acesso no Azure Data Lake Storage.

Definir ACLs recursivamente

Defina ACLs recursivamente usando o cmdlet set-AzDataLakeGen2AclRecursive.

Este exemplo define a ACL de um diretório chamado my-parent-directory. Essas entradas concedem permissões de leitura, gravação e execução ao usuário proprietário, dão ao grupo proprietário apenas permissões de leitura e execução, e não dão acesso a todos os outros. A última entrada de ACL neste exemplo fornece um usuário específico com a ID de objeto "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" permissões de leitura e execução.

$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

Para ver um exemplo que define ACLs recursivamente em lotes especificando um tamanho de lote, confira o artigo de referência Set-AzDataLakeGen2AclRecursive.

Atualizar ACLs

Ao atualizar uma ACL, você modifica a ACL em vez de substituir a ACL. Por exemplo, você pode adicionar uma nova entidade de segurança à ACL sem afetar outras entidades de segurança listadas na ACL. Para substituir a ACL em vez de atualizá-la, confira a seção Definir ACLsdeste artigo.

Esta seção mostra como:

• Atualizar uma ACL
• Atualizar ACLs recursivamente

Atualizar uma ACL

Primeiro, obtenha a ACL. Em seguida, use o cmdlet Set-AzDataLakeGen2ItemAclObject para adicionar ou atualizar uma entrada ACL. Use o cmdlet Update-AzDataLakeGen2Item para confirmar a ACL.

Este exemplo cria ou atualiza a ACL em um diretório para um usuário.

$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

Atualizar ACLs recursivamente

Atualize as ACLs recursivamente usando o cmdlet Update-AzDataLakeGen2AclRecursive.

Este exemplo atualiza uma entrada ACL com permissão de gravação.

$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

Para ver um exemplo que atualiza ACLs recursivamente em lotes especificando um tamanho de lote, confira o artigo de referência Update-AzDataLakeGen2AclRecursive.

Remover entradas de ACL

Esta seção mostra como:

• Remover uma entrada de ACL
• Remover entradas de ACL de forma recursiva

Remover uma entrada de ACL

Este exemplo remove uma entrada de uma ACL existente. Ele reutiliza o contexto da $ctx conta de armazenamento e as $aclvariáveis , $filesystemName, e $dirname estabelecidas em seções anteriores deste artigo.

$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

Remover entradas de ACL de forma recursiva

Você pode remover uma ou mais entradas de ACL recursivamente. Para remover uma entrada de ACL, crie um novo objeto ACL para a entrada de ACL que você deseja remover e então use esse objeto na operação remover ACL. Não obtenha a ACL existente, basta fornecer as entradas da ACL a serem removidas.

Remova as entradas ACL usando o cmdlet Remove-AzDataLakeGen2AclRecursive.

Este exemplo remove uma entrada ACL do diretório raiz do contêiner.

$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

Para ver um exemplo que remove ACLs recursivamente em lotes especificando um tamanho de lote, confira o artigo de referência Remove-AzDataLakeGen2AclRecursive.

Recuperar de falhas

Você pode encontrar erros de tempo de execução ou de permissão ao modificar ACLs recursivamente. Os exemplos desta seção reutilizam o contexto da $ctx conta de armazenamento e as $filesystemNamevariáveis , $dirname, e $acl estabelecidas em seções anteriores deste artigo.

Para erros de tempo de execução, reinicie o processo desde o início. Erros de permissão podem ocorrer se o principal de segurança não tiver permissão suficiente para modificar a ACL de um diretório ou arquivo que está na hierarquia de diretórios que você está modificando. Resolva a questão da permissão e, em seguida, escolha retomar o processo a partir do ponto de falha usando um token de continuação, ou reiniciar o processo do início. Você não precisará usar o token de continuação se preferir reiniciar desde o início. É possível reaplicar entradas de ACL sem nenhum impacto negativo.

Este exemplo retorna resultados à variável e então direciona as entradas falhadas para uma tabela formatada.

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

Com base na saída da tabela, você pode corrigir quaisquer erros de permissão e, em seguida, retomar a execução usando o token de continuação.

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

Para ver um exemplo que define ACLs recursivamente em lotes especificando um tamanho de lote, confira o artigo de referência Set-AzDataLakeGen2AclRecursive.

Se você quiser que o processo seja concluído sem ser interrompido por erros de permissão, pode configurá-lo para isso.

Este exemplo usa o parâmetro ContinueOnFailure para que a execução continue mesmo que a operação encontre um erro de permissão.

$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)

Para ver um exemplo que define ACLs recursivamente em lotes especificando um tamanho de lote, confira o artigo de referência Set-AzDataLakeGen2AclRecursive.

Práticas recomendadas

Esta seção fornece algumas diretrizes de práticas recomendadas para definir as ACLs recursivamente.

Tratamento de erros de tempo de execução

Um erro de runtime pode ocorrer por vários motivos (por exemplo: uma interrupção ou um problema de conectividade de cliente). Se você encontrar um erro de runtime, reinicie o processo de ACL recursivo. As ACLs podem ser reaplicadas para itens sem causar um impacto negativo.

Tratamento de erros de permissão (403)

Se você encontrar uma exceção de controle de acesso durante a execução de um processo de ACL recursivo, a entidade de segurança do AD poderá não ter permissão suficiente para aplicar uma ACL a um ou mais dos itens filho na hierarquia de diretórios. Quando ocorre um erro de permissão, o processo é interrompido e um token de continuação é fornecido. Corrija o problema de permissão e, em seguida, use o token de continuação para processar o conjunto de dados restante. Os diretórios e arquivos que já foram processados com êxito não precisam ser processados novamente. Você também pode optar por reiniciar o processo de ACL recursivo. As ACLs podem ser reaplicadas para itens sem causar um impacto negativo.

Credenciais

Recomendamos que você provisione uma entidade de segurança do Microsoft Entra que tenha sido atribuída à função de proprietário de dados do blob de armazenamento no escopo da conta de armazenamento de destino ou do contêiner.

Desempenho

Para reduzir a latência, recomendamos que você execute o processo de ACL recursivo em uma Máquina Virtual (VM) do Azure localizada na mesma região que a sua conta de armazenamento.

Limites da ACL

O número máximo de ACLs que você pode aplicar a um diretório ou arquivo é de 32 ACLs de acesso e 32 ACLs padrão. Para obter mais informações, consulte Controle de acesso no Azure Data Lake Storage Gen2.

Confira também

• Problemas conhecidos
• Cmdlets do PowerShell de Armazenamento
• Modelo de controle de acesso no Azure Data Lake Storage
• Listas de controle de acesso (ACLs) no Azure Data Lake Storage