Usar a CLI do Azure para gerenciar ACLs no Azure Data Lake Storage

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

Novos itens filho herdam automaticamente as ACLs. Mas você também pode adicionar, atualizar e remover ACLs de forma recursiva nos itens filho existentes sem fazer essas alterações individualmente em cada item filho.

Referência | Exemplos | 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 com o namespace hierárquico habilitado. Para instruções, veja Criar uma conta de armazenamento que tenha um namespace hierárquico.

• CLI do Azure versão 2.14.0 ou superior

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

Certifique-se de ter a versão correta da CLI do Azure instalada

1. Abra o Azure Cloud Shell ou, se você instalou a CLI do Azure localmente, abra um aplicativo de console de comandos como o PowerShell do Windows.

2. Verifique se a versão da CLI do Azure instalada é 2.14.0 ou superior usando o comando a seguir.

    az --version
   

   Se sua versão do CLI do Azure for inferior à 2.14.0, instale uma versão posterior. Para obter mais informações, consulte Instalar a CLI do Azure.

Conectar à conta

1. Se você estiver usando a CLI do Azure localmente, execute o comando de logon.

   az login
   

   Se a CLI conseguir abrir seu navegador padrão, ela abre o navegador e carrega uma página de login no Azure.

   Caso contrário, abra uma página de navegador em https://aka.ms/devicelogin e insira o código de autorização exibido no terminal. Em seguida, entre com suas credenciais de conta no navegador.

   Para saber mais sobre os diferentes métodos de autenticação, consulte Autorizar o acesso a dados de blob ou fila com a CLI do Azure.

2. Se sua identidade estiver associada a mais de uma assinatura e você não for solicitado a selecionar a assinatura, defina sua assinatura ativa para a assinatura da conta de armazenamento na qual deseja operar. Neste exemplo, substitua o valor do espaço reservado <subscription-id> pela ID da sua assinatura.

   az account set --subscription <subscription-id>
   

Obter ACLs

Obtenha a ACL de um diretório usando o comando az storage fs access show.

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

az storage fs access show -p my-directory -f my-container --account-name mystorageaccount --auth-mode login

Obtenha permissões de acesso de um arquivo ao usar o comando az storage fs access show.

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

az storage fs access show -p my-directory/upload.txt -f my-container --account-name mystorageaccount --auth-mode login

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

Aodefiniruma ACL, vocêsubstitui toda a ACL, incluindo todas as entradas. Se você quiser 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, deverá atualizar a ACL. 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 comando az storage fs access set para definir a ACL de um diretório.

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.

az storage fs access set --acl "user::rw-,group::rw-,other::-wx" -p my-directory -f my-container --account-name mystorageaccount --auth-mode login

Este exemplo define a ACL padrão em um diretório para o usuário proprietário, o grupo proprietário ou outros usuários e imprime a ACL no console.

az storage fs access set --acl "default:user::rw-,group::rw-,other::-wx" -p my-directory -f my-container --account-name mystorageaccount --auth-mode login

Use o comando az storage fs access set para definir a ACL de um arquivo.

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.

az storage fs access set --acl "user::rw-,group::rw-,other::-wx" -p my-directory/upload.txt -f my-container --account-name mystorageaccount --auth-mode login

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 comando AZ Storage FS Access Set-recursive.

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.

az storage fs access set-recursive --acl "user::rwx,group::r-x,other::---,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

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 ACLs deste artigo.

Para atualizar uma ACL, crie um novo objeto ACL com a entrada de ACL que você quer atualizar. Em seguida, use esse objeto na operação para atualizar a ACL. Não obtenha a ACL existente, basta fornecer as entradas de ACL a serem atualizadas.

Esta seção mostra como:

• Atualizar uma ACL
• Atualizar ACLs recursivamente

Atualizar uma ACL

Atualize as ACLs de um arquivo por meio do comando az storage fs access update-recursive. O CLI do Azure fornece apenas o update-recursive comando para atualizações. Quando você direciona um único arquivo, o comando atualiza apenas a ACL desse arquivo.

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

az storage fs access update-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx" -p my-parent-directory/myfile.txt -f my-container --account-name mystorageaccount --auth-mode login

Para atualizar a ACL de um grupo ou usuário específico, use as respectivas IDs de objeto. Por exemplo, group:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ou user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Atualizar ACLs recursivamente

Atualize as ACLs recursivamente por meio do comando az storage fs access update-recursive.

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

az storage fs access update-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

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 de ACL usando o comando AZ Storage FS Access remove-recursive.

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

az storage fs access remove-recursive --acl "user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login

Recuperar de falhas

Você pode encontrar erros de tempo de execução ou de 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 o principal de segurança não tiver permissão suficiente para modificar a ACL de um diretório ou arquivo na hierarquia de diretórios que você está modificando. Resolva o problema de permissão e, em seguida, escolha retomar o processo no 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.

Se ocorrer uma falha, retorne um token de continuação definindo o --continue-on-failure parâmetro para false. Depois de resolver os erros, você pode retomar o processo do ponto de falha executando o comando novamente e, em seguida, definindo o --continuation parâmetro para o token de continuação.

az storage fs access set-recursive --acl "user::rw-,group::r-x,other::---" --continue-on-failure false --continuation xxxxxxx -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login  

Para garantir que o processo seja concluído sem interrupções, defina o --continue-on-failure parâmetro como true.

az storage fs access set-recursive --acl "user::rw-,group::r-x,other::---" --continue-on-failure true --continuation xxxxxxx -p my-parent-directory/ -f my-container --account-name mystorageaccount --auth-mode login  

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

• Amostras
• Fornecer feedback
• Problemas conhecidos
• Modelo de controle de acesso no Azure Data Lake Storage
• Listas de controle de acesso (ACLs) no Azure Data Lake Storage