Azure Storage File Share-klientbibliotek för JavaScript

2025-10-17

Azure Files erbjuder fullständigt hanterade filresurser i molnet som är tillgängliga via SMB-protokollet (Server Message Block). Azure-filresurser kan monteras samtidigt av molnbaserade eller lokala distributioner av Windows, Linux och macOS. Dessutom kan Azure-filresurser cachelagras på Windows-servrar med Azure File Sync för snabb åtkomst nära där data används.

Det här projektet tillhandahåller ett klientbibliotek i JavaScript som gör det enkelt att använda Microsoft Azure File Storage-tjänsten.

Använd klientbiblioteken i det här paketet för att:

Hämta/ange egenskaper för filtjänsten
Skapa/lista/ta bort filresurser
Skapa/lista/ta bort filkataloger
Skapa/läsa/lista/uppdatera/ta bort filer

Obs! Det här paketet publicerades tidigare under namnet @azure/storage-file. Det har bytt namn till @azure/storage-file-share för att bättre anpassa till det kommande nya paketet för Azure Storage Files DataLake och tillhandahålla en konsekvent uppsättning API:er för att arbeta med filer i Azure.

Nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Edge och Firefox.

Mer information finns i vår supportprincip.

Prerequisites

En prenumeration på Azure
Ett lagringskonto

Installera paketet

Det bästa sättet att installera Azure File Storage-klientbiblioteket för JavaScript är att använda npm-pakethanteraren. Skriv följande i ett terminalfönster:

npm install @azure/storage-file-share

Autentisera klienten

Azure Storage stöder flera sätt att autentisera. För att kunna interagera med Azure Storage File Share-tjänsten måste du skapa en instans av en Lagringsklient – ShareServiceClient, ShareClienteller ShareDirectoryClient till exempel. Mer information om autentisering finns i exempel för att skapa ShareServiceClient.

Delad nyckel
Signaturer för delad åtkomst

Compatibility

Det här biblioteket är kompatibelt med Node.js och webbläsare och verifieras mot LTS-Node.js versioner (>=8.16.0) och de senaste versionerna av Chrome, Firefox och Edge.

Webbarbetare

Det här biblioteket kräver att vissa DOM-objekt är globalt tillgängliga när de används i webbläsaren, vilket webbarbetare inte gör tillgängliga som standard. Du måste polyfylla dessa för att det här biblioteket ska fungera i webbarbetare.

Mer information finns i vår dokumentation för att använda Azure SDK för JS i Web Workers

Det här biblioteket är beroende av följande DOM-API:er som behöver externa polyfyller som läses in när de används i webbarbetare:

Skillnader mellan Node.js och webbläsare

Det finns skillnader mellan Node.js och webbläsarkörning. När du kommer igång med det här biblioteket bör du vara uppmärksam på API:er eller klasser som har markerats med "ONLY AVAILABLE IN NODE.JS RUNTIME" eller "ONLY AVAILABLE IN BROWSERS".

Om en fil innehåller komprimerade data i gzip eller deflate format och dess innehållskodning anges i enlighet med detta skiljer sig nedladdningsbeteendet mellan Node.js och webbläsare. I Node.js kommer lagringsklienter att ladda ned filen i komprimerat format, medan data i webbläsare laddas ned i komprimerat format.

Följande funktioner, gränssnitt, klasser eller funktioner är endast tillgängliga i Node.js

Auktorisering av delad nyckel baserat på kontonamn och kontonyckel
- StorageSharedKeyCredential
Generering av signatur för delad åtkomst (SAS)
- generateAccountSASQueryParameters()
- generateFileSASQueryParameters()
Parallell uppladdning och nedladdning. Observera att ShareFileClient.uploadData() finns i både Node.js och webbläsare.
- ShareFileClient.uploadFile()
- ShareFileClient.uploadStream()
- ShareFileClient.downloadToBuffer()
- ShareFileClient.downloadToFile()

Följande funktioner, gränssnitt, klasser eller funktioner är endast tillgängliga i webbläsare

N/A

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

CORS

Du måste konfigurera CORS (Cross-Origin Resource Sharing) regler för ditt lagringskonto om du behöver utveckla för webbläsare. Gå till Azure-portalen och Azure Storage Explorer, leta reda på ditt lagringskonto, skapa nya CORS-regler för blob/kö/fil/tabelltjänster.

Du kan till exempel skapa följande CORS-inställningar för felsökning. Men anpassa inställningarna noggrant enligt dina krav i produktionsmiljön.

Tillåtet ursprung: *
Tillåtna verb: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Tillåtna rubriker: *
Synliga rubriker: *
Maximal ålder (sekunder): 86400

Viktiga begrepp

Följande komponenter och deras motsvarande klientbibliotek utgör Azure Storage File Share-tjänsten:

Själva lagringskontot , som representeras av en ShareServiceClient
En filresurs i lagringskontot, som representeras av en ShareClient
En valfri hierarki med kataloger i filresursen, representerad av ShareDirectoryClient instanser
En fil i filresursen, som kan vara upp till 1 TiB stor, som representeras av en ShareFileClient

Examples

Importera paketet
Skapa resurstjänstklienten
Lista resurser i kontot
Skapa en ny resurs och en katalog
Skapa en Azure-fil och ladda sedan upp till den
Lista filer och kataloger under en katalog
Ladda ned en fil och konvertera den till en sträng (Node.js)
Ladda ned en fil och konvertera den till en sträng (webbläsare)

Importera paketet

Om du vill använda klienterna importerar du paketet till filen:

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

Alternativt importerar du endast de typer du behöver selektivt:

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

ShareServiceClient kräver en URL till filresurstjänsten och en åtkomstautentiseringsuppgift. Du kan också välja att acceptera vissa inställningar i parametern options.

använda anslutningssträng

Du kan också instansiera en ShareServiceClient med hjälp av den fromConnectionString() statiska metoden med den fullständiga anslutningssträngen som argument. (Anslutningssträngen kan hämtas från Azure-portalen.)

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

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

med `StorageSharedKeyCredential`

Skicka in en StorageSharedKeyCredential med ditt kontonamn och din kontonyckel. (Kontonamnet och kontonyckeln kan hämtas från Azure-portalen.)

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

med SAS-token

Du kan också instansiera en ShareServiceClient med en signatur för delad åtkomst (SAS). Du kan hämta SAS-token från Azure-portalen eller generera en med hjälp av 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}`,
);

Visa en lista över resurser i kontot

Använd ShareServiceClient.listShares() till iteratorresurser i det här kontot med den nya for-await-of syntaxen:

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

Alternativt utan 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`);

Skapa en Azure-fil och ladda sedan upp till den

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

Visa en lista över filer och kataloger under en katalog

Använd DirectoryClient.listFilesAndDirectories() för att iterator över filer och kataloger med den nya for-await-of syntaxen. Egenskapen kind kan användas för att identifiera om en iterm är en katalog eller en fil.

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++;
}

Alternativt utan att använda 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++;
}

Ett fullständigt exempel på iterering finns i samples/v12/typescript/src/listFilesAndDirectories.ts.

Ladda ned en fil och konvertera den till en sträng (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);
  });
}

Ladda ned en fil och konvertera den till en sträng (webbläsare)

Se avsnittet JavaScript-paket för mer information om hur du använder det här biblioteket i webbläsaren.

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

Ett fullständigt exempel på enkla ShareServiceClient scenarier finns på samples/v12/typescript/src/shareSerivceClient.ts.

Troubleshooting

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Nästa steg

Fler kodexempel

Contributing

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Mer information om hur du konfigurerar testmiljön för lagringsbibliotek finns i storage specific guide .

Feedback

Var den här sidan till hjälp?