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

Azure Files bietet vollständig verwaltete Dateifreigaben in der Cloud, die über das Branchenstandardprotokoll Server Message Block (SMB) zugänglich sind. Azure-Dateifreigaben können gleichzeitig über Cloud- oder lokale Bereitstellungen von Windows, Linux und macOS bereitgestellt werden. Darüber hinaus können Azure-Dateifreigaben auf Windows-Servern mit Azure File Sync zwischengespeichert werden, um schnell darauf zuzugreifen, wo die Daten verwendet werden.

Dieses Projekt stellt eine Clientbibliothek in JavaScript bereit, die die Nutzung des Microsoft Azure File Storage-Diensts erleichtert.

Verwenden Sie die Clientbibliotheken in diesem Paket, um:

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

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

Wichtige Links:

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

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 File Storage-Clientbibliothek für JavaScript ist die Verwendung des npm-Paket-Managers. 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 File Share-Dienst zu interagieren, müssen Sie beispielsweise eine Instanz eines Speicherclients erstellen – ShareServiceClient, ShareClientoder ShareDirectoryClient. Weitere Informationen zur Authentifizierung finden Sie in Beispielen zum Erstellen des ShareServiceClient.

• freigegebenen Schlüssel
• Freigegebene Zugriffssignaturen

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.

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

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

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

Schlüsselkonzepte

Die folgenden Komponenten und ihre entsprechenden Clientbibliotheken bilden den Azure Storage File Share-Dienst:

• Das Speicherkonto sich selbst, dargestellt durch eine ShareServiceClient
• Eine Dateifreigabe innerhalb des Speicherkontos, dargestellt durch eine 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 eine ShareFileClient

Beispiele

• Importieren des Pakets
• Erstellen des Freigabedienstclients
• Listenfreigaben für das Konto
• Erstellen einer neuen Freigabe und eines Verzeichnis-
• Erstellen einer Azure-Datei dann
• 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 nur die benötigten Typen selektiv importieren:

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

Erstellen des Freigabedienstclients

Für die ShareServiceClient ist eine URL zum Dateifreigabedienst und eine Zugriffsanmeldeinformation erforderlich. Sie akzeptiert optional auch einige Einstellungen im options-Parameter.

verwenden der Verbindungszeichenfolge

Alternativ können Sie eine ShareServiceClient mithilfe der fromConnectionString() statischen Methode mit der vollständigen Verbindungszeichenfolge als Argument instanziieren. (Die Verbindungszeichenfolge kann aus dem Azure-Portal abgerufen werden.)

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

mit StorageSharedKeyCredential

Übergeben Sie eine StorageSharedKeyCredential mit Ihrem Kontonamen und 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 eine ShareServiceClient mit einer freigegebenen Zugriffssignatur (SAS) instanziieren. Sie können das SAS-Token aus dem Azure-Portal abrufen oder mithilfe von 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 Durchlaufen von Dateien und Verzeichnissen 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.

Laden Sie eine Datei herunter, und konvertieren Sie sie 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.

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

• Dateifreigabe-Speicherbeispiele (JavaScript)
• File Share Storage Samples (TypeScript)
• Testfälle für die Dateifreigabe

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.

Weitere Informationen zum Einrichten der Testumgebung für Speicherbibliotheken finden Sie auch in speicherspezifischen Leitfaden.