Azure Storage File Share-clientbibliotheek voor JavaScript

2025-10-17

Azure Files biedt volledig beheerde bestandsshares in de cloud die toegankelijk zijn via het SMB-protocol (Server Message Block) van de industriestandaard. Azure-bestandsshares kunnen gelijktijdig worden gekoppeld door cloud- of on-premises implementaties van Windows, Linux en macOS. Daarnaast kunnen Azure-bestandsshares in de cache worden opgeslagen op Windows-servers met Azure File Sync voor snelle toegang in de buurt waar de gegevens worden gebruikt.

Dit project biedt een clientbibliotheek in JavaScript waarmee u de Microsoft Azure File Storage-service eenvoudig kunt gebruiken.

Gebruik de clientbibliotheken in dit pakket om:

Eigenschappen van bestandsservice ophalen/instellen
Bestandsshares maken/weergeven/verwijderen
Bestandsmappen maken/weergeven/verwijderen
Bestanden maken/lezen/lijsten/bijwerken/verwijderen

Opmerking: dit pakket is eerder gepubliceerd onder de naam @azure/storage-file. De naam is gewijzigd in @azure/storage-file-share om beter af te stemmen op het toekomstige nieuwe pakket voor Azure Storage Files DataLake en een consistente set API's te bieden voor het werken met bestanden in Azure.

Sleutelkoppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

LTS-versies van Node.js
Nieuwste versies van Safari, Chrome, Edge en Firefox.

Zie ons ondersteuningsbeleid voor meer informatie.

Prerequisites

Een Azure-abonnement
Een opslagaccount

Het pakket installeren

De voorkeursmethode voor het installeren van de Azure File Storage-clientbibliotheek voor JavaScript is het gebruik van npm-pakketbeheer. Typ het volgende in een terminalvenster:

npm install @azure/storage-file-share

De client verifiëren

Azure Storage ondersteunt verschillende manieren om te verifiëren. Als u wilt communiceren met de Azure Storage-bestandsshareservice, moet u bijvoorbeeld een exemplaar van een Storage-client maken: ShareServiceClient, ShareClientof ShareDirectoryClient. Zie voorbeelden voor het maken van de ShareServiceClient voor meer informatie over verificatie.

Gedeelde sleutel
handtekeningen voor gedeelde toegang

Compatibility

Deze bibliotheek is compatibel met Node.js en browsers en gevalideerd op basis van LTS-Node.js versies (>=8.16.0) en de nieuwste versies van Chrome, Firefox en Edge.

Web Werkers

Voor deze bibliotheek moeten bepaalde DOM-objecten wereldwijd beschikbaar zijn wanneer ze worden gebruikt in de browser, die webmedewerkers niet standaard beschikbaar maken. U moet deze invullen om deze bibliotheek in webwerkrollen te laten werken.

Raadpleeg onze documentatie voor het gebruik van Azure SDK voor JS in Web Workers voor meer informatie

Deze bibliotheek is afhankelijk van de volgende DOM-API's waarvoor externe polyfills moeten worden geladen wanneer ze worden gebruikt in webwerkrollen:

Verschillen tussen Node.js en browsers

Er zijn verschillen tussen Node.js en runtime van browsers. Wanneer u aan de slag gaat met deze bibliotheek, moet u letten op API's of klassen die zijn gemarkeerd met 'ONLY AVAILABLE IN NODE.JS RUNTIME' of 'ONLY AVAILABLE IN BROWSERS'.

Als een bestand gecomprimeerde gegevens in gzip of deflate-indeling bevat en de inhoudscodering dienovereenkomstig is ingesteld, is het downloaden van gedrag anders tussen Node.js en browsers. In Node.js-opslagclients wordt het bestand in de gecomprimeerde indeling gedownload, terwijl in browsers de gegevens worden gedownload in gedeprimeerde indeling.

De volgende functies, interfaces, klassen of functies zijn alleen beschikbaar in Node.js

Autorisatie van gedeelde sleutels op basis van accountnaam en accountsleutel
- StorageSharedKeyCredential
Sas-generatie (Shared Access Signature)
- generateAccountSASQueryParameters()
- generateFileSASQueryParameters()
Parallel uploaden en downloaden. Houd er rekening mee dat ShareFileClient.uploadData() beschikbaar is in zowel Node.js als browsers.
- ShareFileClient.uploadFile()
- ShareFileClient.uploadStream()
- ShareFileClient.downloadToBuffer()
- ShareFileClient.downloadToFile()

De volgende functies, interfaces, klassen of functies zijn alleen beschikbaar in browsers

N/A

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.

CORS

U moet CORS-regels (Cross-Origin Resource Sharing) instellen regels voor uw opslagaccount als u voor browsers moet ontwikkelen. Ga naar Azure Portal en Azure Storage Explorer, zoek uw opslagaccount, maak nieuwe CORS-regels voor blob/queue/file/table-service(s).

U kunt bijvoorbeeld de volgende CORS-instellingen maken voor foutopsporing. Maar pas de instellingen zorgvuldig aan op basis van uw vereisten in de productieomgeving.

Toegestane oorsprongen: *
Toegestane werkwoorden: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Toegestane headers: *
Weergegeven headers: *
Maximale leeftijd (seconden): 86400

Belangrijke concepten

De volgende onderdelen en de bijbehorende clientbibliotheken vormen de Azure Storage-bestandsshareservice:

Het opslagaccount zelf, weergegeven door een ShareServiceClient
Een bestandsshare binnen het opslagaccount, weergegeven door een ShareClient
Een optionele hiërarchie van mappen binnen de bestandsshare, vertegenwoordigd door ShareDirectoryClient exemplaren
Een bestand binnen de bestandsshare, dat maximaal 1 TiB groot mag zijn, weergegeven door een ShareFileClient

Examples

het pakket importeren
De shareserviceclient maken
Lijstshares in het account
Een nieuwe share en een map maken
Een Azure-bestand maken en vervolgens uploaden naar het
Bestanden en mappen onder een map
Een bestand downloaden en converteren naar een tekenreeks (Node.js)
een bestand downloaden en converteren naar een tekenreeks (browsers)

Het pakket importeren

Als u de clients wilt gebruiken, importeert u het pakket in uw bestand:

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

U kunt ook selectief alleen de typen importeren die u nodig hebt:

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

De ShareServiceClient vereist een URL naar de bestandsshareservice en een toegangsreferentie. Het accepteert desgewenst ook bepaalde instellingen in de parameter options.

verbindingsreeks gebruiken

U kunt ook een ShareServiceClient maken met behulp van de statische methode fromConnectionString() met de volledige verbindingsreeks als argument. (De verbindingsreeks kan worden verkregen via azure Portal.)

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

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

met `StorageSharedKeyCredential`

Geef een StorageSharedKeyCredential door met uw accountnaam en accountsleutel. (De accountnaam en accountsleutel kunnen worden verkregen via de 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,
);

met SAS-token

U kunt ook een ShareServiceClient maken met shared access signatures (SAS). U kunt het SAS-token ophalen uit azure Portal of er een genereren met behulp van 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}`,
);

Shares weergeven in het account

Gebruik ShareServiceClient.listShares() om iterator-shares in dit account te iterator met de nieuwe for-await-of syntaxis:

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

U kunt ook zonder 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`);

Een Azure-bestand maken en er vervolgens naar uploaden

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

Bestanden en mappen onder een map weergeven

Gebruik DirectoryClient.listFilesAndDirectories() om bestanden en mappen te iterator met de nieuwe for-await-of syntaxis. De eigenschap kind kan worden gebruikt om te bepalen of een iterm een map of een bestand is.

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

U kunt ook 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++;
}

Voor een compleet voorbeeld van itereren , zie samples/v12/typescript/src/listFilesAndDirectories.ts.

Een bestand downloaden en converteren naar een tekenreeks (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);
  });
}

Een bestand downloaden en converteren naar een tekenreeks (browsers)

Raadpleeg de sectie JavaScript-bundel voor meer informatie over het gebruik van deze bibliotheek in de browser.

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

Een compleet voorbeeld van eenvoudige ShareServiceClient scenario's is te vinden op samples/v12/typescript/src/shareSerivceClient.ts.

Troubleshooting

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden

Contributing

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

Raadpleeg ook storage-specifieke handleiding voor aanvullende informatie over het instellen van de testomgeving voor opslagbibliotheken.

Feedback

Is deze pagina nuttig?