Use o PowerShell para gerir ACLs no Azure Data Lake Storage

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

Novos itens filhos que crias num diretório pai herdam automaticamente as ACLs. No entanto, também pode adicionar, atualizar e remover ACLs recursivamente nos itens filhos já existentes de um diretório principal, sem efetuar essas alterações individualmente em cada item filho.

Referência | Dê a sua opinião

Prerequisites

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

• Uma conta de armazenamento com namespace hierárquico (HNS) 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 aprovisionada à qual foi atribuída a função Proprietário de Dados de Blobs de Armazenamento, com âmbito no contentor de destino, na conta de armazenamento, no grupo de recursos pai ou na subscrição.

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

Instalar o módulo PowerShell

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

   echo $PSVersionTable.PSVersion.ToString()
   

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

2. Instalar o módulo Az.Storage .

   Install-Module Az.Storage -Repository PSGallery -Force  
   

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

Inicie sessão na conta

1. Abra uma janela de comandos PowerShell do Windows e depois inicie sessão na sua subscrição Azure com o comando Connect-AzAccount e siga as instruções no ecrã.

   Connect-AzAccount
   

2. Se a sua identidade estiver associada a mais do que uma subscrição e não lhe for pedido para selecionar a subscrição, defina a sua subscrição ativa para a subscrição da conta de armazenamento que pretende usar. Neste exemplo, substitua o valor do marcador <subscription-id> pelo ID da sua subscrição.

   Select-AzSubscription -SubscriptionId <subscription-id>
   

3. Obtenha o contexto da conta de armazenamento.

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

Coloca ACLs

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

No Azure Data Lake Storage, um contentor também é chamado de sistema de ficheiros. O -FileSystem parâmetro usado nos exemplos seguintes assume o nome do seu contentor.

O exemplo seguinte obtém a ACL do diretório raiz de um contentor e depois imprime a ACL na consola.

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

O exemplo seguinte obtém a ACL de um diretório e depois imprime a ACL na consola.

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

O exemplo seguinte obtém a ACL de um ficheiro e depois imprime a ACL na consola.

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

A imagem seguinte mostra a saída após obter a ACL de um diretório.

Neste exemplo, o utilizador proprietário tem permissões de leitura, escrita e execução. O grupo proprietário só tem permissões de leitura e execução. Para mais informações sobre listas de controlo de acesso, consulte Controlo de acesso no Azure Data Lake Storage.

Definir ACLs

Quando defines um ACL, substituis todo o 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, consulte a seção Atualizar ACLs deste artigo.

Se você optar por definir a 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, consulte 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 utilizador proprietário, grupo proprietário ou outros utilizadores. Em seguida, utilize o cmdlet Update-AzDataLakeGen2Item para confirmar a ACL.

Este exemplo define a ACL na diretoria raiz de um contentor para o utilizador proprietário, grupo proprietário ou outros utilizadores, e depois imprime a ACL na consola.

$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 num diretório para o utilizador proprietário, grupo proprietário ou outros utilizadores, e depois imprime a ACL na consola.

$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 num ficheiro para o utilizador proprietário, grupo proprietário ou outros utilizadores, e depois imprime a ACL na consola.

$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 seguinte mostra a saída após definir a ACL de um ficheiro.

Neste exemplo, o utilizador proprietário e o grupo proprietário têm apenas permissões de leitura e escrita. Todos os outros utilizadores têm permissões de escrita e execução. Para mais informações sobre listas de controlo de acesso, consulte Controlo 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. Estas entradas dão permissões ao utilizador proprietário para ler, escrever e executar, concedem 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 ACL neste exemplo fornece a um usuário específico com o 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, veja o artigo de referência Set-AzDataLakeGen2AclRecursive .

Atualizar ACL

Ao atualizar uma ACL, você modifica a ACL em vez de substituí-la. 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, consulte a seção Definir ACLs deste artigo.

Esta seção mostra como:

• Atualizar uma ACL
• Atualizar ACLs recursivamente

Atualizar uma ACL

Primeiro, obtenha a ACL. Depois, use o cmdlet Set-AzDataLakeGen2ItemAclObject para adicionar ou atualizar uma entrada ACL. Utilize o cmdlet Update-AzDataLakeGen2Item para aplicar a ACL.

Este exemplo cria ou atualiza a ACL num diretório para um utilizador.

$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 por lotes ao especificar um tamanho de lote, consulte o artigo de referência Update-AzDataLakeGen2AclRecursive.

Remover entradas da ACL

Esta seção mostra como:

• Remover uma entrada de ACL
• Remover entradas da ACL recursivamente

Remover uma entrada de ACL

Este exemplo remove uma entrada de uma ACL existente. Reutiliza o contexto da $ctx conta de armazenamento e as $aclvariáveis , $filesystemName, e $dirname estabelecidas nas secçõ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 da ACL recursivamente

Pode remover uma ou mais entradas ACL recursivamente. Para remover uma entrada ACL, cria um novo objeto ACL para a entrada que queres remover e depois usa esse objeto na operação remover ACL. Não obtenha a ACL existente; basta fornecer as entradas da ACL a remover.

Remova entradas ACL utilizando o cmdlet Remove-AzDataLakeGen2AclRecursive.

Este exemplo remove uma entrada ACL do diretório raiz do contentor.

$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 o tamanho do lote, consulte o artigo de referência Remove-AzDataLakeGen2AclRecursive .

Recuperar de falhas

Você pode encontrar erros de tempo de execução ou permissão ao modificar ACLs recursivamente. Os exemplos desta secção reutilizam o contexto da conta de armazenamento $ctx e as variáveis $filesystemName, $dirname e $acl definidas nas secçõ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 ficheiro que está na hierarquia de diretórios que está a modificar. Resolver a questão das permissões e depois optar por 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 precisa usar o token de continuação se preferir reiniciar desde o início. Você pode reaplicar entradas de ACL sem qualquer impacto negativo.

Este exemplo devolve resultados à variável e depois 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 no resultado da tabela, podes corrigir quaisquer erros de permissões e depois 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, veja o artigo de referência Set-AzDataLakeGen2AclRecursive .

Se quiseres que o processo seja concluído sem ser interrompido por erros de permissões, podes configurá-lo para isso.

Este exemplo utiliza o ContinueOnFailure parâmetro 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, veja o artigo de referência Set-AzDataLakeGen2AclRecursive .

Melhores práticas

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

Tratamento de erros de tempo de execução

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

Gerenciamento de erros de permissão (403)

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

Credenciais

Recomendamos que provisione uma entidade de segurança do Microsoft Entra à qual tenha sido atribuída a função de Proprietário de Dados do Blob de Armazenamento no escopo da conta ou contêiner de armazenamento de destino.

Desempenho

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

Limites do 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, veja Controlo de acesso no Azure Data Lake Storage Gen2.

Consulte também

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