Biblioteca de clientes do Data Lake do Arquivo de Armazenamento do Azure para JavaScript – versão 12.23.0

  • Artigo

O ADLS (Azure Data Lake Storage) inclui todos os recursos necessários para facilitar que desenvolvedores, cientistas de dados e analistas armazenem dados de qualquer tamanho, forma e velocidade e façam todos os tipos de processamento e análise entre plataformas e idiomas. Ele remove as complexidades de ingerir e armazenar todos os seus dados, tornando mais rápido começar a trabalhar com análises em lote, streaming e interativa.

Este projeto fornece uma biblioteca de clientes no JavaScript que facilita o consumo do serviço Data Lake do Armazenamento do Microsoft Azure.

Use as bibliotecas de cliente neste pacote para:

  • Criar/listar/excluir sistemas de arquivos
  • Criar/ler/listar/atualizar/excluir caminhos, diretórios e arquivos

links de chave:

Introdução

Ambientes com suporte no momento

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

  • Uma assinatura do Azure
  • Uma conta de armazenamento

Instalar o pacote

A maneira preferida de instalar a biblioteca de clientes do Azure Storage Data Lake para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela de terminal:

npm install @azure/storage-file-datalake

Autenticar o cliente

O Armazenamento do Azure dá suporte a várias maneiras de autenticação. Para interagir com o serviço Azure Data Lake Storage, você precisará criar uma instância de um cliente de Armazenamento – DataLakeServiceClient, DataLakeFileSystemClientou DataLakePathClient, por exemplo. Consulte exemplos para criar o DataLakeServiceClient para saber mais sobre autenticação.

Azure Active Directory

O serviço Azure Data Lake Storage dá suporte ao uso do Azure Active Directory para autenticar solicitações em suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credencial que seu aplicativo pode usar para fazer isso. Consulte o README para @azure/identity para obter mais detalhes e exemplos para começar.

Compatibilidade

Essa biblioteca é compatível com Node.js e navegadores e validada em versões de Node.js LTS (>=8.16.0) e versões mais recentes do Chrome, Firefox e Edge.

Web Workers

Essa biblioteca exige que determinados objetos DOM estejam disponíveis globalmente quando usados no navegador, que os trabalhos da Web não disponibilizam por padrão. Você precisará polifilá-los para fazer essa biblioteca funcionar em trabalhos web.

Para obter mais informações, consulte nossa documentação para usar o SDK do Azure para JS no Web Workers

Essa biblioteca depende das seguintes APIs do DOM que precisam de polyfills externos carregados quando usados em trabalhos Web:

Diferenças entre Node.js e navegadores

Há diferenças entre Node.js e o runtime dos navegadores. Ao começar a usar essa biblioteca, preste atenção às APIs ou classes marcadas com "SOMENTE DISPONÍVEL EM NODE.JS RUNTIME" ou "SOMENTE DISPONÍVEL EM NAVEGADORES".

  • Se um arquivo mantiver dados compactados no formato gzip ou deflate e sua codificação de conteúdo for definida adequadamente, o comportamento de download será diferente entre Node.js e navegadores. Em Node.js clientes de armazenamento baixarão o arquivo em seu formato compactado, enquanto nos navegadores os dados serão baixados em formato descompactado.
Recursos, interfaces, classes ou funções disponíveis apenas em Node.js
  • Autorização de chave compartilhada com base no nome da conta e na chave da conta
    • StorageSharedKeyCredential
  • Geração de SAS (Assinatura de Acesso Compartilhado)
    • generateAccountSASQueryParameters()
    • generateDataLakeSASQueryParameters()
  • Carregamento e download paralelos. Observe que DataLakeFileClient.upload() está disponível em Node.js e navegadores.
    • DataLakeFileClient.uploadFile()
    • DataLakeFileClient.uploadStream()
    • DataLakeFileClient.readToBuffer()
    • DataLakeFileClient.readToFile()
Recursos, interfaces, classes ou funções disponíveis somente em navegadores
  • N/A

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento .

CORS

Você precisa configurar regras de CORS (Compartilhamento de Recursos entre Origens) para sua conta de armazenamento se precisar desenvolver para navegadores. Acesse o portal do Azure e o Gerenciador de Armazenamento do Azure, localize sua conta de armazenamento, crie novas regras CORS para serviços de blob/fila/arquivo/tabela.

Por exemplo, você pode criar as seguintes configurações de CORS para depuração. Porém, personalize as configurações cuidadosamente de acordo com seus requisitos no ambiente de produção.

  • Origens permitidas: *
  • Verbos permitidos: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
  • Cabeçalhos permitidos: *
  • Cabeçalhos expostos: *
  • Idade máxima (segundos): 86400

Aviso: o Data Lake atualmente compartilha as configurações de CORS para o serviço de blob.

Principais conceitos

O Azure Data Lake Storage Gen2 foi projetado para:

  • Servir vários petabytes de informações enquanto sustenta centenas de gigabits de taxa de transferência
  • Permitir que você gerencie facilmente grandes quantidades de dados

Os principais recursos do DataLake Storage Gen2 incluem:

  • Acesso compatível com Hadoop
  • Um super conjunto de permissões POSIX
  • Econômico em termos de capacidade e transações de armazenamento de baixo custo
  • Driver otimizado para análise de Big Data

Uma parte fundamental do Data Lake Storage Gen2 é a adição de um namespace hierárquico ao Armazenamento de Blobs. O namespace hierárquico organiza objetos/arquivos em uma hierarquia de diretórios para acesso eficiente a dados.

No passado, a análise baseada em nuvem tinha que comprometer-se em áreas de desempenho, gerenciamento e segurança. O Data Lake Storage Gen2 aborda cada um desses aspectos das seguintes maneiras:

  • O desempenho é otimizado porque você não precisa copiar ou transformar dados como um pré-requisito para análise. O namespace hierárquico melhora muito o desempenho das operações de gerenciamento de diretório, o que melhora o desempenho geral do trabalho.
  • O gerenciamento é mais fácil porque você pode organizar e manipular arquivos por meio de diretórios e subdiretórios.
  • A segurança é exequível porque você pode definir permissões POSIX em diretórios ou arquivos individuais.
  • A eficácia do custo é possível à medida que o Data Lake Storage Gen2 é criado com base no armazenamento de Blobs do Azure de baixo custo. Os recursos adicionais reduzem ainda mais o custo total de propriedade para executar a análise de Big Data no Azure.

O Data Lake Storage oferece três tipos de recursos:

  • A conta de armazenamento usada por meio de DataLakeServiceClient
  • Um sistema de arquivos na conta de armazenamento usada por meio de DataLakeFileSystemClient
  • Um caminho em um sistema de arquivos usado por meio de DataLakeDirectoryClient ou DataLakeFileClient
Azure DataLake Gen2 BLOB
Sistema de arquivos Recipiente
Caminho (arquivo ou diretório) BLOB

Observação: essa biblioteca de clientes só dá suporte a contas de armazenamento com o HNS (namespace hierárquico) habilitado.

Exemplos

Importar o pacote

Para usar os clientes, importe o pacote para o arquivo:

const AzureStorageDataLake = require("@azure/storage-file-datalake");

Como alternativa, importe seletivamente apenas os tipos necessários:

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

Criar o cliente do serviço data lake

O DataLakeServiceClient requer uma URL para o serviço data lake e uma credencial de acesso. Opcionalmente, ele também aceita algumas configurações no parâmetro options.

com DefaultAzureCredential de @azure/identity pacote

maneira recomendada de instanciar um DataLakeServiceClient

Notar. Atualmente, o Azure Data Lake reutiliza funções relacionadas a blob, como "Proprietário de Dados de Blob de Armazenamento" durante a autenticação OAuth do AAD a seguir.

Configuração: Referência – Autorizar o acesso a blobs (data lake) e filas com o Azure Active Directory de um aplicativo cliente – /azure/storage/common/storage-auth-aad-app

  • Registre um novo aplicativo do AAD e conceda permissões para acessar o Armazenamento do Azure em nome do usuário conectado.

    • Registrar um novo aplicativo no Azure Active Directory(no portal do Azure) – /azure/active-directory/develop/quickstart-register-app
    • Na seção API permissions, selecione Add a permission e escolha Microsoft APIs.
    • Escolha Azure Storage e marque a caixa de seleção ao lado de user_impersonation e clique em Add permissions. Isso permitiria que o aplicativo acessasse o Armazenamento do Azure em nome do usuário conectado.

  • Conceder acesso aos dados do Azure Data Lake com RBAC no Portal do Azure

    • Funções RBAC para blobs (data lake) e filas – /azure/storage/common/storage-auth-aad-rbac-portal.
    • No portal do Azure, acesse sua conta de armazenamento e atribua função de Colaborador de Dados de Blob de Armazenamento ao aplicativo AAD registrado na guia Access control (IAM) (na barra de navegação do lado esquerdo da sua conta de armazenamento no portal do azure).

  • Configuração do ambiente para o exemplo

    • Na página de visão geral do aplicativo AAD, anote o CLIENT ID e o TENANT ID. Na guia "Certificados & Segredos", crie um segredo e observe isso.
    • Verifique se você tem AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET como variáveis de ambiente para executar com êxito o exemplo(Pode aproveitar process.env).
const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

Consulte o exemplo de autenticação do Azure AD para obter um exemplo completo usando esse método.

[Observação - As etapas acima são apenas para Node.js]

usando a cadeia de conexão

Como alternativa, você pode criar uma instância de um DataLakeServiceClient usando o método estático fromConnectionString() com a cadeia de conexão completa como o argumento. (A cadeia de conexão pode ser obtida no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

com StorageSharedKeyCredential

Como alternativa, você cria uma instância de um DataLakeServiceClient com um StorageSharedKeyCredential passando o nome da conta e a chave da conta como argumentos. (O nome da conta e a chave de conta podem ser obtidos no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]

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

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  sharedKeyCredential
);

com token SAS

Além disso, você pode criar uma instância de um DataLakeServiceClient com uma SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS no Portal do Azure ou gerar um usando generateAccountSASQueryParameters().

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

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const serviceClientWithSAS = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`
);

Criar um novo sistema de arquivos

Use DataLakeServiceClient.getFileSystemClient() para obter uma instância do cliente do sistema de arquivos e, em seguida, criar um novo recurso do sistema de arquivos.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  // Create a file system
  const fileSystemName = `newfilesystem${new Date().getTime()}`;
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const createResponse = await fileSystemClient.create();
  console.log(`Create file system ${fileSystemName} successfully`, createResponse.requestId);
}

main();

Listar os sistemas de arquivos

Use DataLakeServiceClient.listFileSystems() função para iterar os sistemas de arquivos, com a nova sintaxe for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let fileSystems = datalakeServiceClient.listFileSystems();
  for await (const fileSystem of fileSystems) {
    console.log(`File system ${i++}: ${fileSystem.name}`);
  }
}

main();

Como alternativa, sem usar for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let iter = datalakeServiceClient.listFileSystems();
  let fileSystemItem = await iter.next();
  while (!fileSystemItem.done) {
    console.log(`File System ${i++}: ${fileSystemItem.value.name}`);
    fileSystemItem = await iter.next();
  }
}

main();

Além disso, há suporte para paginação para listagem também por meio de byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  for await (const response of datalakeServiceClient
    .listFileSystems()
    .byPage({ maxPageSize: 20 })) {
    if (response.fileSystemItems) {
      for (const fileSystem of response.fileSystemItems) {
        console.log(`File System ${i++}: ${fileSystem.name}`);
      }
    }
  }
}

main();

Criar e excluir um diretório

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const directoryClient = fileSystemClient.getDirectoryClient("directory");
  await directoryClient.create();
  await directoryClient.delete();
}

main();

Criar um arquivo

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  const content = "Hello world!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = fileSystemClient.getFileClient(fileName);
  await fileClient.create();
  await fileClient.append(content, 0, content.length);
  await fileClient.flush(content.length);
  console.log(`Create and upload file ${fileName} successfully`);
}

main();

Listar caminhos dentro de um sistema de arquivos

Semelhante à listagem de sistemas de arquivos.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  let i = 1;
  let paths = fileSystemClient.listPaths();
  for await (const path of paths) {
    console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
  }
}

main();

Baixar um arquivo e convertê-lo em uma cadeia de caracteres (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  defaultAzureCredential
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const fileClient = fileSystemClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadResponse.readableStreamBody
  const downloadResponse = await fileClient.read();
  const downloaded = await streamToBuffer(downloadResponse.readableStreamBody);
  console.log("Downloaded file content:", downloaded.toString());

  // [Node.js only] A helper method used to read a Node.js readable stream into a Buffer.
  async function streamToBuffer(readableStream) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on("end", () => {
        resolve(Buffer.concat(chunks));
      });
      readableStream.on("error", reject);
    });
  }
}

main();

Baixar um arquivo e convertê-lo em uma cadeia de caracteres (Navegadores)

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

const account = "<account>";
const sas="<sas token>"

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`
);

const fileSystemName = "<file system name>";
const fileName = "<file name>"

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const fileClient = fileSystemClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadResponse.contentAsBlob
  const downloadResponse = await fileClient.read();
  const downloaded = await blobToString(await downloadResponse.contentAsBlob);
  console.log(
    "Downloaded file content",
    downloaded
  );

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob: Blob): Promise<string> {
    const fileReader = new FileReader();
    return new Promise<string>((resolve, reject) => {
      fileReader.onloadend = (ev: any) => {
        resolve(ev.target!.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Solucionando problemas

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Próximas etapas

Mais exemplos de código:

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

impressões