Azure Storage File Share-clientbibliotheek voor JavaScript

Artikel
11/20/2024

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/weergeven/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:

Slag

Momenteel ondersteunde omgevingen

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

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

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

Compatibiliteit

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.

Webmedewerkers

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.V.T

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

Sleutelbegrippen

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

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

Voorbeelden

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:

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

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

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

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

met `StorageSharedKeyCredential`

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

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

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

Shares weergeven in het account

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

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

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

Een Azure-bestand maken en er vervolgens naar uploaden

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

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.

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

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

Zie samples/v12/typescript/src/listFilesAndDirectories.tsvoor een volledig voorbeeld over herhalen.

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

Een bestand downloaden en converteren naar een tekenreeks (browsers)

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

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

Een volledig voorbeeld van eenvoudige ShareServiceClient-scenario's bevindt zich in samples/v12/typescript/src/shareSerivceClient.ts.

Probleemoplossing

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:

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

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden

Bijdragen

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.

Delen via

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

Het pakket installeren

De client verifiëren

Compatibiliteit

Webmedewerkers

Verschillen tussen Node.js en browsers

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

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

JavaScript-bundel

CORS

Sleutelbegrippen

Voorbeelden

Het pakket importeren

verbindingsreeks gebruiken

met `StorageSharedKeyCredential`

met SAS-token

Shares weergeven in het account

Een Azure-bestand maken en er vervolgens naar uploaden

Bestanden en mappen onder een map weergeven

Een bestand downloaden en converteren naar een tekenreeks (Node.js)

Een bestand downloaden en converteren naar een tekenreeks (browsers)

Probleemoplossing

Volgende stappen

Bijdragen

Aanvullende resources

Delen via

Azure Storage File Share-clientbibliotheek voor JavaScript - versie 12.26.0

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

Het pakket installeren

De client verifiëren

Compatibiliteit

Webmedewerkers

Verschillen tussen Node.js en browsers

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

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

JavaScript-bundel

CORS

Sleutelbegrippen

Voorbeelden

Het pakket importeren

De shareserviceclient maken

verbindingsreeks gebruiken

met StorageSharedKeyCredential

met SAS-token

Shares weergeven in het account

Een nieuwe share en een map maken

Een Azure-bestand maken en er vervolgens naar uploaden

Bestanden en mappen onder een map weergeven

Een bestand downloaden en converteren naar een tekenreeks (Node.js)

Een bestand downloaden en converteren naar een tekenreeks (browsers)

Probleemoplossing

Volgende stappen

Bijdragen

Aanvullende resources

met `StorageSharedKeyCredential`