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

Článek
06/13/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í/nastavení vlastností souborové služby
Vytvoření, výpis nebo odstranění sdílených složek
Vytvoření, výpis nebo odstranění adresářů souborů
Vytvoření, čtení, výpis, aktualizace nebo odstranění souborů

Poznámka: Tento balíček byl dříve publikován pod názvem @azure/storage-file. Byla přejmenována 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, jak nainstalovat klientskou knihovnu Azure File Storage pro JavaScript, je použít 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, ShareServiceClientnapříklad , ShareClientnebo ShareDirectoryClient . 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 ověřuje se ve verzích LTS Node.js (>=8.16.0) a nejnovějších verzích prohlížečů Chrome, Firefox a Edge.

Pracovní procesy webu

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ích pracovních činnostech, budete je muset polyfillovat.

Další informace najdete v naší dokumentaci k používání sady Azure SDK pro JS ve webových pracovních prostředí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 Node.js a modulem runtime prohlížeče existují rozdíly. Při začátcích s touto knihovnou věnujte pozornost rozhraním API nebo třídám označeným jako "POUZE K DISPOZICI V NODE.JS RUNTIME" nebo "POUZE K DISPOZICI V PROHLÍŽEČÍCH".

Pokud soubor obsahuje komprimovaná data ve gzip formátu nebo deflate a jeho kódování obsahu je odpovídajícím způsobem nastaveno, chování stahování se mezi Node.js a prohlížeči liší. V Node.js storage 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í Všimněte si, ž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 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 web Azure Portal a Průzkumník služby Azure Storage, vyhledejte svůj účet úložiště a vytvořte nová pravidla CORS pro objekty blob, fronty, soubory nebo table služby.

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é zdroje: *
Povolené operace: 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ě reprezentovaný 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
Vytvoření klienta sdílené služby
Výpis sdílených složek v účtu
Vytvoření nové sdílené složky a adresáře
Vytvoření souboru Azure a jeho nahrání do něj
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, naimportujte balíček do souboru:

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

Případně můžete selektivně importovat jenom ty 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ího řetězce

Případně můžete vytvořit instanci ShareServiceClient pomocí fromConnectionString() statické metody s úplným připojovacím řetězcem jako argumentem. (Připojovací řetězec je možné 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 soubor 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();

Vytvoření souboru Azure a jeho nahrání do něj

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

Pracovní procesy webu

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ího řetězce

S `StorageSharedKeyCredential`

s tokenem SAS

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

Vytvoření souboru Azure a jeho nahrání do něj

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.23.0

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Ověření klienta

Kompatibilita

Pracovní procesy webu

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

Vytvoření klienta sdílené služby

pomocí připojovacího řetězce

S StorageSharedKeyCredential

s tokenem SAS

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

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

Vytvoření souboru Azure a jeho nahrání do něj

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`