Usar o PowerShell para gerenciar ACLs no Azure Data Lake Storage Gen2

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

A herança de ACL já está disponível para novos itens filho criados em um diretório pai. Mas você também pode adicionar, atualizar e remover ACLs recursivamente nos itens filho existentes de um diretório pai sem ter que fazer essas alterações individualmente para cada item filho.

Referência | Dar feedback

Pré-requisitos

• Uma subscrição 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.

• Versão da CLI 2.6.0 do Azure ou superior.

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

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

  • 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, isso inclui todos os itens filho no contêiner ou diretório de destino.

  • Chave da conta de armazenamento.

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, consulte 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 módulos do PowerShell, consulte Instalar o módulo do Azure PowerShell

Conecte-se à conta

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

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

Nota

Se estiver a utilizar o Microsoft Entra ID para autorizar o acesso, certifique-se de que a sua entidade de segurança recebeu a função de Proprietário de Dados do Blob de Armazenamento. Para saber mais sobre como as permissões de ACL são aplicadas e os efeitos de alterá-las, consulte Modelo de controle de acesso no Azure Data Lake Storage Gen2.

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

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

   Connect-AzAccount
   

2. Se sua identidade estiver associada a mais de uma assinatura, defina sua assinatura ativa como assinatura da conta de armazenamento na qual você deseja criar e gerenciar diretórios. Neste exemplo, substitua o valor do <subscription-id> espaço reservado 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 da conta de armazenamento

Com essa abordagem, o sistema não verifica as permissões de RBAC ou ACL 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>'

Obter ACLs

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

Este exemplo obtém a ACL do diretório raiz de um contêiner e, em seguida, imprime a ACL no console.

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

Este exemplo obtém a ACL de um diretório e, em seguida, imprime a ACL no console.

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

Este exemplo obtém a ACL de um arquivo e, em seguida, 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 apenas permissões de leitura e execução. Para obter mais informações sobre listas de controle de acesso, consulte Controle de acesso no Azure Data Lake Storage Gen2.

Definir ACLs

Ao definir uma ACL, você substitui a ACL inteira, incluindo todas as entradas. Se desejar alterar o nível de permissão de uma entidade de segurança ou adicionar uma nova entidade de segurança à ACL sem afetar outras entradas existentes, atualize a ACL. 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 para criar uma ACL para o Set-AzDataLakeGen2ItemAclObject usuário proprietário, grupo proprietário ou outros usuários. Em seguida, use o Update-AzDataLakeGen2Item cmdlet para confirmar a ACL.

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

Nota

Se desejar definir uma entrada de ACL padrão, use o parâmetro -DefaultScope ao executar o comando Set-AzDataLakeGen2ItemAclObject. Por exemplo: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope.

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

Nota

Para definir a ACL de um grupo ou usuário específico, entidade de serviço ou identidade gerenciada, use suas respetivas IDs de objeto. Por exemplo, para definir a ACL de um grupo, use group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Para definir a ACL de um usuário, use user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

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 apenas permissões de 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 listas de controle de acesso, consulte Controle de acesso no Azure Data Lake Storage Gen2.

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 dão ao usuário proprietário permissões de leitura, gravação e execução, 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 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

Nota

Se desejar definir uma entrada de ACL padrão, use o parâmetro -DefaultScope ao executar o comando Set-AzDataLakeGen2ItemAclObject. Por exemplo: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx -DefaultScope.

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

Atualizar ACLs

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 o ACL. Em seguida, use o Set-AzDataLakeGen2ItemAclObject cmdlet para adicionar ou atualizar uma entrada ACL. Use o Update-AzDataLakeGen2Item cmdlet 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 xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Nota

Se desejar atualizar uma entrada de ACL padrão, use o parâmetro -DefaultScope ao executar o comando Set-AzDataLakeGen2ItemAclObject. Por exemplo: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID xxxxxxxx-xxxx-xxxxxxxxxxx -Permission r-x -DefaultScope.

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

Nota

Para definir a ACL de um grupo ou usuário específico, entidade de serviço ou identidade gerenciada, use suas respetivas IDs de objeto. Por exemplo, para definir a ACL de um grupo, use group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Para definir a ACL de um usuário, use user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Para ver um exemplo que atualiza ACLs recursivamente em lotes especificando 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.

$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

Você pode remover uma ou mais entradas da ACL recursivamente. Para remover uma entrada ACL, crie um novo objeto ACL para que a entrada ACL seja removida e, em seguida, use esse objeto na operação de remoção da ACL. Não obtenha a ACL existente, apenas forneça as entradas da ACL a serem removidas.

Remova as entradas da 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

Nota

Se desejar remover uma entrada de ACL padrão, use o parâmetro -DefaultScope ao executar o comando Set-AzDataLakeGen2ItemAclObject. Por exemplo: $acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---" -DefaultScope.

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

Recupere-se de falhas

Você pode encontrar erros de tempo de execução ou permissão ao modificar ACLs recursivamente.

Para erros de tempo de execução, reinicie o processo desde o início. Erros de permissão podem ocorrer se a entidade 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 está sendo modificada. Resolva o problema de permissão e, em seguida, opte por retomar o processo a partir do ponto de falha usando um token de continuação ou reiniciar o processo desde o 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 retorna resultados para a variável e, em seguida, canaliza entradas com falha 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, consulte o artigo de referência Set-AzDataLakeGen2AclRecursive .

Se desejar que o processo seja concluído ininterruptamente por erros de permissão, você pode especificar isso.

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

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

echo "[Result Summary]"
echo "TotalDirectoriesSuccessfulCount: `t$($result.TotalFilesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalDirectoriesSuccessfulCount)"
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, consulte o artigo de referência Set-AzDataLakeGen2AclRecursive .

Melhores práticas

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

Manipulando 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.

Manipulando 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, 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 de ACL recursiva. As ACLs podem ser reaplicadas aos itens sem causar um impacto negativo.

Credenciais

Recomendamos que você 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 LCA

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 Azure Data Lake Storage Gen2
• Listas de controle de acesso (ACLs) no Azure Data Lake Storage Gen2