Klientská knihovna sdílené složky azure Storage pro JavaScript

Článek
07/24/2024

Azure Files nabízí plně spravované sdílené složky v cloudu, které jsou přístupné přes standardní protokol SMB (Server Message Block). Sdílené složky Azure je možné připojit souběžně cloudovým nebo místním nasazením systémů Windows, Linux a macOS. Sdílené složky Azure je navíc možné ukládat do mezipaměti na serverech s Windows pomocí Synchronizace souborů Azure pro rychlý přístup blízko 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.

Klientské knihovny v tomto balíčku slouží k:

Získání nebo 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í, seznam, aktualizace, 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 připravovanému novému balíčku pro DataLake služby Azure Storage Files a poskytovala konzistentní sadu rozhraní API pro práci se soubory v Azure.

Klíčové odkazy:

zdrojového kódu
balíčku (npm)
Referenční dokumentace k rozhraní API
dokumentace k produktu
ukázky
rozhraní REST API služby Azure Storage File

Začínáme

Aktuálně podporovaná prostředí

LTS verze Node.js
Nejnovější verze Safari, Chrome, Edge a Firefox.

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

Požadavky

Předplatné Azure
účtu úložiště

Instalace balíčku

Upřednostňovaným způsobem instalace klientské knihovny 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í. Pokud chcete pracovat se službou sdílené složky Azure Storage, budete muset vytvořit instanci klienta služby Storage – ShareServiceClient, ShareClientnebo ShareDirectoryClient. Další informace o ověřování najdete v ukázkách pro vytvoření ShareServiceClient.

sdílený klíč
sdílených přístupových podpisů

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 Chromu, Firefoxu a Edge.

Webové pracovní procesy

Tato knihovna vyžaduje, aby byly určité objekty MODELU DOM globálně dostupné při použití v prohlížeči, které webové pracovní procesy ve výchozím nastavení nedostupují. Pokud chcete, aby tato knihovna fungovala ve webových pracovních pracovních procesů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

Tato knihovna závisí na následujících rozhraních API DOM, která potřebují externí polyfilly načtené při použití ve webových pracovních procesů:

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

Mezi modulem runtime Node.js a prohlížečů existují rozdíly. Při zahájení práce s touto knihovnou věnujte pozornost rozhraním API nebo třídám označeným "POUZE K DISPOZICI V NODE.JS RUNTIME" nebo "POUZE DOSTUPNÉ V PROHLÍŽEČÍCH".

Pokud soubor obsahuje komprimovaná data ve formátu gzip nebo deflate a jeho kódování obsahu je nastavené odpovídajícím způsobem, chování při stahování se liší mezi Node.js a prohlížeči. V Node.js klienti úložiště stáhnou soubor v jeho 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 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.

Není k dispozici

JavaScript Bundle

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

CORS

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

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í stáří (sekundy): 86400

Klíčové koncepty

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

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

Příklady

Import balíčku
Vytvoření klienta sdílené služby
Zobrazit sdílené složky v účtu
Vytvoření nové sdílené složky a adresáře
vytvoření souboru Azure a jeho nahrání
Výpis souborů a adresářů v adresáři
Stáhnout soubor a převést ho na řetězec (Node.js)
Stáhnout soubor a převést ho 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");

Alternativně selektivně importujte pouze typy, které potřebujete:

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

ShareServiceClient vyžaduje adresu URL služby sdílené složky 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

Alternativně můžete vytvořit instanci ShareServiceClient pomocí fromConnectionString() statické metody s úplným připojovacím řetězcem jako argumentem. (Připojovací řetězec lze 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 StorageSharedKeyCredential s názvem úč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 instanci ShareServiceClient 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() ke sdíleným složkám v tomto účtu s novou syntaxí 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;
  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řte soubor Azure a pak ho 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

Pomocí DirectoryClient.listFilesAndDirectories() iterátoru nad soubory a adresáři s novou syntaxí for-await-of. Vlastnost kind lze použít k identifikaci, 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 v tématu samples/v12/typescript/src/listFilesAndDirectories.ts.

Stáhněte soubor a převeďte ho 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();

Stáhněte si soubor a převeďte ho 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 scénářů ShareServiceClient je v samples/v12/typescript/src/shareSerivceClient.ts.

Řešení problémů

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete 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ívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

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

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

s `StorageSharedKeyCredential`

s tokenem SAS

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

Vytvořte soubor Azure a pak ho nahrajte.

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

Stáhněte soubor a převeďte ho na řetězec (Node.js)

Stáhněte si soubor a převeďte ho na řetězec (prohlížeče).

Řešení problémů

Další kroky

Přispívající

Další materiály

Sdílet prostřednictvím

Klientská knihovna sdílené složky Azure Storage pro JavaScript – verze 12.24.0

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

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řte soubor Azure a pak ho nahrajte.

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

Stáhněte soubor a převeďte ho na řetězec (Node.js)

Stáhněte si soubor a převeďte ho na řetězec (prohlížeče).

Řešení problémů

Další kroky

Přispívající

Další materiály

s `StorageSharedKeyCredential`