Usar o SDK do JavaScript em Node.js para gerenciar ACLs no Azure Data Lake Storage Gen2

  • Artigo

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

Pacote (Gerenciador de pacotes do Node) | Exemplos | Enviar comentários

Pré-requisitos

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

  • Uma conta de armazenamento precisa ter o HNS (namespace hierárquico) habilitado. Siga estas instruções para criar um.

  • CLI do Azure versão 2.6.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 de Proprietário de Dados do Blob de Armazenamento no escopo do contêiner, conta de armazenamento, grupo de recursos pai ou assinatura de destino.

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

    • Chave de conta de armazenamento.

Configurar o seu projeto

Instale biblioteca de clientes do Data Lake para JavaScript abrindo uma janela de terminal e, em seguida, digitando o comando a seguir.

npm install @azure/storage-file-datalake

Importe o pacote storage-file-datalake colocando essa instrução na parte superior do seu arquivo de código.

const {
AzureStorageDataLake,
DataLakeServiceClient,
StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");

Conectar à conta

Para usar os trechos de código neste artigo, será necessário criar uma instância de DataLakeServiceClient que representa a conta de armazenamento.

Conectar usando o Microsoft Entra ID

Observação

Se estiver usando o Microsoft Entra ID para autorizar acesso, confira se a função de Proprietário de dados do blob de armazenamento foi atribuída à entidade de segurança. Para saber mais sobre como as permissões de ACL são aplicadas e os efeitos de alterá-las, confira Modelo de controle de acesso no Azure Data Lake Storage Gen2.

É possível usar a Biblioteca de clientes de identidade do Azure para JS para autenticar o aplicativo com o Microsoft Entra ID.

Como parte desse processo, primeiro será necessário atribuir uma das seguintes funções do RBAC do Azure (controle de acesso baseado em função do Azure) à sua entidade de segurança:

Função Capacidade de configuração de ACL
Proprietário de Dados do Blob de Armazenamento Todos os diretórios e arquivos na conta.
Colaborador de dados de blob de armazenamento Somente diretórios e arquivos de propriedade da entidade de segurança.

Em seguida, crie uma instância DataLakeServiceClient e passe em uma nova instância da classe DefaultAzureCredential.

function GetDataLakeServiceClientAD(accountName) {

  const dataLakeServiceClient = new DataLakeServiceClient(
      `https://${accountName}.dfs.core.windows.net`,
      new DefaultAzureCredential()
  );

  return dataLakeServiceClient;
}

Para saber mais sobre como usar DefaultAzureCredential para autorizar o acesso a dados, confira Visão geral: autenticar aplicativos JavaScript no Azure usando o SDK 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). Esse exemplo cria uma instância DataLakeServiceClient autorizada com a chave de conta.


function GetDataLakeServiceClient(accountName, accountKey) {

  const sharedKeyCredential =
     new StorageSharedKeyCredential(accountName, accountKey);

  const dataLakeServiceClient = new DataLakeServiceClient(
      `https://${accountName}.dfs.core.windows.net`, sharedKeyCredential);

  return dataLakeServiceClient;
}

Cuidado

A autorização com Chave Compartilhada não é recomendada, pois pode ser menos segura. Para uma segurança ideal, desabilite a autorização por meio da Chave Compartilhada para sua conta de armazenamento, conforme descrito em Impedir autorização de Chave Compartilhada para uma conta do Armazenamento do Microsoft Azure.

O uso de chaves de acesso e cadeias de conexão deve ser limitado a aplicativos iniciais de prova de conceito ou protótipos de desenvolvimento que não acessem dados confidenciais ou de produção. Caso contrário, as classes de autenticação baseadas em token disponíveis no SDK do Azure devem ser sempre preferenciais ao autenticar 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 Microsoft Azure. Para obter mais informações, confira Autorizar operações para acesso a dados.

Obter e definir uma ACL de diretório

Este exemplo obtém e define a ACL de um diretório chamado my-directory. Este exemplo fornece ao o usuário proprietário as permissões de leitura, gravação e execução, fornece ao grupo proprietário somente permissões de leitura e execução e concede a todos os outros acesso de leitura.

Observação

Se o seu aplicativo autorizar o acesso usando Microsoft Entra ID, confira se a função de Proprietário de dados do blob de armazenamento foi atribuída à entidade de segurança que seu aplicativo usa para autorizar o acesso. Para saber mais sobre como as permissões de ACL são aplicadas e os efeitos por alterá-las, confira Controle de acesso no Azure Data Lake Storage Gen2.

async function ManageDirectoryACLs(fileSystemClient) {

    const directoryClient = fileSystemClient.getDirectoryClient("my-directory");
    const permissions = await directoryClient.getAccessControl();

    console.log(permissions.acl);

    const acl = [
    {
      accessControlType: "user",
      entityId: "",
      defaultScope: false,
      permissions: {
        read: true,
        write: true,
        execute: true
      }
    },
    {
      accessControlType: "group",
      entityId: "",
      defaultScope: false,
      permissions: {
        read: true,
        write: false,
        execute: true
      }
    },
    {
      accessControlType: "other",
      entityId: "",
      defaultScope: false,
      permissions: {
        read: true,
        write: true,
        execute: false
      }

    }

  ];

  await directoryClient.setAccessControl(acl);
}

Também é possível 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.

Obter e definir uma ACL de arquivo

Este exemplo obtém e define a ACL de um arquivo denominado upload-file.txt. Este exemplo fornece ao o usuário proprietário as permissões de leitura, gravação e execução, fornece ao grupo proprietário somente permissões de leitura e execução e concede a todos os outros acesso de leitura.

Observação

Se o seu aplicativo autorizar o acesso usando Microsoft Entra ID, confira se a função de Proprietário de dados do blob de armazenamento foi atribuída à entidade de segurança que seu aplicativo usa para autorizar o acesso. Para saber mais sobre como as permissões de ACL são aplicadas e os efeitos por alterá-las, confira Controle de acesso no Azure Data Lake Storage Gen2.

async function ManageFileACLs(fileSystemClient) {

  const fileClient = fileSystemClient.getFileClient("my-directory/uploaded-file.txt");
  const permissions = await fileClient.getAccessControl();

  console.log(permissions.acl);

  const acl = [
  {
    accessControlType: "user",
    entityId: "",
    defaultScope: false,
    permissions: {
      read: true,
      write: true,
      execute: true
    }
  },
  {
    accessControlType: "group",
    entityId: "",
    defaultScope: false,
    permissions: {
      read: true,
      write: false,
      execute: true
    }
  },
  {
    accessControlType: "other",
    entityId: "",
    defaultScope: false,
    permissions: {
      read: true,
      write: true,
      execute: false
    }

  }

];

await fileClient.setAccessControl(acl);
}

Confira também