Azure Storage File Share-klientbibliotek för JavaScript

Artikel
11/20/2024

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.

Förutsättningar

En Azure-prenumeration
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

Kompatibilitet

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

Ej tillämpligt

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 i storlek, representerad av en ShareFileClient

Exempel

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:

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

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

const { ShareServiceClient, StorageSharedKeyCredential } = require("@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.)

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

med `StorageSharedKeyCredential`

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

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

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

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

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:

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 shareIter = serviceClient.listShares();
  let i = 1;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

Alternativt utan 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() {
  const 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();

Skapa en Azure-fil och ladda sedan upp till den

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

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.

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

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

  const 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}`);
    }
    i++;
    item = await dirIter.next();
  }
}

main();

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)

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

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

Mer information om hur du använder det här biblioteket i webbläsaren finns i avsnittet 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();

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

Felsökning

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:

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

setLogLevel("info");

Nästa steg

Fler kodexempel

Bidragande

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 .

Dela via

Komma igång

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

Förutsättningar

Installera paketet

Autentisera klienten

Kompatibilitet

Webbarbetare

Skillnader mellan Node.js och webbläsare

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

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

JavaScript-paket

CORS

Viktiga begrepp

Exempel

Importera paketet

använda anslutningssträng

med `StorageSharedKeyCredential`

med SAS-token

Visa en lista över resurser i kontot

Skapa en Azure-fil och ladda sedan upp till den

Visa en lista över 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)

Felsökning

Nästa steg

Bidragande

Ytterligare resurser

Dela via

Azure Storage File Share-klientbibliotek för JavaScript – version 12.26.0

Komma igång

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

Förutsättningar

Installera paketet

Autentisera klienten

Kompatibilitet

Webbarbetare

Skillnader mellan Node.js och webbläsare

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

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

JavaScript-paket

CORS

Viktiga begrepp

Exempel

Importera paketet

Skapa resurstjänstklienten

använda anslutningssträng

med StorageSharedKeyCredential

med SAS-token

Visa en lista över resurser i kontot

Skapa en ny resurs och en katalog

Skapa en Azure-fil och ladda sedan upp till den

Visa en lista över 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)

Felsökning

Nästa steg

Bidragande

Ytterligare resurser

med `StorageSharedKeyCredential`