Share via

Azure Storage File Data Lake-Clientbibliothek für JavaScript – Version 12.17.0

  • Artikel

Azure Data Lake Storage (ADLS) umfasst alle Funktionen, die erforderlich sind, um Entwicklern, Data Scientists und Analysten das Speichern von Daten beliebiger Größe, Form und Geschwindigkeit zu erleichtern und alle Arten von Verarbeitungen und Analysen plattform- und sprachübergreifend durchzuführen. Mit Data Lake gehört die Komplexität beim Erfassen und Speichern von Daten der Vergangenheit an, und mit Batch-, Streaming- und interaktiven Analysen können Sie Ihre Analysen jetzt noch schneller ausführen.

Dieses Projekt stellt eine Clientbibliothek in JavaScript bereit, die die Nutzung Microsoft Azure Storage Data Lake-Diensts vereinfacht.

Verwenden Sie die Clientbibliotheken in diesem Paket für Folgendes:

  • Create/Auflisten/Löschen von Dateisystemen
  • Create/Read/List/Update/Delete Pfade, Verzeichnisse und Dateien

Schlüssellinks:

Erste Schritte

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Installieren des Pakets

Die bevorzugte Methode zum Installieren der Azure Storage Data Lake-Clientbibliothek für JavaScript besteht darin, den npm-Paket-Manager zu verwenden. Geben Sie Folgendes in ein Terminalfenster ein:

npm install @azure/storage-file-datalake

Authentifizieren des Clients

Azure Storage unterstützt mehrere Möglichkeiten zur Authentifizierung. Um mit dem Azure Data Lake Storage-Dienst zu interagieren, müssen Sie eine instance eines Speicherclients erstellen, DataLakeServiceClientz. B. , DataLakeFileSystemClientoderDataLakePathClient. Weitere Informationen zur Authentifizierung finden Sie unter Beispiele zum Erstellen von DataLakeServiceClient .

Azure Active Directory

Der Azure Data Lake Storage-Dienst unterstützt die Verwendung von Azure Active Directory zum Authentifizieren von Anforderungen an seine APIs. Das @azure/identity Paket bietet eine Vielzahl von Anmeldeinformationstypen, die Ihre Anwendung dazu verwenden kann. Weitere Informationen und Beispiele finden @azure/identity Sie in der Infodatei.

Kompatibilität

Diese Bibliothek ist mit Node.js und Browsern kompatibel und mit LTS-Node.js Versionen (>=8.16.0) und den neuesten Versionen von Chrome, Firefox und Edge überprüft.

Web Worker

Diese Bibliothek erfordert, dass bestimmte DOM-Objekte global verfügbar sind, wenn sie im Browser verwendet werden, die Web worker standardmäßig nicht verfügbar machen. Sie müssen diese polyausfüllen, damit diese Bibliothek in Web workern funktioniert.

Weitere Informationen finden Sie in unserer Dokumentation zur Verwendung des Azure SDK für JS in Web Workern.

Diese Bibliothek ist von folgenden DOM-APIs abhängig, die externe Polyfills laden müssen, wenn sie in Web Workern verwendet werden:

Unterschiede zwischen Node.js und Browsern

Es gibt Unterschiede zwischen Node.js- und Browserlaufzeit. Achten Sie beim Einstieg mit dieser Bibliothek auf APIs oder Klassen, die mit "ONLY AVAILABLE IN NODE.JS RUNTIME" oder "ONLY AVAILABLE IN BROWSERS" gekennzeichnet sind.

  • Wenn eine Datei komprimierte Daten in oder deflate im gzip Format enthält und die Inhaltscodierung entsprechend festgelegt ist, unterscheidet sich das Downloadverhalten zwischen Node.js und Browsern. In Node.js Speicherclients die Datei in ihrem komprimierten Format herunterladen, während in Browsern die Daten in dekomprimiertem Format heruntergeladen werden.
Features, Schnittstellen, Klassen oder Funktionen, die nur in Node.js
  • Freigabeschlüsselautorisierung basierend auf Kontoname und Kontoschlüssel
    • StorageSharedKeyCredential
  • Sas-Generierung (Shared Access Signature)
    • generateAccountSASQueryParameters()
    • generateDataLakeSASQueryParameters()
  • Paralleles Hochladen und Herunterladen. Beachten Sie, dass DataLakeFileClient.upload() sowohl in Node.js als auch in Browsern verfügbar ist.
    • DataLakeFileClient.uploadFile()
    • DataLakeFileClient.uploadStream()
    • DataLakeFileClient.readToBuffer()
    • DataLakeFileClient.readToFile()
Features, Schnittstellen, Klassen oder Funktionen, die nur in Browsern verfügbar sind
  • –

JavaScript-Bundle

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zunächst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

CORS

Sie müssen CORS-Regeln (Cross-Origin Resource Sharing) für Ihr Speicherkonto einrichten, wenn Sie für Browser entwickeln müssen. Wechseln Sie zu Azure-Portal und Azure Storage-Explorer, suchen Sie Nach Ihrem Speicherkonto, und erstellen Sie neue CORS-Regeln für Blob-,Warteschlangen-,Datei-/Tabellendienste.

Sie können beispielsweise die folgenden CORS-Einstellungen für das Debuggen erstellen. Aber bitte passen Sie die Einstellungen sorgfältig an Ihre Anforderungen in der Produktionsumgebung an.

  • Zulässige Ursprünge: *
  • Zulässige Verben: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Zulässige Header: *
  • Verfügbar gemachte Header: *
  • Maximales Alter (Sekunden): 86400

Hinweis: Data Lake verwendet derzeit CORS-Einstellungen für den Blobdienst.

Wichtige Begriffe

Azure Data Lake Storage Gen2 wurde für Folgendes konzipiert:

  • Bereitstellen von Mehreren Petabytes an Informationen bei gleichzeitiger Beibehaltung von Hunderten von Gigabit-Durchsatz
  • Einfache Verwaltung riesiger Datenmengen

Zu den wichtigsten Features von DataLake Storage Gen2 gehören:

  • Hadoop-kompatibler Zugriff
  • Eine Reihe von POSIX-Berechtigungen
  • Kosteneffektiv in Bezug auf kostengünstige Speicherkapazität und Transaktionen
  • Optimierter Treiber für Big Data-Analysen

Ein wesentlicher Bestandteil von Data Lake Storage Gen2 ist das Hinzufügen eines hierarchischen Namespace zum Blobspeicher. Der hierarchische Namespace organisiert Objekte/Dateien in einer Hierarchie von Verzeichnissen für den effizienten Datenzugriff.

In der Vergangenheit mussten bei cloudbasierten Analysen Kompromisse in puncto Leistung, Verwaltung und Sicherheit eingegangen werden. Data Lake Storage Gen2 geht jeden dieser Aspekte auf folgende Weise an:

  • Die Leistung ist optimiert, da Sie keine Daten als Voraussetzung für die Analyse kopieren oder transformieren müssen. Der hierarchische Namespace verbessert die Leistung von Verzeichnisverwaltungsvorgängen erheblich, wodurch die gesamte Auftragsverarbeitungsleistung gesteigert wird.
  • Die Verwaltung ist einfacher, weil Sie Dateien mithilfe von Verzeichnissen und Unterverzeichnissen organisieren und bearbeiten können.
  • Die Sicherheit ist durchsetzbar, da Sie POSIX-Berechtigungen für Verzeichnisse oder einzelne Dateien definieren können.
  • Kosteneffizienz wird ermöglicht, da Data Lake Storage Gen2 auf kostengünstigem Azure Blob Storage aufsetzt. Durch diese zusätzlichen Features werden die Gesamtbetriebskosten für Big Data-Analysen in Azure weiter gesenkt.

Data Lake Storage bietet drei Arten von Ressourcen:

  • Das verwendete Speicherkonto über DataLakeServiceClient
  • Ein Dateisystem im Speicherkonto, das über DataLakeFileSystemClient
  • Ein Pfad in einem Dateisystem, das über DataLakeDirectoryClient oder verwendet wird DataLakeFileClient
Azure DataLake Gen2 Blob
Dateisystem Container
Pfad (Datei oder Verzeichnis) Blob

Hinweis: Diese Clientbibliothek unterstützt nur Speicherkonten mit aktiviertem hierarchischem Namespace (HNS).

Beispiele

Importieren des Pakets

Um die Clients zu verwenden, importieren Sie das Paket in Ihre Datei:

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

Alternativ können Sie selektiv nur die Typen importieren, die Sie benötigen:

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

Create des Data Lake-Dienstclients

Die DataLakeServiceClient erfordert eine URL zum Data Lake-Dienst und eine Zugriffsanmeldeinformation. Optional werden auch einige Einstellungen im options Parameter akzeptiert.

mit DefaultAzureCredential from-Paket @azure/identity

Empfohlene Methode zum Instanziieren eines DataLakeServiceClient

Hinweis. Azure Data Lake verwendet derzeit blobbezogene Rollen wie "Besitzer von Speicherblobdaten" während der AAD OAuth-Authentifizierung wieder.

Setup: Referenz: Autorisieren des Zugriffs auf Blobs (Data Lake) und Warteschlangen mit Azure Active Directory über eine Clientanwendung – /azure/storage/common/storage-auth-aad-app

  • Registrieren Sie eine neue AAD-Anwendung, und erteilen Sie berechtigungen für den Zugriff auf Azure Storage im Namen des angemeldeten Benutzers.

    • Registrieren einer neuen Anwendung in Azure Active Directory (im Azure-Portal): /azure/active-directory/develop/quickstart-register-app
    • Wählen Sie Add a permission im Abschnitt ausAPI permissions, und wählen Sie ausMicrosoft APIs.
    • Aktivieren Sie Azure Storage das Kontrollkästchen neben , user_impersonation und klicken Sie dann auf Add permissions. Dadurch kann die Anwendung im Namen des angemeldeten Benutzers auf Azure Storage zugreifen.

  • Gewähren des Zugriffs auf Azure Data Lake-Daten mit RBAC im Azure-Portal

    • RBAC-Rollen für Blobs (Data Lake) und Warteschlangen: /azure/storage/common/storage-auth-aad-rbac-portal.
    • Navigieren Sie im Azure-Portal zu Ihrem Speicherkonto, und weisen Sie der registrierten AAD-Anwendung die Rolle Mitwirkender an Storage-Blobdaten über Access control (IAM) die Registerkarte zu (in der linken Navigationsleiste Ihres Speicherkontos im Azure-Portal).

  • Umgebungseinrichtung für das Beispiel

    • Notieren Sie sich auf der Übersichtsseite Ihrer AAD-Anwendung die CLIENT ID - und TENANT ID- . Erstellen Sie auf der Registerkarte "Zertifikate & Geheimnisse" ein Geheimnis, und notieren Sie sich das.
    • Stellen Sie sicher, dass Sie über AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET als Umgebungsvariablen verfügen, um das Beispiel erfolgreich auszuführen (Can leverage 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
);

Ein vollständiges Beispiel mit dieser Methode finden Sie im Azure AD-Authentifizierungsbeispiel .

[Hinweis: Die obigen Schritte sind nur für Node.js]

Verwenden von Verbindungszeichenfolge

Alternativ können Sie eine DataLakeServiceClient instanziieren, indem Sie die fromConnectionString() statische Methode mit dem vollständigen Verbindungszeichenfolge als Argument verwenden. (Die Verbindungszeichenfolge kann über das Azure-Portal abgerufen werden.) [NUR IN NODE.JS RUNTIME VERFÜGBAR]

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

Mit StorageSharedKeyCredential

Alternativ können Sie ein DataLakeServiceClient mit einem StorageSharedKeyCredential instanziieren, indem Sie den Kontonamen und den Kontoschlüssel als Argumente übergeben. (Kontoname und Kontoschlüssel können über das Azure-Portal abgerufen werden.) [NUR IN NODE.JS RUNTIME VERFÜGBAR]

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

mit SAS-Token

Außerdem können Sie eine DataLakeServiceClient mit einer SAS (Shared Access Signatures) instanziieren. Sie können das SAS-Token aus dem Azure-Portal abrufen oder mit generateAccountSASQueryParameters()generieren.

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

Create eines neuen Dateisystems

Verwenden Sie DataLakeServiceClient.getFileSystemClient() , um einen Dateisystemclient abzurufen instance dann eine neue Dateisystemressource zu erstellen.

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

Auflisten der Dateisysteme

Verwenden Sie DataLakeServiceClient.listFileSystems() die Funktion, um die Dateisysteme mit der neuen for-await-of Syntax zu durchlaufen:

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

Alternativ ohne :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();

Darüber hinaus wird die Paginierung auch für die Auflistung über byPage()unterstützt:

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

Create und Löschen eines Verzeichnisses

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

Erstellen von Dateien

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

Auflisten von Pfaden innerhalb eines Dateisystems

Ähnlich wie beim Auflisten von Dateisystemen.

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

Herunterladen einer Datei und Konvertieren in eine Zeichenfolge (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();

Herunterladen einer Datei und Konvertieren in eine Zeichenfolge (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();

Problembehandlung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Nächste Schritte

Weitere Codebeispiele:

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe