Biblioteca de cliente do Azure Storage File Data Lake para JavaScript - versão 12.23.0

O Azure Data Lake Storage (ADLS) inclui todos os recursos necessários para tornar mais fácil para desenvolvedores, cientistas de dados e analistas armazenar dados de qualquer tamanho, forma e velocidade, além de fazer todos os tipos de processamento e análise entre plataformas e idiomas. Ele elimina as complexidades de ingerir e armazenar todos os seus dados, ao mesmo tempo em que torna mais rápido começar a trabalhar com análises em lote, streaming e interativas.

Este projeto fornece uma biblioteca de cliente em JavaScript que facilita o consumo do serviço Microsoft Azure Storage Data Lake.

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

• Código fonte
• Pacote (npm)
• de documentação de referência da API
• Documentação do produto
• Amostras
• APIs REST do Azure Storage Data Lake

Primeiros passos

Ambientes atualmente suportados

• versões LTS do Node.js
• Versões mais recentes do Safari, Chrome, Edge e Firefox.

Consulte o nosso de 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 cliente do Azure Storage Data Lake para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela do 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 de Armazenamento do Azure Data Lake, 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 Ative Directory
• Chave compartilhada
• Assinaturas de acesso compartilhado

Azure Ative Directory

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

Compatibilidade

Esta biblioteca é compatível com Node.js e navegadores, e validada em relação às versões LTS Node.js (>= 8.16.0) e versões mais recentes do Chrome, Firefox e Edge.

Trabalhadores da Web

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

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

Essa biblioteca depende das seguintes APIs DOM que precisam de polipreenchimentos externos carregados quando usados em web workers:

• document
• DOMParser
• Node
• XMLSerializer

Diferenças entre Node.js e navegadores

Há diferenças entre Node.js e o tempo de execução dos navegadores. Ao começar a usar essa biblioteca, preste atenção às APIs ou classes marcadas com "APENAS DISPONÍVEL EM TEMPO DE EXECUÇÃO NODE.JS" ou "DISPONÍVEL APENAS EM NAVEGADORES".

• Se um arquivo contiver dados compactados em formato gzip ou deflate e sua codificação de conteúdo for definida de acordo, o comportamento de download será diferente entre Node.js e navegadores. Em Node.js os clientes de armazenamento baixarão o arquivo em seu formato compactado, enquanto nos navegadores os dados serão baixados em formato descompactado.

Funcionalidades, interfaces, classes ou funções disponíveis apenas no Node.js

• Autorização de chave compartilhada com base no nome da conta e na chave da conta
  • StorageSharedKeyCredential
• Geração de Assinatura de Acesso Compartilhado (SAS)
  • generateAccountSASQueryParameters()
  • generateDataLakeSASQueryParameters()
• Upload e download paralelos. Observe que DataLakeFileClient.upload() está disponível em Node.js e navegadores.
  • DataLakeFileClient.uploadFile()
  • DataLakeFileClient.uploadStream()
  • DataLakeFileClient.readToBuffer()
  • DataLakeFileClient.readToFile()

Funcionalidades, interfaces, classes ou funções disponíveis apenas em browsers

• N/A

Pacote JavaScript

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

CORS

Você precisa configurar regras de de compartilhamento de recursos entre origens (Cross-Origin Resourcesharing) para sua conta de armazenamento se precisar desenvolver para navegadores. Vá para o portal do Azure e o Gerenciador de Armazenamento do Azure, encontre 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. Mas por favor, personalize as configurações cuidadosamente de acordo com suas necessidades 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: Atualmente, o Data Lake compartilha configurações de CORS para o serviço de blob.

Conceitos-chave

O Azure Data Lake Storage Gen2 foi projetado para:

• Sirva vários petabytes de informações enquanto sustenta centenas de gigabits de taxa de transferência
• Permitem-lhe gerir 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
• Custo-benefício em termos de capacidade de armazenamento de baixo custo e transações
• 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 Blob. O namespace hierárquico organiza objetos/arquivos em uma hierarquia de diretórios para acesso eficiente aos dados.

No passado, a análise baseada na nuvem tinha de comprometer as áreas de desempenho, gestão e segurança. O Data Lake Storage Gen2 aborda cada um desses aspetos das seguintes maneiras:

• O desempenho é otimizado porque você não precisa copiar ou transformar dados como 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 é aplicável porque você pode definir permissões POSIX em diretórios ou arquivos individuais.
• A relação custo-benefício é possível à medida que o Data Lake Storage Gen2 é criado sobre o armazenamento de Blob do Azure de baixo custo. Os recursos adicionais reduzem ainda mais o custo total de propriedade para executar análises de big data no Azure.

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

• A conta de armazenamento usada via DataLakeServiceClient
• Um sistema de arquivos na conta de armazenamento usada via DataLakeFileSystemClient
• Um caminho em um sistema de arquivos usado via DataLakeDirectoryClient ou DataLakeFileClient

Azure DataLake Gen2	Blob
Sistema de arquivos	Contentor
Caminho (arquivo ou diretório)	Blob

Nota: Esta biblioteca de cliente suporta apenas contas de armazenamento com namespace hierárquico (HNS) habilitado.

Exemplos

• Importar o pacote
• Criar o cliente de serviço de data lake
• Criar um novo sistema de arquivos
• Listar os sistemas de arquivos
• Criar e excluir um diretório
• Criar um arquivo
• Listar caminhos dentro de um sistema de arquivos
• Baixe um arquivo e converta-o em uma string (Node.js)
• Baixe um arquivo e converta-o em uma string (Navegadores)

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 de serviço data lake

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

com DefaultAzureCredential de @azure/identity pacote

Maneira recomendada de instanciar um DataLakeServiceClient

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

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

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

  • Registrar um novo aplicativo no Azure Ative Directory(no azure-portal) - /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 azure, vá para 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 azure).

• Configuração do ambiente para o exemplo

  • Na página de visão geral do seu aplicativo AAD, anote o CLIENT ID e TENANT ID. Na guia "Certificados & segredos", crie um segredo e anote isso.
  • Certifique-se de ter AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET como variáveis de ambiente para executar com êxito a amostra(Pode alavancar 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 de exemplo Azure AD Auth para obter um exemplo completo usando esse método.

[Nota - Os passos acima são apenas para Node.js]

Usando a cadeia de conexão

Como alternativa, você pode instanciar um DataLakeServiceClient usando o método estático fromConnectionString() com a cadeia de conexão completa como argumento. (A cadeia de conexão pode ser obtida no portal azure.) [DISPONÍVEL APENAS EM TEMPO DE EXECUÇÃO NODE.JS]

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

com StorageSharedKeyCredential

Como alternativa, você instancia um DataLakeServiceClient com um StorageSharedKeyCredential passando nome-conta e chave-conta como argumentos. (O nome da conta e a chave da conta podem ser obtidos no portal azure.) [DISPONÍVEL APENAS EM TEMPO DE EXECUÇÃO NODE.JS]

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 instanciar um DataLakeServiceClient com uma SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS do 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 de cliente do sistema de arquivos e, em seguida, crie 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();

Alternativamente, 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, a paginação também é suportada para listagem através 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 ficheiro

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 a listar 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();

Baixe um arquivo e converta-o em uma string (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 string (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();

Solução de 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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

Mais exemplos de código:

• Exemplos de armazenamento do DataLake (JavaScript)
• Exemplos de armazenamento DataLake (TypeScript)
• Casos de teste de armazenamento DataLake

Contribuição

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