Usar o .NET para gerenciar ACLs no Azure Data Lake Storage Gen2
Este artigo mostra como usar o .NET 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.
Pacote (NuGet) | Amostras | API referência | Gen1 para Gen2 mapeamento | Dar feedback
Pré-requisitos
Uma subscrição do Azure. Veja Obter versão de 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.
Configure o seu projeto
Para começar, instale o pacote NuGet Azure.Storage.Files.DataLake .
Abra uma janela de comando (por exemplo: Windows PowerShell).
No diretório do projeto, instale o pacote de visualização Azure.Storage.Files.DataLake usando o
dotnet add package
comando.dotnet add package Azure.Storage.Files.DataLake -v 12.6.0 -s https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-net/nuget/v3/index.json
Em seguida, adicione essas instruções using à parte superior do arquivo de código.
using Azure; using Azure.Core; using Azure.Storage; using Azure.Storage.Files.DataLake; using Azure.Storage.Files.DataLake.Models; using System.Collections.Generic; using System.Threading.Tasks;
Conecte-se à conta
Para usar os trechos deste artigo, você precisará criar uma instância DataLakeServiceClient que represente a conta de armazenamento.
Conectar-se 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.
Você pode usar a biblioteca de cliente de identidade do Azure para .NET para autenticar seu aplicativo com a ID do Microsoft Entra.
Depois de instalar o pacote, adicione esta instrução using à parte superior do arquivo de código.
using Azure.Identity;
Primeiro, você terá que atribuir uma das seguintes funções de controle de acesso baseado em função do Azure (Azure RBAC) à sua entidade de segurança:
Função | Capacidade de configuração de ACL |
---|---|
Proprietário dos Dados do Armazenamento de Blobs | Todos os diretórios e arquivos na conta. |
Contribuinte de Dados do Armazenamento de Blobs | Somente diretórios e arquivos de propriedade da entidade de segurança. |
Em seguida, crie uma instância DataLakeServiceClient e passe uma nova instância da classe DefaultAzureCredential.
public static DataLakeServiceClient GetDataLakeServiceClient(string accountName)
{
string dfsUri = $"https://{accountName}.dfs.core.windows.net";
DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
new Uri(dfsUri),
new DefaultAzureCredential());
return dataLakeServiceClient;
}
Para saber mais sobre como usar DefaultAzureCredential para autorizar o acesso a dados, consulte Como autenticar aplicativos .NET com serviços do Azure.
Conectar-se usando uma chave de conta
Você pode autorizar o acesso aos dados usando as chaves de acesso da sua conta (Chave compartilhada). Este exemplo cria uma instância DataLakeServiceClient que é autorizada com a chave de conta.
public static DataLakeServiceClient GetDataLakeServiceClient(string accountName, string accountKey)
{
StorageSharedKeyCredential sharedKeyCredential =
new StorageSharedKeyCredential(accountName, accountKey);
string dfsUri = $"https://{accountName}.dfs.core.windows.net";
DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
new Uri(dfsUri),
sharedKeyCredential);
return dataLakeServiceClient;
}
Atenção
A autorização com chave compartilhada não é recomendada, pois pode ser menos segura. Para uma segurança ideal, desative a autorização através da Chave Partilhada para a sua conta de armazenamento, conforme descrito em Impedir autorização de Chave Partilhada para uma conta de Armazenamento do Azure.
O uso de chaves de acesso e cadeias de conexão deve ser limitado a aplicativos de prova de conceito iniciais ou protótipos de desenvolvimento que não acessam dados confidenciais ou de produção. Caso contrário, as classes de autenticação baseada em token disponíveis no SDK do Azure devem sempre ser preferidas ao autenticar nos recursos do Azure.
A Microsoft recomenda que os clientes usem o Microsoft Entra ID ou uma assinatura de acesso compartilhado (SAS) para autorizar o acesso aos dados no Armazenamento do Azure. Para obter mais informações, consulte Autorizar operações para acesso a dados.
Definir ACLs
Ao definir uma ACL, você substitui a ACL inteira, incluindo todas as suas 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 a ACL de um diretório
- Definir a ACL de um arquivo
- Definir ACLs recursivamente
Definir a ACL de um diretório
Obtenha a lista de controle de acesso (ACL) de um diretório chamando o método DataLakeDirectoryClient.GetAccessControlAsync e defina a ACL chamando o método DataLakeDirectoryClient.SetAccessControlList.
Este exemplo obtém e define a ACL de um diretório chamado my-directory
. A cadeia de caracteres dá ao usuário proprietário permissões de leitura, gravação e execução, dá ao grupo proprietário apenas permissões de user::rwx,group::r-x,other::rw-
leitura e execução e dá a todos os outros permissões de leitura e gravação.
public async Task ManageDirectoryACLs(DataLakeFileSystemClient fileSystemClient)
{
DataLakeDirectoryClient directoryClient =
fileSystemClient.GetDirectoryClient("");
PathAccessControl directoryAccessControl =
await directoryClient.GetAccessControlAsync();
foreach (var item in directoryAccessControl.AccessControlList)
{
Console.WriteLine(item.ToString());
}
IList<PathAccessControlItem> accessControlList
= PathAccessControlExtensions.ParseAccessControlList
("user::rwx,group::r-x,other::rw-");
directoryClient.SetAccessControlList(accessControlList);
}
Você também pode obter e definir a ACL do diretório raiz de um contêiner. Para obter o diretório raiz, passe uma cadeia de caracteres vazia (""
) para o método DataLakeFileSystemClient.GetDirectoryClient .
Definir a ACL de um arquivo
Obtenha a lista de controle de acesso (ACL) de um arquivo chamando o método DataLakeFileClient.GetAccessControlAsync e defina a ACL chamando o método DataLakeFileClient.SetAccessControlList.
Este exemplo obtém e define a ACL de um arquivo chamado my-file.txt
. A cadeia de caracteres dá ao usuário proprietário permissões de leitura, gravação e execução, dá ao grupo proprietário apenas permissões de user::rwx,group::r-x,other::rw-
leitura e execução e dá a todos os outros permissões de leitura e gravação.
public async Task ManageFileACLs(DataLakeFileSystemClient fileSystemClient)
{
DataLakeDirectoryClient directoryClient =
fileSystemClient.GetDirectoryClient("my-directory");
DataLakeFileClient fileClient =
directoryClient.GetFileClient("hello.txt");
PathAccessControl FileAccessControl =
await fileClient.GetAccessControlAsync();
foreach (var item in FileAccessControl.AccessControlList)
{
Console.WriteLine(item.ToString());
}
IList<PathAccessControlItem> accessControlList
= PathAccessControlExtensions.ParseAccessControlList
("user::rwx,group::r-x,other::rw-");
fileClient.SetAccessControlList(accessControlList);
}
Definir ACLs recursivamente
Defina ACLs recursivamente chamando o método DataLakeDirectoryClient.SetAccessControlRecursiveAsync . Passe este método uma lista de PathAccessControlItem. Cada PathAccessControlItem define uma entrada ACL.
Se quiser definir uma entrada ACL padrão , você pode definir a propriedade PathAccessControlItem.DefaultScope do PathAccessControlItem como true.
Este exemplo define a ACL de um diretório chamado my-parent-directory
. Esse método aceita um parâmetro booleano chamado isDefaultScope
que especifica se a ACL padrão deve ser definida. Esse parâmetro é usado no construtor do PathAccessControlItem. As entradas da ACL dão ao usuário proprietário permissões de leitura, gravação e execução, dá ao grupo proprietário apenas permissões de leitura e execução e não dá acesso a todos os outros. A última entrada de ACL neste exemplo fornece a um usuário específico com as permissões de leitura e execução do ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
do objeto.
public async Task SetACLRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
DataLakeDirectoryClient directoryClient =
serviceClient.GetFileSystemClient("my-container").
GetDirectoryClient("my-parent-directory");
List<PathAccessControlItem> accessControlList =
new List<PathAccessControlItem>()
{
new PathAccessControlItem(AccessControlType.User,
RolePermissions.Read |
RolePermissions.Write |
RolePermissions.Execute, isDefaultScope),
new PathAccessControlItem(AccessControlType.Group,
RolePermissions.Read |
RolePermissions.Execute, isDefaultScope),
new PathAccessControlItem(AccessControlType.Other,
RolePermissions.None, isDefaultScope),
new PathAccessControlItem(AccessControlType.User,
RolePermissions.Read |
RolePermissions.Execute, isDefaultScope,
entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
};
await directoryClient.SetAccessControlRecursiveAsync
(accessControlList, null);
}
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 a ACL de um diretório chamando o método DataLakeDirectoryClient.GetAccessControlAsync . Copie a lista de entradas ACL para uma nova List de objetos PathAccessControl . Em seguida, localize a entrada que você deseja atualizar e substitua-a na lista. Defina a ACL chamando o método DataLakeDirectoryClient.SetAccessControlList .
Este exemplo atualiza a ACL raiz de um contêiner substituindo a entrada ACL para todos os outros usuários.
public async Task UpdateDirectoryACLs(DataLakeFileSystemClient fileSystemClient)
{
DataLakeDirectoryClient directoryClient =
fileSystemClient.GetDirectoryClient("");
PathAccessControl directoryAccessControl =
await directoryClient.GetAccessControlAsync();
List<PathAccessControlItem> accessControlListUpdate
= (List<PathAccessControlItem>)directoryAccessControl.AccessControlList;
int index = -1;
foreach (var item in accessControlListUpdate)
{
if (item.AccessControlType == AccessControlType.Other)
{
index = accessControlListUpdate.IndexOf(item);
break;
}
}
if (index > -1)
{
accessControlListUpdate[index] = new PathAccessControlItem(AccessControlType.Other,
RolePermissions.Read |
RolePermissions.Execute);
directoryClient.SetAccessControlList(accessControlListUpdate);
}
}
Atualizar ACLs recursivamente
Para atualizar uma ACL recursivamente, 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.
Atualize uma ACL recursivamente chamando o método DataLakeDirectoryClient.UpdateAccessControlRecursiveAsync . Passe este método uma lista de PathAccessControlItem. Cada PathAccessControlItem define uma entrada ACL.
Se desejar atualizar uma entrada de ACL padrão , você pode definir a propriedade PathAccessControlItem.DefaultScope do PathAccessControlItem como true.
Este exemplo atualiza uma entrada ACL com permissão de gravação. Esse método aceita um parâmetro booleano chamado isDefaultScope
que especifica se a ACL padrão deve ser atualizada. Esse parâmetro é usado no construtor do PathAccessControlItem.
public async Task UpdateACLsRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
DataLakeDirectoryClient directoryClient =
serviceClient.GetFileSystemClient("my-container").
GetDirectoryClient("my-parent-directory");
List<PathAccessControlItem> accessControlListUpdate =
new List<PathAccessControlItem>()
{
new PathAccessControlItem(AccessControlType.User,
RolePermissions.Read |
RolePermissions.Write |
RolePermissions.Execute, isDefaultScope,
entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
};
await directoryClient.UpdateAccessControlRecursiveAsync
(accessControlListUpdate, null);
}
Remover entradas da ACL
Você pode remover uma ou mais entradas da ACL. Esta seção mostra como:
- Remover uma entrada de ACL
- Remover entradas da ACL recursivamente
Remover uma entrada de ACL
Primeiro, obtenha a ACL de um diretório chamando o método DataLakeDirectoryClient.GetAccessControlAsync . Copie a lista de entradas ACL para uma nova List de objetos PathAccessControl . Em seguida, localize a entrada que você deseja remover e chame o método Remove da coleção. Defina a ACL atualizada chamando o método DataLakeDirectoryClient.SetAccessControlList .
Este exemplo atualiza a ACL raiz de um contêiner substituindo a entrada ACL para todos os outros usuários.
public async Task RemoveDirectoryACLEntry
(DataLakeFileSystemClient fileSystemClient)
{
DataLakeDirectoryClient directoryClient =
fileSystemClient.GetDirectoryClient("");
PathAccessControl directoryAccessControl =
await directoryClient.GetAccessControlAsync();
List<PathAccessControlItem> accessControlListUpdate
= (List<PathAccessControlItem>)directoryAccessControl.AccessControlList;
PathAccessControlItem entryToRemove = null;
foreach (var item in accessControlListUpdate)
{
if (item.EntityId == "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
{
entryToRemove = item;
break;
}
}
if (entryToRemove != null)
{
accessControlListUpdate.Remove(entryToRemove);
directoryClient.SetAccessControlList(accessControlListUpdate);
}
}
Remover entradas da ACL recursivamente
Para remover entradas ACL recursivamente, crie um novo objeto ACL para entrada ACL a ser removida e, em seguida, use esse objeto na operação remover ACL. Não obtenha a ACL existente, apenas forneça as entradas da ACL a serem removidas.
Remova as entradas da ACL chamando o método DataLakeDirectoryClient.RemoveAccessControlRecursiveAsync . Passe este método uma lista de PathAccessControlItem. Cada PathAccessControlItem define uma entrada ACL.
Se quiser remover uma entrada de ACL padrão , você pode definir a propriedade PathAccessControlItem.DefaultScope do PathAccessControlItem como true.
Este exemplo remove uma entrada ACL da ACL do diretório chamado my-parent-directory
. Esse método aceita um parâmetro booleano chamado isDefaultScope
que especifica se a entrada deve ser removida da ACL padrão. Esse parâmetro é usado no construtor do PathAccessControlItem.
public async Task RemoveACLsRecursively(DataLakeServiceClient serviceClient, bool isDefaultScope)
{
DataLakeDirectoryClient directoryClient =
serviceClient.GetFileSystemClient("my-container").
GetDirectoryClient("my-parent-directory");
List<RemovePathAccessControlItem> accessControlListForRemoval =
new List<RemovePathAccessControlItem>()
{
new RemovePathAccessControlItem(AccessControlType.User, isDefaultScope,
entityId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
};
await directoryClient.RemoveAccessControlRecursiveAsync
(accessControlListForRemoval, null);
}
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 um token de continuação em caso de falha. O aplicativo pode chamar esse método de exemplo novamente após o erro ter sido resolvido e passar o token de continuação. Se esse método de exemplo for chamado pela primeira vez, o aplicativo poderá passar um valor de para o parâmetro de token de null
continuação.
public async Task<string> ResumeAsync(DataLakeServiceClient serviceClient,
DataLakeDirectoryClient directoryClient,
List<PathAccessControlItem> accessControlList,
string continuationToken)
{
try
{
var accessControlChangeResult =
await directoryClient.SetAccessControlRecursiveAsync(
accessControlList, continuationToken: continuationToken, null);
if (accessControlChangeResult.Value.Counters.FailedChangesCount > 0)
{
continuationToken =
accessControlChangeResult.Value.ContinuationToken;
}
return continuationToken;
}
catch (Exception ex)
{
Console.WriteLine(ex.ToString());
return continuationToken;
}
}
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, passe um objeto AccessControlChangedOptions e defina a propriedade ContinueOnFailure desse objeto como true
.
Este exemplo define entradas ACL recursivamente. Se esse código encontrar um erro de permissão, ele registrará essa falha e continuará a execução. Este exemplo imprime o número de falhas no console.
public async Task ContinueOnFailureAsync(DataLakeServiceClient serviceClient,
DataLakeDirectoryClient directoryClient,
List<PathAccessControlItem> accessControlList)
{
var accessControlChangeResult =
await directoryClient.SetAccessControlRecursiveAsync(
accessControlList, null, new AccessControlChangeOptions()
{ ContinueOnFailure = true });
var counters = accessControlChangeResult.Value.Counters;
Console.WriteLine("Number of directories changed: " +
counters.ChangedDirectoriesCount.ToString());
Console.WriteLine("Number of files changed: " +
counters.ChangedFilesCount.ToString());
Console.WriteLine("Number of failures: " +
counters.FailedChangesCount.ToString());
}
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
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários