Libreria client Data Lake di archiviazione di Azure per JavaScript - versione 12.28.1

Azure Data Lake Storage (ADLS) include tutte le funzionalità necessarie per semplificare gli sviluppatori, i data scientist e gli analisti per archiviare i dati di qualsiasi dimensione, forma e velocità ed eseguire tutti i tipi di elaborazione e analisi tra piattaforme e linguaggi. Rimuove le complessità dell'inserimento e dell'archiviazione di tutti i dati, semplificando al contempo l'avvio e l'esecuzione con analisi batch, streaming e interattive.

Questo progetto fornisce una libreria client in JavaScript che semplifica l'uso del servizio Data Lake di Archiviazione di Microsoft Azure.

Usare le librerie client in questo pacchetto per:

Creare/elencare/eliminare file system
Creare/leggere/elencare/aggiornare/eliminare percorsi, directory e file

Collegamenti chiave:

Come iniziare

Ambienti attualmente supportati

Versioni LTS di Node.js
Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per ulteriori dettagli, consulta la nostra politica di supporto .

Prerequisites

Una sottoscrizione di Azure
Un account di archiviazione

Installare il pacchetto

Il modo migliore per installare la libreria client di Azure Storage Data Lake per JavaScript consiste nell'usare la gestione pacchetti npm. Digitare quanto segue in una finestra del terminale:

npm install @azure/storage-file-datalake

Autenticare il client

Archiviazione di Azure supporta diversi modi per eseguire l'autenticazione. Per interagire con il servizio Azure Data Lake Storage è necessario creare un'istanza di un client DataLakeServiceClientdi archiviazione, ad esempio , DataLakeFileSystemClient, o DataLakePathClient . Per altre informazioni sull'autenticazioneDataLakeServiceClient, vedere gli esempi per la creazione di .

Azure Active Directory
Chiave condivisa
Firme di accesso condiviso

Azure Active Directory

Il servizio Azure Data Lake Storage supporta l'uso di Azure Active Directory per autenticare le richieste alle API. Il pacchetto @azure/identity offre diversi tipi di credenziali che l'applicazione può usare per eseguire questa operazione. Si prega di consultare il file README per @azure/identity ulteriori dettagli ed esempi per iniziare.

Compatibility

Questa libreria è compatibile con Node.js e browser e convalidata rispetto alle versioni di LTS Node.js (>=8.16.0) e alle versioni più recenti di Chrome, Firefox ed Edge.

Lavoratori del Web

Questa libreria richiede che determinati oggetti DOM siano disponibili a livello globale quando vengono usati nel browser, che i web worker non rendono disponibili per impostazione predefinita. Sarà necessario eseguire il polyfill per rendere questa libreria funzionante nei web worker.

Per altre informazioni, vedere la documentazione per l'uso di Azure SDK per JS nei Web Worker

Questa libreria dipende dalle API DOM seguenti che richiedono polyfill esterni caricati quando vengono usati nei web worker:

Differenze tra Node.js e browser

Ci sono differenze tra il runtime del Node.js e quello dei browser. Quando si inizia a utilizzare questa libreria, prestare attenzione alle API o alle classi contrassegnate con "DISPONIBILE SOLO IN NODE.JS RUNTIME" o "DISPONIBILE SOLO NEI BROWSER".

Se un file contiene dati compressi in un formato o gzip e deflate la codifica del contenuto è impostata di conseguenza, il comportamento di download è diverso tra Node.js e browser. In Node.js i client di archiviazione scaricheranno il file nel suo formato compresso, mentre nei browser i dati verranno scaricati in formato decompresso.

Caratteristiche, interfacce, classi o funzioni disponibili solo in Node.js

Autorizzazione chiave condivisa basata sul nome dell'account e sulla chiave dell'account
- StorageSharedKeyCredential
Generazione della firma di accesso condiviso
- generateAccountSASQueryParameters()
- generateDataLakeSASQueryParameters()
Caricamento e download paralleli. Si noti che DataLakeFileClient.upload() è disponibile sia in Node.js che nei browser.
- DataLakeFileClient.uploadFile()
- DataLakeFileClient.uploadStream()
- DataLakeFileClient.readToBuffer()
- DataLakeFileClient.readToFile()

Funzionalità, interfacce, classi o funzioni disponibili solo nei browser

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per i dettagli su come eseguire questa operazione, consulta la nostra documentazione sui raggruppamenti.

CORS

Se è necessario sviluppare per i browser, è necessario configurare le regole CORS (Cross-Origin Resource Sharing) per l'account di archiviazione. Passare al portale di Azure e Azure Storage Explorer, trovare l'account di archiviazione, creare nuove regole CORS per i servizi BLOB/queue/file/table.

Ad esempio, è possibile creare le impostazioni CORS seguenti per il debug. Ma personalizzare attentamente le impostazioni in base ai requisiti nell'ambiente di produzione.

Origini consentite: *
Verbi consentiti: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Intestazioni consentite: *
Intestazioni esposte: *
Età massima (secondi): 86400

Nota: Data Lake condivide attualmente le impostazioni CORS per il servizio BLOB.

Concetti chiave

Azure Data Lake Storage Gen2 è stato progettato per:

Servire più petabyte di informazioni mantenendo centinaia di gigabit di velocità effettiva
Consente di gestire facilmente grandi quantità di dati

Le funzionalità principali di DataLake Storage Gen2 includono:

Accesso compatibile con Hadoop
Un super set di autorizzazioni POSIX
Conveniente in termini di capacità e transazioni di archiviazione a basso costo
Driver ottimizzato per l'analisi di Big Data

Una parte fondamentale di Data Lake Storage Gen2 è l'aggiunta di uno spazio dei nomi gerarchico all'archiviazione BLOB. Lo spazio dei nomi gerarchico organizza oggetti/file in una gerarchia di directory per un accesso efficiente ai dati.

In passato, l'analisi basata sul cloud doveva compromettere le prestazioni, la gestione e la sicurezza. Data Lake Storage Gen2 affronta ognuno di questi aspetti nei modi seguenti:

Le prestazioni sono ottimizzate perché non è necessario copiare o trasformare i dati come prerequisito per l'analisi. Lo spazio dei nomi gerarchico migliora notevolmente le prestazioni delle operazioni di gestione delle directory, migliorando così le prestazioni complessive dei processi.
La gestione è più semplice perché è possibile organizzare e modificare i file tramite directory e sottodirectory.
La sicurezza è applicabile perché è possibile definire le autorizzazioni POSIX per le directory o i singoli file.
L'efficacia dei costi è resa possibile perché Data Lake Storage Gen2 si basa sull'archiviazione BLOB di Azure a basso costo. Le funzionalità aggiuntive riduce ulteriormente il costo totale di proprietà per l'esecuzione di analisi dei Big Data in Azure.

Data Lake Storage offre tre tipi di risorse:

L'account di archiviazione utilizzato tramiteDataLakeServiceClient
Un file system nell'account di archiviazione usato tramite DataLakeFileSystemClient
Un percorso in un file system utilizzato tramite DataLakeDirectoryClient o DataLakeFileClient

Azure DataLake Gen2	Blob
Filesystem	Container
Percorso (file o directory)	Blob

Nota: questa libreria client supporta solo gli account di archiviazione con spazio dei nomi gerarchico (HNS) abilitato.

Examples

Importare il pacchetto
Creare il client del servizio data lake
Creare un nuovo file system
Elenca i file system
Creare ed eliminare una directory
Creare un file
Elencare i percorsi all'interno di un file system
Scarica un file e convertilo in una stringa (Node.js)
Scaricare un file e convertirlo in una stringa (Browser)

Importare il pacchetto

Per usare i client, importare il pacchetto nel file:

import * as AzureStorageDataLake from "@azure/storage-file-datalake";

In alternativa, importare in modo selettivo solo i tipi necessari:

import { DataLakeServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-datalake";

Creare il client del servizio Data Lake

Richiede DataLakeServiceClient un URL per il servizio data lake e una credenziale di accesso. Facoltativamente, accetta anche alcune impostazioni nel options parametro.

con `DefaultAzureCredential` dal `@azure/identity` pacchetto

Modo consigliato per creare un'istanza di un DataLakeServiceClient

Notice. Azure Data Lake riutilizza attualmente i ruoli correlati ai BLOB, ad esempio "Proprietario dati BLOB di archiviazione" durante l'autenticazione OAuth di AAD.

Configurazione: Riferimento - Autorizzare l'accesso ai BLOB (data lake) e alle code con Azure Active Directory da un'applicazione client - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

Registrare una nuova applicazione AAD e concedere le autorizzazioni per accedere ad Archiviazione di Azure per conto dell'utente connesso.
- Registrare una nuova applicazione in Azure Active Directory (nel portale azure) - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- API permissions Nella sezione, seleziona Add a permission e scegli Microsoft APIs.
- Selezionare Azure Storage la casella di controllo accanto a user_impersonation e quindi fare clic su Add permissions. In questo modo l'applicazione può accedere ad Archiviazione di Azure per conto dell'utente connesso.
Concedere l'accesso ai dati di Azure Data Lake con il controllo degli accessi in base al ruolo nel portale di Azure
- Ruoli RBAC per BLOB (data lake) e code - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- Nel portale di Azure passare all'account di archiviazione e assegnare il ruolo Collaboratore dati BLOB di archiviazione all'applicazione AAD registrata dalla Access control (IAM) scheda (nella barra di spostamento sul lato sinistro dell'account di archiviazione nel portale azure).
Configurazione dell'ambiente per l'esempio
- Dalla pagina di panoramica dell'applicazione AAD, annotare i valori CLIENT ID e TENANT ID. Nella scheda "Certificati e segreti", crea un segreto e annotalo.
- Assicurarsi di avere AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET come variabili di ambiente per eseguire correttamente l'esempio(Può sfruttare process.env).

import { DefaultAzureCredential } from "@azure/identity";
import { DataLakeServiceClient } from "@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,
);

Per un esempio completo di questo metodo, vedere l'esempio di autenticazione di Azure AD .

[Nota - I passaggi precedenti sono solo per Node.js]

uso della stringa di connessione

In alternativa, è possibile creare un'istanza DataLakeServiceClient di utilizzando il fromConnectionString() metodo statico con la stringa di connessione completa come argomento. La stringa di connessione può essere ottenuta dal portale di Azure. [DISPONIBILE SOLO IN NODE.JS RUNTIME]

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const connectionString = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connectionString);

con `StorageSharedKeyCredential`

In alternativa, si crea un'istanza di a DataLakeServiceClient passando StorageSharedKeyCredential account-name e account-key come argomenti. È possibile ottenere il nome dell'account e la chiave dell'account dal portale di Azure. [DISPONIBILE SOLO IN NODE.JS RUNTIME]

import { StorageSharedKeyCredential, DataLakeServiceClient } from "@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,
);

con token di firma di accesso condiviso

Inoltre, è possibile creare un'istanza DataLakeServiceClient con una firma di accesso condiviso (SAS). È possibile ottenere il token di firma di accesso condiviso dal portale di Azure o generarne uno usando generateAccountSASQueryParameters().

import { DataLakeServiceClient } from "@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}`,
);

Creare un nuovo file system

Utilizzare DataLakeServiceClient.getFileSystemClient() per ottenere un'istanza client del file system, quindi creare una nuova risorsa del file system.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

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

// 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);

Elencare i file system

Usa DataLakeServiceClient.listFileSystems() la funzione per iterare i file system, con la nuova for-await-of sintassi:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

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

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

In alternativa senza utilizzare for-await-of:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

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

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
let { value, done } = await fileSystems.next();
while (!done) {
  console.log(`File system ${i++}: ${value.name}`);
  ({ value, done } = await fileSystems.next());
}

Inoltre, l'impaginazione è supportata anche per l'elenco tramite byPage():

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

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

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}`);
    }
  }
}

Creare ed eliminare una directory

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

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

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const directoryClient = fileSystemClient.getDirectoryClient("directory");
await directoryClient.create();
await directoryClient.delete();

Creare un file

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

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

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

const content = "Hello world!";
const fileName = `newfile${+new Date()}`;
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`);

Elencare i percorsi all'interno di un file system

Simile all'elenco dei file system.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

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

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

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

Scarica un file e convertilo in una stringa (Node.js)

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

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

const fileSystemName = "<file system name>";
const fileName = "<file name>";
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();
if (downloadResponse.readableStreamBody) {
  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: NodeJS.ReadableStream): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

Scaricare un file e convertirlo in una stringa (Browser)

import { DataLakeServiceClient } from "@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>";
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();
if (downloadResponse.contentAsBlob) {
  const blob = await downloadResponse.contentAsBlob;
  const downloaded = await blob.text();
  console.log(`Downloaded file content ${downloaded}`);
}

Troubleshooting

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la AZURE_LOG_LEVEL variabile di ambiente su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Passaggi successivi

Altri esempi di codice:

Contributing

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-17