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

Azure Data Lake Storage (ADLS) umfasst alle erforderlichen Funktionen, um Entwicklern, Datenwissenschaftlern und Analysten das Speichern von Daten beliebiger Größe, Form und Geschwindigkeit zu erleichtern und alle Arten von Verarbeitung und Analyse auf allen Plattformen und Sprachen zu erledigen. Dadurch werden die Komplexitäten beim Aufnehmen und Speichern aller Daten entfernt, sodass sie schneller mit Batch-, Streaming- und interaktiven Analysen in Betrieb genommen werden können.

Dieses Projekt stellt eine Clientbibliothek in JavaScript bereit, die das Verwenden des Microsoft Azure Storage Data Lake-Diensts erleichtert.

Verwenden Sie die Clientbibliotheken in diesem Paket, um:

• Erstellen/Auflisten/Löschen von Dateisystemen
• Erstellen/Lesen/Liste/Aktualisieren/Löschen von Pfaden, Verzeichnissen und Dateien

Zugriffstastenlinks:

• Quellcode
• Package (npm)
• API-Referenzdokumentation
• Produktdokumentation
• Beispiele
• REST-APIs von Azure Storage Data Lake

Erste Schritte

Derzeit unterstützte Umgebungen

• LTS-Versionen von Node.js
• Neueste Versionen von Safari, Chrome, Edge und Firefox.

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

• Ein Azure-Abonnement
• Ein Speicherkonto

Installieren des Pakets

Die bevorzugte Methode zum Installieren der Azure Storage Data Lake-Clientbibliothek für JavaScript ist die Verwendung des npm-Paket-Managers. 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 beispielsweise eine Instanz eines Speicherclients erstellen – DataLakeServiceClient, DataLakeFileSystemClientoder DataLakePathClient. Weitere Informationen zur Authentifizierung finden Sie in Beispielen zum Erstellen des DataLakeServiceClient.

• Azure Active Directory-
• freigegebenen Schlüssel
• Freigegebene Zugriffssignaturen

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 verwenden kann, um dies zu tun. Weitere Details und Beispiele für die ersten Schritte finden Sie in der README für @azure/identity.

Kompatibilität

Diese Bibliothek ist mit Node.js und Browsern kompatibel und wird 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 Workers

Diese Bibliothek hängt von den folgenden DOM-APIs ab, die externe Polyfills benötigen, die bei Verwendung in Web-Workern geladen werden:

• document
• DOMParser
• Node
• XMLSerializer

Unterschiede zwischen Node.js und Browsern

Es gibt Unterschiede zwischen Node.js und Browserlaufzeit. Achten Sie bei den ersten Schritten mit dieser Bibliothek auf APIs oder Klassen, die mit "NUR IN NODE.JS RUNTIME VERFÜGBAR" gekennzeichnet sind, oder "NUR IN BROWSERN VERFÜGBAR".

• Wenn eine Datei komprimierte Daten im gzip- oder deflate-Format enthält und deren Inhaltscodierung entsprechend festgelegt ist, unterscheidet sich das Downloadverhalten zwischen Node.js und Browsern. In Node.js Speicherclients laden die Datei im komprimierten Format herunter, während die Daten in Browsern im komprimierten Format heruntergeladen werden.

Features, Schnittstellen, Klassen oder Funktionen nur in Node.js

• Gemeinsame Schlüsselautorisierung basierend auf Kontoname und Kontoschlüssel
  • StorageSharedKeyCredential
• Generierung von Shared Access Signature(SAS)
  • 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

• N/A

JavaScript-Bündel

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

CORS

Sie müssen Cross-Origin Resource Sharing (CORS) Regeln für Ihr Speicherkonto einrichten, wenn Sie für Browser entwickeln müssen. Wechseln Sie zu Azure-Portal und Azure Storage-Explorer, suchen Sie Ihr Speicherkonto, erstellen Sie neue CORS-Regeln für blob/queue/file/table service(s).

Sie können z. B. die folgenden CORS-Einstellungen für das Debuggen erstellen. Passen Sie die Einstellungen jedoch entsprechend Ihren Anforderungen in der Produktionsumgebung sorgfältig an.

• Zulässige Ursprünge: *
• Zulässige Verben: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Zulässige Kopfzeilen: *
• Verfügbar gemachte Kopfzeilen: *
• Höchstalter (Sekunden): 86400

Hinweis: Data Lake gibt derzeit CORS-Einstellungen für den BLOB-Dienst weiter.

Schlüsselkonzepte

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

• Bereitstellen mehrerer Petabytes an Informationen bei gleichzeitiger Beibehaltung von Hunderten von Gigabit-Durchsatz
• Ermöglichen Sie die einfache Verwaltung massiver Datenmengen.

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

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

Ein grundlegender Bestandteil von Data Lake Storage Gen2 ist das Hinzufügen eines hierarchischen Namespaces zu Blob Storage. Der hierarchische Namespace organisiert Objekte/Dateien in einer Hierarchie von Verzeichnissen für einen effizienten Datenzugriff.

In der Vergangenheit mussten cloudbasierte Analysen in Bereichen der Leistung, Verwaltung und Sicherheit kompromittiert werden. Data Lake Storage Gen2 befasst sich mit den folgenden Aspekten:

• Die Leistung ist optimiert, da Sie daten nicht als Voraussetzung für die Analyse kopieren oder transformieren müssen. Der hierarchische Namespace verbessert die Leistung von Verzeichnisverwaltungsvorgängen erheblich, wodurch die Gesamtleistung des Auftrags verbessert wird.
• Die Verwaltung ist einfacher, da Sie Dateien über Verzeichnisse und Unterverzeichnisse organisieren und bearbeiten können.
• Sicherheit ist durchsetzbar, da Sie POSIX-Berechtigungen für Verzeichnisse oder einzelne Dateien definieren können.
• Die Kosteneffizienz wird ermöglicht, da Data Lake Storage Gen2 auf dem kostengünstigen Azure Blob Storage basiert. Die zusätzlichen Features senken die Gesamtbetriebskosten für die Ausführung von Big Data Analytics in Azure weiter.

Data Lake Storage bietet drei Arten von Ressourcen:

• Das Speicherkonto über DataLakeServiceClient
• Ein Dateisystem im über DataLakeFileSystemClient verwendeten Speicherkonto
• Ein Pfad in einem Dateisystem, das über DataLakeDirectoryClient oder DataLakeFileClient verwendet wird

Azure DataLake Gen2	Blob
Dateisystem	Container
Pfad (Datei oder Verzeichnis)	Blob

Hinweis: Diese Clientbibliothek unterstützt nur Speicherkonten mit aktivierten hierarchischen Namespaces (HNS).

Beispiele

• Importieren des Pakets
• Erstellen des Data Lake-Dienstclients
• Erstellen eines neuen Dateisystems
• Auflisten der Dateisysteme
• Erstellen und Löschen eines Verzeichnisses
• Erstellen einer Datei
• Listenpfade innerhalb eines Dateisystems
• Herunterladen einer Datei und Konvertieren in eine Zeichenfolge (Node.js)
• Herunterladen einer Datei und Konvertieren in eine Zeichenfolge (Browser)

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 nur die benötigten Typen selektiv importieren:

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

Erstellen des Data Lake-Dienstclients

Für die DataLakeServiceClient ist eine URL zum Data Lake-Dienst und eine Zugriffsanmeldeinformationen erforderlich. Sie akzeptiert optional auch einige Einstellungen im options-Parameter.

mit DefaultAzureCredential aus @azure/identity Paket

Empfohlene Methode zum Instanziieren eines DataLakeServiceClient

Bemerken. Azure Data Lake verwendet derzeit blobbezogene Rollen wie "Storage Blob Data Owner" während der folgenden AAD OAuth-Authentifizierung wieder.

Setup: Referenz – Autorisieren des Zugriffs auf Blobs (Data Lake) und Warteschlangen mit Azure Active Directory aus einer 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 im Azure Active Directory(im Azure-Portal) – /azure/active-directory/develop/quickstart-register-app
  • Wählen Sie im Abschnitt API permissionsAdd a permission aus, und wählen Sie Microsoft APIsaus.
  • Wählen Sie Azure Storage aus, und aktivieren Sie 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.
  • Wechseln Sie im Azure-Portal zu Ihrem Speicherkonto, und weisen Sie Rolle "Storage Blob Data Contributor" der registrierten AAD-Anwendung auf der Registerkarte Access control (IAM) zu (in der linken Navigationsleiste Ihres Speicherkontos im Azure-Portal).

• Umgebungssetup 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 & Geheime Schlüssel" einen geheimen Schlüssel, und notieren Sie sich dies unten.
  • Stellen Sie sicher, dass Sie AZURE_TENANT_ID, AZURE_CLIENT_ID, als Umgebungsvariablen AZURE_CLIENT_SECRET haben, um das Beispiel erfolgreich auszuführen(Kann process.env nutzen).

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 Auth-Beispiel.

[Hinweis - Oben aufgeführte Schritte sind nur für Node.js]

verwenden der Verbindungszeichenfolge

Alternativ können Sie eine DataLakeServiceClient mithilfe der fromConnectionString() statischen Methode mit der vollständigen Verbindungszeichenfolge als Argument instanziieren. (Die Verbindungszeichenfolge kann aus dem 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 instanziieren Sie eine DataLakeServiceClient mit einem StorageSharedKeyCredential, indem Sie Kontoname und Kontoschlüssel als Argumente übergeben. (Der Kontoname und der 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 freigegebenen Zugriffssignatur (SAS) instanziieren. Sie können das SAS-Token aus dem Azure-Portal abrufen oder mithilfe von 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}`
);

Erstellen eines neuen Dateisystems

Verwenden Sie DataLakeServiceClient.getFileSystemClient(), um eine Dateisystemclientinstanz abzurufen und 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() Funktion zum Durchlaufen der Dateisysteme mit der neuen for-await-of syntax:

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

Erstellen 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 einer Datei

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;
  const paths = fileSystemClient.listPaths();
  for await (const path of paths) {
    console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
  }
}

main();

Laden Sie eine Datei herunter, und konvertieren Sie sie 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) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Fehlerbehebung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Nächste Schritte

Weitere Codebeispiele:

• DataLake Storage Samples (JavaScript)
• DataLake Storage Samples (TypeScript)
• DataLake Storage Test Cases

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.