Share via

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

  • Artigo

Este artigo mostra como usar a CLI do Azure 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.

Exemplos de referência | | Dar feedback

Pré-requisitos

Verifique se você tem a versão correta da CLI do Azure instalada

  1. Abra o Azure Cloud Shell ou, se tiver instalado a CLI do Azure localmente, abra um aplicativo de console de comando, como o Windows PowerShell.

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

     az --version

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

Conecte-se à conta

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

    az login

    Se a CLI puder abrir seu navegador padrão, ela fará isso e carregará uma página de entrada do Azure.

    Caso contrário, abra uma página do navegador e https://aka.ms/devicelogin insira o código de autorização exibido no seu terminal. Em seguida, inicie sessão com as credenciais da sua conta no browser.

    Para saber mais sobre 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, defina sua assinatura ativa como assinatura da conta de armazenamento que hospedará seu site estático.

    az account set --subscription <subscription-id>

    Substitua o valor do espaço reservado <subscription-id> pelo ID da sua assinatura.

Nota

O exemplo apresentado neste artigo mostra a autorização do Microsoft Entra. Para saber mais sobre métodos de autorização, consulte Autorizar o acesso a dados de blob ou fila com a CLI do Azure.

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-file-system --account-name mystorageaccount --auth-mode login

Obtenha as permissões de acesso de um arquivo usando 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-file-system --account-name mystorageaccount --auth-mode login

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

Get ACL output

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 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, grupo proprietário ou outros usuários e, em seguida, imprime a ACL no console.

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

Este exemplo define a ACL padrão 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.

az storage fs access set --acl "default:user::rw-,group::rw-,other::-wx" -p my-directory -f my-file-system --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, grupo proprietário ou outros usuários e, em seguida, imprime a ACL no console.

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

Nota

Para definir a ACL de um grupo ou usuário específico, 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.

Get ACL output 2

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 comando az storage fs access set-recursive .

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.

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

Nota

Se você quiser definir uma entrada ACL padrão , adicione o prefixo default: a cada entrada. Por exemplo, default:user::rwx ou default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x.

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.

Para atualizar uma ACL, crie um novo objeto ACL com a entrada ACL que você deseja atualizar e use esse objeto na operação de atualização da ACL. Não obtenha a ACL existente, apenas forneça entradas de ACL para serem atualizadas.

Esta seção mostra como:

  • Atualizar uma ACL
  • Atualizar ACLs recursivamente

Atualizar uma ACL

Atualize a ACL de um arquivo usando o 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/myfile.txt -f my-container --account-name mystorageaccount --auth-mode login

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

Nota

A atualização da ACL de um único diretório sem atualizar a ACL de itens filho não é suportada pela CLI do Azure. Para atualizar a ACL de um diretório sem modificar as ACLs de todos os itens filho nesse diretório, use qualquer uma das outras ferramentas e SDKs suportados. Consulte Como definir ACLs.

Atualizar ACLs recursivamente

Atualize as ACLs recursivamente usando o 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

Nota

Se você quiser atualizar uma entrada ACL padrão , adicione o prefixo default: a cada entrada. Por exemplo, default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r-x.

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

Nota

Se você quiser remover uma entrada ACL padrão , adicione o prefixo default: a cada entrada. Por exemplo, default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

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.

Em caso de falha, você pode retornar um token de continuação definindo o --continue-on-failure parâmetro como false. Depois de resolver os erros, você pode retomar o processo a partir do ponto de falha executando o comando novamente e, em seguida, definindo o parâmetro para o --continuation 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

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

Para garantir que o processo seja concluído ininterruptamente, 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

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