Delen via

Azure Storage File Share-clientbibliotheek voor JavaScript - versie 12.18.1

  • Artikel

Met Azure Files beschikt u over volledig beheerde bestandsshares in de cloud die toegankelijk zijn via het industriestandaard SMB-protocol (Server Message Block). Azure-bestandsshares kunnen gelijktijdig worden gekoppeld door on-premises implementaties of cloudimplementaties van Windows, Linux en macOS. Bovendien kunnen Azure-bestandsshares worden opgeslagen in de cache op Windows-servers met Azure-bestandssynchronisatie voor snelle toegang tot locaties waar de gegevens worden gebruikt.

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

Gebruik de clientbibliotheken in dit pakket voor het volgende:

  • Eigenschappen van bestandsservice ophalen/instellen
  • bestandsshares Creatie/lijst/verwijderen
  • bestandsmappen Creatie/lijst/verwijderen
  • bestanden Creatie/Lezen/Lijst/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 aanstaande nieuwe pakket voor Azure Storage Files DataLake en een consistente set API's te bieden voor het werken met bestanden in Azure.

Belangrijke koppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Vereisten

Het pakket installeren

De beste manier om de Azure File Storage-clientbibliotheek voor JavaScript te installeren, is met behulp 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 File Share-service, moet u een exemplaar van een Storage-client maken: ShareServiceClient, ShareClientof ShareDirectoryClient bijvoorbeeld. Zie voorbeelden voor het maken van de ShareServiceClient voor meer informatie over verificatie.

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.

Webwerkrollen

Deze bibliotheek vereist dat bepaalde DOM-objecten globaal beschikbaar zijn wanneer ze worden gebruikt in de browser, die webwerkrollen niet standaard beschikbaar maken. U moet deze invullen om deze bibliotheek te laten werken in webwerkrollen.

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 de runtime van Node.js en browsers. Let bij het aan de slag gaan met deze bibliotheek op API's of klassen die zijn gemarkeerd met 'ALLEEN BESCHIKBAAR IN NODE.JS RUNTIME' of 'ALLEEN BESCHIKBAAR IN BROWSERS'.

  • Als een bestand gecomprimeerde gegevens in of-indeling gzipdeflate bevat en de inhoudscodering dienovereenkomstig is ingesteld, verschilt het downloadgedrag tussen Node.js en browsers. In Node.js-opslagclients het bestand in de gecomprimeerde indeling downloaden, terwijl in browsers de gegevens in de gecomprimeerde indeling worden gedownload.
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 documentatie voor bundeling voor meer informatie over hoe u dit doet.

CORS

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

U kunt bijvoorbeeld de volgende CORS-instellingen voor foutopsporing maken. 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

Belangrijkste concepten

De volgende onderdelen en de bijbehorende clientbibliotheken vormen de Azure Storage File Share-service:

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

Voorbeelden

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 Creatie

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

met behulp van verbindingsreeks

U kunt ook een ShareServiceClient instantiëren met behulp van de fromConnectionString() statische methode met de volledige verbindingsreeks als argument. (De verbindingsreeks kunt u verkrijgen 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 de 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 instantiëren met een SAS (Shared Access Signatures). U kunt het SAS-token ophalen uit de Azure-portal of een token 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 in het account weergeven

Gebruik ShareServiceClient.listShares() om shares in dit account te iteratoren 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() {
  let 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() {
  let 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();

een nieuwe share en een map Creatie

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 Creatie en vervolgens uploaden naar het bestand

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 iteratoren met de nieuwe for-await-of syntaxis. De kind eigenschap 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);

  let 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 het volgende doen for-await-ofzonder :

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

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

main();

Zie samples/v12/typescript/src/listFilesAndDirectories.ts voor een volledig voorbeeld van het 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-bundel 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 vindt u in samples/v12/typescript/src/shareSerivceClient.ts.

Problemen oplossen

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. Logboekregistratie kan ook worden ingeschakeld tijdens runtime door aan te roepen setLogLevel 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 handleiding voor bijdragen voor meer informatie over het bouwen en testen van de code.

Raadpleeg ook De specifieke handleiding voor opslag voor meer informatie over het instellen van de testomgeving voor opslagbibliotheken.

Weergaven