Libreria client di Azure Storage File Data Lake per JavaScript - versione 12.23.0

Articolo
07/24/2024

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:

Introduttiva

Ambienti attualmente supportati

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

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

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 di archiviazione, ad esempio DataLakeServiceClient, DataLakeFileSystemCliento DataLakePathClient. Per altre informazioni sull'autenticazione, vedere esempi per la creazione del DataLakeServiceClient.

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. Per altre informazioni e esempi, vedere README per @azure/identity.

Compatibilità

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

Web Worker

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 di per l'uso di Azure SDK per JS in 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

Esistono differenze tra Node.js e il runtime dei browser. Quando si inizia a usare questa libreria, prestare attenzione alle API o alle classi contrassegnate con "ONLY AVAILABLE IN NODE.JS RUNTIME" o "ONLY AVAILABLE IN BROWSERS".

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

Funzionalità, 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

JavaScript Bundle

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

CORS

È necessario configurare regole cors (Cross-Origin Resource Sharing) per l'account di archiviazione se è necessario sviluppare per i browser. 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 usato tramite DataLakeServiceClient
Un file system nell'account di archiviazione usato tramite DataLakeFileSystemClient
Un percorso in un file system usato tramite DataLakeDirectoryClient o DataLakeFileClient

Azure DataLake Gen2	Blob
File system	Contenitore
Percorso (file o directory)	Blob

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

Esempi

Importare il pacchetto
Creare il client del servizio Data Lake
Creare un nuovo file system
Elencare i file system
Creare ed eliminare una directory
Creare un file
Elencare i percorsi all'interno di un file system
Scaricare un file e convertirlo 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:

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

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

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

Creare il client del servizio Data Lake

Il DataLakeServiceClient richiede un URL per il servizio Data Lake e una credenziale di accesso. Facoltativamente accetta anche alcune impostazioni nel parametro options.

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

modo consigliato per creare un'istanza di un DataLakeServiceClient

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

Installazione: riferimento - Autorizzare l'accesso ai BLOB (data lake) e alle code con Azure Active Directory da un'applicazione client - /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(in azure-portal) - /azure/active-directory/develop/quickstart-register-app
- Nella sezione API permissions selezionare Add a permission e scegliere Microsoft APIs.
- Selezionare Azure Storage e selezionare 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 controllo degli accessi in base al ruolo per BLOB (data lake) e code - /azure/storage/common/storage-auth-aad-rbac-portal.
- Nel portale di Azure passare all'account di archiviazione e assegnare ruolo Collaboratore ai dati dei BLOB di archiviazione all'applicazione AAD registrata dalla scheda Access control (IAM) (nella barra di spostamento sul lato sinistro dell'account di archiviazione nel portale di Azure).
Configurazione dell'ambiente per l'esempio
- Nella pagina di panoramica dell'applicazione AAD prendere nota dei CLIENT ID e TENANT ID. Nella scheda "Certificati & segreti" creare un segreto e notare che è inattivo.
- 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).

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

Per un esempio completo con questo metodo, vedere 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 di un DataLakeServiceClient usando il metodo statico fromConnectionString() 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]

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

con `StorageSharedKeyCredential`

In alternativa, si crea un'istanza di un DataLakeServiceClient con un StorageSharedKeyCredential passando il nome dell'account e la chiave dell'account come argomenti. È possibile ottenere il nome dell'account e la chiave dell'account dal portale di Azure. [DISPONIBILE SOLO IN 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
);

con token di firma di accesso condiviso

È anche possibile creare un'istanza di un DataLakeServiceClient con firme di accesso condiviso. È possibile ottenere il token di firma di accesso condiviso dal portale di Azure o generarne uno 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}`
);

Creare un nuovo file system

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

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

Elencare i file system

Usare DataLakeServiceClient.listFileSystems() funzione per scorrere i file system, con la nuova sintassi 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();

In alternativa, senza usare 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();

Inoltre, l'impaginazione è supportata anche per l'inserzione tramite 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();

Creare ed eliminare una directory

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

Creare un file

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

Elencare i percorsi all'interno di un file system

Simile all'elenco dei file system.

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

Scaricare un file e convertirlo in una stringa (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();

Scaricare un file e convertirlo in una stringa (Browser)

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

Risoluzione dei problemi

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

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

setLogLevel("info");

Passaggi successivi

Altri esempi di codice:

DataLake Storage Samples (JavaScript)
degli esempi di archiviazione DataLake (TypeScript)
test case di archiviazione datalake

Contribuire

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

impressioni

Condividi tramite

Libreria client di Azure Storage File Data Lake per JavaScript - versione 12.23.0

Introduttiva

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto

Autenticare il client

Azure Active Directory

Compatibilità

Web Worker

Differenze tra Node.js e browser

Funzionalità, interfacce, classi o funzioni disponibili solo in Node.js

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

JavaScript Bundle

CORS

Concetti chiave

Esempi

Importare il pacchetto

Creare il client del servizio Data Lake

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

uso della stringa di connessione

con `StorageSharedKeyCredential`

con token di firma di accesso condiviso

Creare un nuovo file system

Elencare i file system

Creare ed eliminare una directory

Creare un file

Elencare i percorsi all'interno di un file system

Scaricare un file e convertirlo in una stringa (Node.js)

Scaricare un file e convertirlo in una stringa (Browser)

Risoluzione dei problemi

Passaggi successivi

Contribuire

Risorse aggiuntive

Condividi tramite

Libreria client di Azure Storage File Data Lake per JavaScript - versione 12.23.0

Introduttiva

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto

Autenticare il client

Azure Active Directory

Compatibilità

Web Worker

Differenze tra Node.js e browser

Funzionalità, interfacce, classi o funzioni disponibili solo in Node.js

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

JavaScript Bundle

CORS

Concetti chiave

Esempi

Importare il pacchetto

Creare il client del servizio Data Lake

con DefaultAzureCredential dal pacchetto di @azure/identity

uso della stringa di connessione

con StorageSharedKeyCredential

con token di firma di accesso condiviso

Creare un nuovo file system

Elencare i file system

Creare ed eliminare una directory

Creare un file

Elencare i percorsi all'interno di un file system

Scaricare un file e convertirlo in una stringa (Node.js)

Scaricare un file e convertirlo in una stringa (Browser)

Risoluzione dei problemi

Passaggi successivi

Contribuire

Risorse aggiuntive

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

con `StorageSharedKeyCredential`