Libreria client di Condivisione file di Archiviazione di Azure per JavaScript - versione 12.24.0

File di Azure offre condivisioni file completamente gestite nel cloud accessibili tramite il protocollo SMB (Server Message Block) standard del settore. Le condivisioni file di Azure possono essere montate simultaneamente da distribuzioni cloud o locali di Windows, Linux e macOS. Inoltre, le condivisioni file di Azure possono essere memorizzate nella cache nei server Windows con Sincronizzazione file di Azure per l'accesso rapido nelle vicinanze in cui vengono usati i dati.

Questo progetto fornisce una libreria client in JavaScript che semplifica l'uso del servizio archiviazione file di Microsoft Azure.

Usare le librerie client in questo pacchetto per:

• Get/Set File Service Properties
• Creare/elencare/eliminare condivisioni file
• Creare/elencare/eliminare directory file
• Creare/leggere/elencare/aggiornare/eliminare file

Nota: questo pacchetto è stato pubblicato in precedenza con il nome @azure/storage-file. È stato rinominato in @azure/storage-file-share per allinearsi meglio al nuovo pacchetto imminente per DataLake di File di archiviazione di Azure e fornire un set coerente di API per l'uso dei file in Azure.

Collegamenti chiave:

• codice sorgente
• pacchetto (npm)
• documentazione di riferimento dell'API
• documentazione del prodotto
• esempi di
• API REST del file di archiviazione di Azure

Introduttiva

Ambienti attualmente supportati

• versioni LTS di Node.js
• Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

• Una sottoscrizione di Azure
• Un account di archiviazione

Installare il pacchetto

Il modo migliore per installare la libreria client di Archiviazione file di Azure per JavaScript consiste nell'usare la gestione pacchetti npm. Digitare quanto segue in una finestra del terminale:

npm install @azure/storage-file-share

Autenticare il client

Archiviazione di Azure supporta diversi modi per eseguire l'autenticazione. Per interagire con il servizio Condivisione file di Archiviazione di Azure, è necessario creare un'istanza di un client di archiviazione, ad esempio ShareServiceClient, ShareCliento ShareDirectoryClient. Per altre informazioni sull'autenticazione, vedere esempi per la creazione del ShareServiceClient.

• chiave condivisa
• firme di accesso condiviso

Compatibilità

Questa libreria è compatibile con Node.js e browser e convalidati rispetto alle versioni Node.js LTS (>=8.16.0) e versioni più recenti di Chrome, Firefox e Edge.

Web Worker

Questa libreria richiede che determinati oggetti DOM siano disponibili a livello globale quando vengono usati nel browser, che i web worker non rendono disponibili per impostazione predefinita. Sarà necessario eseguire il polyfill per rendere questa libreria funzionante nei web worker.

Per altre informazioni, vedere la documentazione di per l'uso di Azure SDK per JS in Web Worker

Questa libreria dipende dalle API DOM seguenti che richiedono polyfill esterni caricati quando vengono usati nei web worker:

• document
• DOMParser
• Node
• XMLSerializer

Differenze tra Node.js e browser

Esistono differenze tra Node.js e il runtime dei browser. Quando si inizia a usare questa libreria, prestare attenzione alle API o alle classi contrassegnate con "ONLY AVAILABLE IN NODE.JS RUNTIME" o "ONLY AVAILABLE IN BROWSERS".

• Se un file contiene dati compressi in formato gzip o deflate e la relativa codifica del contenuto viene impostata di conseguenza, il comportamento di download è diverso tra Node.js e browser. In Node.js client di archiviazione scaricherà il file nel formato compresso, mentre nei browser i dati verranno scaricati in formato decompresso.

Le funzionalità, le interfacce, le classi o le funzioni seguenti sono disponibili solo in Node.js

• Autorizzazione chiave condivisa basata sul nome dell'account e sulla chiave dell'account
  • StorageSharedKeyCredential
• Generazione della firma di accesso condiviso
  • generateAccountSASQueryParameters()
  • generateFileSASQueryParameters()
• Caricamento e download paralleli. Si noti che ShareFileClient.uploadData() è disponibile sia in Node.js che nei browser.
  • ShareFileClient.uploadFile()
  • ShareFileClient.uploadStream()
  • ShareFileClient.downloadToBuffer()
  • ShareFileClient.downloadToFile()

Le funzionalità, le interfacce, le classi o le funzioni seguenti sono disponibili solo nei browser

N/D

JavaScript Bundle

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

CORS

È necessario configurare regole cors (Cross-Origin Resource Sharing) per l'account di archiviazione se è necessario sviluppare per i browser. Passare al portale di Azure e Azure Storage Explorer, trovare l'account di archiviazione, creare nuove regole CORS per i servizi BLOB/queue/file/table.

Ad esempio, è possibile creare le impostazioni CORS seguenti per il debug. Ma personalizzare attentamente le impostazioni in base ai requisiti nell'ambiente di produzione.

• Origini consentite: *
• Verbi consentiti: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Intestazioni consentite: *
• Intestazioni esposte: *
• Età massima (secondi): 86400

Concetti chiave

I componenti seguenti e le librerie client corrispondenti costituiscono il servizio Condivisione file di archiviazione di Azure:

• L'account di archiviazione si, rappresentato da un ShareServiceClient
• Una condivisione file all'interno dell'account di archiviazione, rappresentata da un ShareClient
• Gerarchia facoltativa di directory all'interno della condivisione file, rappresentata da istanze di ShareDirectoryClient
• Un file all'interno della condivisione file, che può avere dimensioni fino a 1 TiB, rappresentate da un ShareFileClient

Esempi

• Importare il pacchetto
• Creare il client del servizio di condivisione
• Elenca le condivisioni nell'account
• Creare una nuova condivisione e una nuova directory
• Creare un file di Azure e caricarlo
• Elencare file e directory in una directory
• Scaricare un file e convertirlo in una stringa (Node.js)
• Scaricare un file e convertirlo in una stringa (Browser)

Importare il pacchetto

Per usare i client, importare il pacchetto nel file:

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

In alternativa, importare selettivamente solo i tipi necessari:

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

Creare il client del servizio di condivisione

Il ShareServiceClient richiede un URL per il servizio di condivisione file e una credenziale di accesso. Facoltativamente accetta anche alcune impostazioni nel parametro options.

uso della stringa di connessione

In alternativa, è possibile creare un'istanza di un ShareServiceClient usando il metodo statico fromConnectionString() con la stringa di connessione completa come argomento. La stringa di connessione può essere ottenuta dal portale di Azure.

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

con StorageSharedKeyCredential

Passare un StorageSharedKeyCredential con il nome dell'account e la chiave dell'account. È possibile ottenere il nome dell'account e la chiave dell'account dal portale di Azure.

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

con token di firma di accesso condiviso

È anche possibile creare un'istanza di un ShareServiceClient con firme di accesso condiviso. È possibile ottenere il token di firma di accesso condiviso dal portale di Azure o generarne uno usando 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}`
);

Elencare le condivisioni nell'account

Usare ShareServiceClient.listShares() per le condivisioni di iteratore in questo account, con la nuova sintassi di 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;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

In alternativa, senza 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();

Creare una nuova condivisione e una directory

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

Creare un file di Azure e quindi caricarlo

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

Elencare file e directory in una directory

Usare DirectoryClient.listFilesAndDirectories() per eseguire l'iteratore su file e directory, con la nuova sintassi di for-await-of. La proprietà kind può essere utilizzata per identificare se un iterm è una directory o un file.

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

In alternativa, senza usare 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);

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

Per un esempio completo sull'iterazione, vedere samples/v12/typescript/src/listFilesAndDirectories.ts.

Scaricare un file e convertirlo in una stringa (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();

Scaricare un file e convertirlo in una stringa (Browser)

Per altre informazioni sull'uso di questa libreria nel browser, vedere la sezione bundle JavaScript .

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

Un esempio completo di scenari di ShareServiceClient semplici è disponibile in samples/v12/typescript/src/shareSerivceClient.ts.

Risoluzione dei problemi

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Passaggi successivi

Altri esempi di codice

• di archiviazione di condivisione file (JavaScript)
• esempi di archiviazione di condivisione file (TypeScript)
• test case di archiviazione di condivisione file

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

Per altre informazioni sulla configurazione dell'ambiente di test per le librerie di archiviazione, vedere anche guida specifica all'archiviazione.