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

Azure Files bietet vollständig verwaltete Dateifreigaben in der Cloud, auf die über das Branchenstandardprotokoll Server Message Block (SMB) zugegriffen werden kann. Azure-Dateifreigaben können gleichzeitig durch die Cloud oder lokale Bereitstellungen von Windows, Linux und macOS eingebunden werden. Außerdem können Azure-Dateifreigaben auf Windows-Servern mit der Azure-Dateisynchronisierung zwischengespeichert werden, um einen schnellen Zugriff in der Nähe des Datennutzungsorts zu gewährleisten.

Dieses Projekt stellt eine Clientbibliothek in JavaScript bereit, die die Nutzung des Microsoft Azure-Dateispeicherdiensts vereinfacht.

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

• Abrufen/Festlegen von Dateidiensteigenschaften
• Erstellen/Auflisten/Löschen von Dateifreigaben
• Erstellen/Auflisten/Löschen von Dateiverzeichnissen
• Erstellen/Lesen/Listen/Aktualisieren/Löschen von Dateien

Hinweis: Dieses Paket wurde zuvor unter dem Namen @azure/storage-fileveröffentlicht. Es wurde umbenannt, um @azure/storage-file-share besser auf das bevorstehende neue Paket für Azure Storage Files DataLake auszurichten und einen konsistenten Satz von APIs für die Arbeit mit Dateien in Azure bereitzustellen.

Wichtige Links:

• Quellcode
• Paket (npm)
• API-Referenzdokumentation
• Produktdokumentation
• Beispiele
• REST-APIs für Azure Storage-Dateien

Erste Schritte

Die derzeitig unterstützten Umgebungen

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

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

• Ein Azure-Abonnement
• Ein Speicherkonto

Installieren des Pakets

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

npm install @azure/storage-file-share

Authentifizieren des Clients

Azure Storage unterstützt mehrere Möglichkeiten zur Authentifizierung. Um mit dem Azure Storage-Dateifreigabedienst interagieren zu können, müssen Sie eine instance eines Speicherclients erstellen, ShareServiceClientz. B. , ShareClientoderShareDirectoryClient. Weitere Informationen zur Authentifizierung finden Sie unter Beispiele zum Erstellen von ShareServiceClient .

• Gemeinsam verwendeter Schlüssel
• Shared Access Signatures

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:

• document
• DOMParser
• Node
• XMLSerializer

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.

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

• Freigabeschlüsselautorisierung basierend auf Kontoname und Kontoschlüssel
  • StorageSharedKeyCredential
• Sas-Generierung (Shared Access Signature)
  • generateAccountSASQueryParameters()
  • generateFileSASQueryParameters()
• Paralleles Hochladen und Herunterladen. Beachten Sie, dass ShareFileClient.uploadData() sowohl in Node.js als auch in Browsern verfügbar ist.
  • ShareFileClient.uploadFile()
  • ShareFileClient.uploadStream()
  • ShareFileClient.downloadToBuffer()
  • ShareFileClient.downloadToFile()

Folgende Features, Schnittstellen, Klassen oder Funktionen sind nur in Browsern verfügbar

–

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

Wichtige Begriffe

Die folgenden Komponenten und die entsprechenden Clientbibliotheken bilden den Azure Storage-Dateifreigabedienst:

• Das Speicherkonto selbst, dargestellt durch ein ShareServiceClient
• Eine Dateifreigabe innerhalb des Speicherkontos, dargestellt durch einen ShareClient
• Eine optionale Hierarchie von Verzeichnissen innerhalb der Dateifreigabe, dargestellt durch ShareDirectoryClient Instanzen
• Eine Datei innerhalb der Dateifreigabe, die bis zu 1 TiB groß sein kann, dargestellt durch einen ShareFileClient

Beispiele

• Importieren des Pakets
• Erstellen des Freigabedienstclients
• Auflisten von Freigaben im Konto
• Erstellen einer neuen Freigabe und eines Verzeichnisses
• Erstellen sie eine Azure-Datei, und laden Sie sie dann hoch.
• Auflisten von Dateien und Verzeichnissen unter einem Verzeichnis
• 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 AzureStorageFileShare = require("@azure/storage-file-share");

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

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

Erstellen des Freigabedienstclients

Die ShareServiceClient erfordert eine URL für den Dateifreigabedienst und Zugriffsanmeldeinformationen. Optional werden auch einige Einstellungen im options Parameter akzeptiert.

Verwenden von Verbindungszeichenfolge

Alternativ können Sie eine ShareServiceClient instanziieren, indem Sie die fromConnectionString() statische Methode mit dem vollständigen Verbindungszeichenfolge als Argument verwenden. (Die Verbindungszeichenfolge können über das Azure-Portal abgerufen werden.)

const { ShareServiceClient } = require("@azure/storage-file-share");

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

Mit StorageSharedKeyCredential

Übergeben Sie einen StorageSharedKeyCredential mit Ihrem Kontonamen und Ihrem Kontoschlüssel. (Der Kontoname und der Kontoschlüssel können über das Azure-Portal abgerufen werden.)

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

// 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 credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  // When using AnonymousCredential, following url should include a valid SAS
  `https://${account}.file.core.windows.net`,
  credential
);

mit SAS-Token

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

const { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new ShareServiceClient(
  `https://${account}.file.core.windows.net${sas}`
);

Auflisten von Freigaben im Konto

Verwenden Sie ShareServiceClient.listShares() für Iteratorfreigaben in diesem Konto mit der neuen for-await-of Syntax:

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  let shareIter = serviceClient.listShares();
  let i = 1;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

Alternativ ohne for-await-of:

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  let shareIter = serviceClient.listShares();
  let i = 1;
  let shareItem = await shareIter.next();
  while (!shareItem.done) {
    console.log(`Share ${i++}: ${shareItem.value.name}`);
    shareItem = await shareIter.next();
  }
}

main();

Erstellen einer neuen Freigabe und eines Verzeichnisses

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareName = `newshare${new Date().getTime()}`;
  const shareClient = serviceClient.getShareClient(shareName);
  await shareClient.create();
  console.log(`Create share ${shareName} successfully`);

  const directoryName = `newdirectory${new Date().getTime()}`;
  const directoryClient = shareClient.getDirectoryClient(directoryName);
  await directoryClient.create();
  console.log(`Create directory ${directoryName} successfully`);
}

main();

Erstellen sie eine Azure-Datei, und laden Sie sie dann hoch.

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const content = "Hello World!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = directoryClient.getFileClient(fileName);
  await fileClient.create(content.length);
  console.log(`Create file ${fileName} successfully`);

  // Upload file range
  await fileClient.uploadRange(content, 0, content.length);
  console.log(`Upload file range "${content}" to ${fileName} successfully`);
}

main();

Auflisten von Dateien und Verzeichnissen unter einem Verzeichnis

Verwenden Sie DirectoryClient.listFilesAndDirectories() zum Iterator für Dateien und Verzeichnisse mit der neuen for-await-of Syntax. Die kind -Eigenschaft kann verwendet werden, um zu ermitteln, ob ein Iterm ein Verzeichnis oder eine Datei ist.

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  let dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  for await (const item of dirIter) {
    if (item.kind === "directory") {
      console.log(`${i} - directory\t: ${item.name}`);
    } else {
      console.log(`${i} - file\t: ${item.name}`);
    }
    i++;
  }
}

main();

Alternativ ohne :for-await-of

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  let dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  let item = await dirIter.next();
  while (!item.done) {
    if (item.value.kind === "directory") {
      console.log(`${i} - directory\t: ${item.value.name}`);
    } else {
      console.log(`${i} - file\t: ${item.value.name}`);
    }
    item = await dirIter.next();
  }
}

main();

Ein vollständiges Beispiel zum Durchlaufen finden Sie unter samples/v12/typescript/src/listFilesAndDirectories.ts.

Herunterladen einer Datei und Konvertieren in eine Zeichenfolge (Node.js)

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const fileName = "<file name>";

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

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadFileResponse.readableStreamBody
  const downloadFileResponse = await fileClient.download();
  console.log(
    `Downloaded file content: ${(
      await streamToBuffer(downloadFileResponse.readableStreamBody)
    ).toString()}`
  );
}

main();

Herunterladen einer Datei und Konvertieren in eine Zeichenfolge (Browser)

Weitere Informationen zur Verwendung dieser Bibliothek im Browser finden Sie im Abschnitt JavaScript Bundle .

const { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const shareName = "<share name>";
const fileName = "<file name>";

const serviceClient = new ShareServiceClient(`https://${account}.file.core.windows.net${sas}`);

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadFileResponse.blobBody
  const downloadFileResponse = await fileClient.download(0);
  console.log(
    `Downloaded file content: ${await blobToString(await downloadFileResponse.blobBody)}`
  );
}

// [Browser 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();

Ein vollständiges Beispiel für einfache ShareServiceClient Szenarien finden Sie unter samples/v12/typescript/src/shareSerivceClient.ts.

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

• Dateifreigabespeicherbeispiele (JavaScript)
• Dateifreigabespeicherbeispiele (TypeScript)
• Testfälle für Dateifreigabespeicher

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.

Weitere Informationen zum Einrichten der Testumgebung für Speicherbibliotheken finden Sie auch im Speicherspezifischen Leitfaden .