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

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ů
Vytváření/čtení/seznam/aktualizace/mazá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ý kód
Balíček (npm)
Referenční dokumentace k rozhraní API
dokumentace k produktu
Samples
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 zásadách podpory.

Prerequisites

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ů

Compatibility

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íci

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.

N/A

JavaScriptový balíček

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 k 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ý ShareServiceClient
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

Examples

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:

import * as AzureStorageFileShare from "@azure/storage-file-share";

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

import { ShareServiceClient, StorageSharedKeyCredential } from "@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.)

import { ShareServiceClient } from "@azure/storage-file-share";

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

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

import { StorageSharedKeyCredential, ShareServiceClient } from "@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().

import { ShareServiceClient } from "@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:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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,
);

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

Alternativně bez for-await-of:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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 shareIter = serviceClient.listShares();
let i = 1;
let { value, done } = await shareIter.next();
while (!done) {
  console.log(`Share ${i++}: ${value.name}`);
  ({ value, done } = await shareIter.next());
}

import { StorageSharedKeyCredential, ShareServiceClient } from "@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 = `newshare${+new Date()}`;
const shareClient = serviceClient.getShareClient(shareName);
await shareClient.create();
console.log(`Create share ${shareName} successfully`);

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

Vytvořte soubor Azure a pak ho nahrajte.

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

const content = "Hello World!";
const fileName = `newdirectory${+new Date()}`;
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`);

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.

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

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

Alternativně bez použití for-await-of:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

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

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

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

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
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();
if (downloadFileResponse.readableStreamBody) {
  const buffer = await streamToBuffer(downloadFileResponse.readableStreamBody);
  console.log(`Downloaded file content: ${buffer.toString()}`);
}

// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
async function streamToBuffer(readableStream: NodeJS.ReadableStream): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

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 naleznete v části JavaScript Bundle .

import { ShareServiceClient } from "@azure/storage-file-share";

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

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

const shareName = "<share name>";
const fileName = "<file name>";
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);
if (downloadFileResponse.blobBody) {
  console.log(`Downloaded file content: ${(await downloadFileResponse.blobBody).text()}`);
}

Úplný příklad jednoduchých ShareServiceClient scénářů je k dispozici na adrese samples/v12/typescript/src/shareSerivceClient.ts.

Troubleshooting

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:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Další kroky

Další ukázky kódu

Contributing

Pokud chcete přispívat do této knihovny, přečtěte si průvodce pro přispívání a přečtěte si 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 Storage.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-17