Klientská knihovna sdílených složek Azure Storage pro JavaScript

Článek
05/15/2024

Služba Azure Files nabízí plně spravované sdílené složky v cloudu, které jsou přístupné přes standardní protokol Server Message Block (SMB). Sdílené složky Azure je možné připojit současně do cloudových i místních nasazení systémů Windows, Linux a macOS. Sdílené složky Azure je navíc možné ukládat do mezipaměti ve Windows Serveru pomocí Synchronizace souborů Azure, aby byly rychle přístupné poblíž místa, kde se data používají.

Tento projekt poskytuje klientskou knihovnu v JavaScriptu, která usnadňuje využívání služby Microsoft Azure File Storage.

Pomocí klientských knihoven v tomto balíčku:

Získání nebo nastavení vlastností souborové služby
Create, výpis nebo odstranění sdílených složek
Create, výpis nebo odstranění adresářů souborů
Create, čtení, výpis, aktualizace nebo odstranění souborů

Poznámka: Tento balíček byl dříve publikován pod názvem @azure/storage-file. Přejmenovala se na @azure/storage-file-share , aby lépe odpovídala chystanýmu novému balíčku pro Azure Storage Files DataLake a poskytovala konzistentní sadu rozhraní API pro práci se soubory v Azure.

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

LtS verze Node.js
Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v našich zásadách podpory .

Požadavky

Instalace balíčku

Upřednostňovaným způsobem instalace klientské knihovny služby Azure File Storage pro JavaScript je použití správce balíčků npm. Do okna terminálu zadejte následující:

npm install @azure/storage-file-share

Ověření klienta

Azure Storage podporuje několik způsobů ověřování. Abyste mohli pracovat se službou sdílené složky Azure Storage, budete muset vytvořit instanci klienta služby Storage , ShareServiceClientShareClient, nebo ShareDirectoryClient například . Další informace o ověřování najdete v ShareServiceClientukázkách pro vytvoření.

Sdílený klíč
Sdílené přístupové podpisy

Kompatibilita

Tato knihovna je kompatibilní s Node.js a prohlížeči a je ověřená ve verzích LTS Node.js (>=8.16.0) a nejnovějších verzích prohlížečů Chrome, Firefox a Edge.

Webové pracovní procesy

Tato knihovna vyžaduje, aby určité objekty MODELU DOM byly při použití v prohlížeči globálně dostupné, což webové pracovní procesy ve výchozím nastavení nezpřístupní. Aby tato knihovna fungovala ve webových pracovnících, budete je muset polyfillovat.

Další informace najdete v naší dokumentaci k používání sady Azure SDK pro JS ve webových pracovních procesůch.

Tato knihovna závisí na následujících rozhraních API dom, která při použití ve webových pracovních procesů vyžadují načtení externích polyfillů:

Rozdíly mezi Node.js a prohlížeči

Mezi modulem runtime Node.js a prohlížeče existují rozdíly. Když začínáte s touto knihovnou, věnujte pozornost rozhraním API nebo třídám označeným "POUZE K DISPOZICI V NODE.JS RUNTIME" nebo "K DISPOZICI POUZE V PROHLÍŽEČÍCH".

Pokud soubor obsahuje komprimovaná data ve gzip formátu nebo deflate a jeho kódování obsahu je nastaveno odpovídajícím způsobem, chování stahování se mezi Node.js a prohlížeči liší. V Node.js úložiště klienti stáhnou soubor v komprimovaném formátu, zatímco v prohlížečích se data stáhnou v dekomprimovaném formátu.

Následující funkce, rozhraní, třídy nebo funkce jsou k dispozici pouze v Node.js

Autorizace sdíleného klíče na základě názvu účtu a klíče účtu
- StorageSharedKeyCredential
Generování sdíleného přístupového podpisu (SAS)
- generateAccountSASQueryParameters()
- generateFileSASQueryParameters()
Paralelní nahrávání a stahování. Mějte na paměti, že ShareFileClient.uploadData() je k dispozici v Node.js i v prohlížečích.
- ShareFileClient.uploadFile()
- ShareFileClient.uploadStream()
- ShareFileClient.downloadToBuffer()
- ShareFileClient.downloadToFile()

Následující funkce, rozhraní, třídy nebo funkce jsou k dispozici pouze v prohlížečích.

–

JavaScript Bundle

Pokud chcete tuto klientskou knihovnu používat v prohlížeči, musíte nejprve použít nástroj bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci k sdružování.

CORS

Pokud potřebujete vyvíjet pro prohlížeče, musíte pro svůj účet úložiště nastavit pravidla sdílení prostředků mezi zdroji (CORS ). Přejděte na Azure Portal a Průzkumník služby Azure Storage, vyhledejte svůj účet úložiště a vytvořte nová pravidla CORS pro služby objektů blob, fronty, souborů a tabulek.

Můžete například vytvořit následující nastavení CORS pro ladění. Přizpůsobte si ale nastavení pečlivě podle svých požadavků v produkčním prostředí.

Povolené původy: *
Povolené příkazy: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
Povolené hlavičky: *
Vystavené hlavičky: *
Maximální věk (sekundy): 86400

Klíčové koncepty

Službu sdílené složky Azure Storage tvoří následující komponenty a jejich odpovídající klientské knihovny:

Samotný účet úložiště představovaný ShareServiceClient
Sdílená složka v rámci účtu úložiště reprezentovanáShareClient
Volitelná hierarchie adresářů v rámci sdílené složky reprezentovaná instancemi ShareDirectoryClient
Soubor v rámci sdílené složky, který může mít velikost až 1 TiB, reprezentovanýShareFileClient

Příklady

Import balíčku
Create klienta sdílené služby
Výpis sdílených složek v účtu
Create nové sdílené složky a adresáře
Create soubor Azure a pak do něj soubor nahrajte.
Výpis souborů a adresářů v adresáři
Stažení souboru a jeho převedení na řetězec (Node.js)
Stažení souboru a jeho převedení na řetězec (prohlížeče)

Import balíčku

Pokud chcete použít klienty, importujte balíček do souboru:

const AzureStorageFileShare = require("@azure/storage-file-share");

Případně můžete selektivně importovat pouze typy, které potřebujete:

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

Vyžaduje ShareServiceClient adresu URL služby sdílených složek a přihlašovací údaje pro přístup. Volitelně také přijímá některá nastavení v parametru options .

pomocí připojovací řetězec

Alternativně můžete vytvořit ShareServiceClient instanci pomocí fromConnectionString() statické metody s úplným připojovací řetězec jako argumentem. (Připojovací řetězec můžete získat z webu Azure Portal.)

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

S `StorageSharedKeyCredential`

Předejte parametr StorageSharedKeyCredential s názvem vašeho účtu a klíčem účtu. (Název účtu a klíč účtu je možné získat z webu Azure Portal.)

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

s tokenem SAS

Můžete také vytvořit ShareServiceClient instanci se sdílenými přístupovými podpisy (SAS). Token SAS můžete získat z webu Azure Portal nebo ho vygenerovat pomocí generateAccountSASQueryParameters().

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

Výpis sdílených složek v účtu

Použijte ShareServiceClient.listShares() k iterátoru sdílené složky v tomto účtu s novou 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();

Alternativně bez 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();

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

Create soubor Azure a pak do něj soubor nahrajte.

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

Výpis souborů a adresářů v adresáři

Používá DirectoryClient.listFilesAndDirectories() se k iterátoru souborů a adresářů s novou for-await-of syntaxí. Vlastnost kind lze použít k určení, zda iterm je adresář nebo soubor.

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

Alternativně bez použití 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();

Kompletní ukázku iterace najdete na stránce samples/v12/typescript/src/listFilesAndDirectories.ts.

Stažení souboru a jeho převedení na řetězec (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();

Stažení souboru a jeho převedení na řetězec (prohlížeče)

Další informace o používání této knihovny v prohlížeči najdete v části 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();

Úplný příklad jednoduchých ShareServiceClient scénářů najdete na stránce samples/v12/typescript/src/shareSerivceClient.ts.

Poradce při potížích

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v :@azure/logger

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

setLogLevel("info");

Další kroky

Další ukázky kódu

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

Další informace o nastavení testovacího prostředí pro knihovny úložiště najdete také v průvodci pro konkrétní úložiště.

Sdílet prostřednictvím

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Ověření klienta

Kompatibilita

Webové pracovní procesy

Rozdíly mezi Node.js a prohlížeči

Následující funkce, rozhraní, třídy nebo funkce jsou k dispozici pouze v Node.js

Následující funkce, rozhraní, třídy nebo funkce jsou k dispozici pouze v prohlížečích.

JavaScript Bundle

CORS

Klíčové koncepty

Příklady

Import balíčku

pomocí připojovací řetězec

S `StorageSharedKeyCredential`

s tokenem SAS

Výpis sdílených složek v účtu

Create soubor Azure a pak do něj soubor nahrajte.

Výpis souborů a adresářů v adresáři

Stažení souboru a jeho převedení na řetězec (Node.js)

Stažení souboru a jeho převedení na řetězec (prohlížeče)

Poradce při potížích

Další kroky

Přispívání

Váš názor

Další materiály

Sdílet prostřednictvím

Klientská knihovna sdílených složek Azure Storage pro JavaScript – verze 12.18.1

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Ověření klienta

Kompatibilita

Webové pracovní procesy

Rozdíly mezi Node.js a prohlížeči

Následující funkce, rozhraní, třídy nebo funkce jsou k dispozici pouze v Node.js

Následující funkce, rozhraní, třídy nebo funkce jsou k dispozici pouze v prohlížečích.

JavaScript Bundle

CORS

Klíčové koncepty

Příklady

Import balíčku

Create klienta sdílené služby

pomocí připojovací řetězec

S StorageSharedKeyCredential

s tokenem SAS

Výpis sdílených složek v účtu

Create nové sdílené složky a adresáře

Create soubor Azure a pak do něj soubor nahrajte.

Výpis souborů a adresářů v adresáři

Stažení souboru a jeho převedení na řetězec (Node.js)

Stažení souboru a jeho převedení na řetězec (prohlížeče)

Poradce při potížích

Další kroky

Přispívání

Váš názor

Další materiály

S `StorageSharedKeyCredential`