Bibliothèque cliente de partage de fichiers Stockage Azure pour JavaScript - version 12.24.0

Azure Files offre des partages de fichiers entièrement managés dans le cloud accessibles via le protocole SMB (Server Message Block) standard du secteur. Les partages de fichiers Azure peuvent être montés simultanément par des déploiements cloud ou locaux de Windows, Linux et macOS. En outre, les partages de fichiers Azure peuvent être mis en cache sur des serveurs Windows avec Azure File Sync pour un accès rapide près de l’endroit où les données sont utilisées.

Ce projet fournit une bibliothèque cliente en JavaScript qui facilite l’utilisation du service stockage de fichiers Microsoft Azure.

Utilisez les bibliothèques clientes dans ce package pour :

• Get/Set File Service Properties
• Créer/répertorier/supprimer des partages de fichiers
• Créer/répertorier/supprimer des répertoires de fichiers
• Créer/lire/liste/mettre à jour/supprimer des fichiers

Remarque : Ce package a été publié précédemment sous le nom @azure/storage-file. Il a été renommé en @azure/storage-file-share pour mieux s’aligner sur le nouveau package à venir pour Azure Storage Files DataLake et fournir un ensemble cohérent d’API permettant d’utiliser des fichiers sur Azure.

Liens clés :

• code source
• package (npm)
• Documentation de référence de l’API
• documentation produit
• Exemples
• API REST de fichier stockage Azure

Commencer

Environnements actuellement pris en charge

• versions LTS de Node.js
• Dernières versions de Safari, Chrome, Edge et Firefox.

Pour plus d’informations, consultez notre de stratégie de support .

Conditions préalables

• Un abonnement Azure
• Un compte de stockage

Installer le package

La méthode recommandée pour installer la bibliothèque cliente Stockage Fichier Azure pour JavaScript consiste à utiliser le gestionnaire de package npm. Tapez ce qui suit dans une fenêtre de terminal :

npm install @azure/storage-file-share

Authentifier le client

Stockage Azure prend en charge plusieurs façons de s’authentifier. Pour interagir avec le service de partage de fichiers stockage Azure, vous devez créer une instance d’un client de stockage , ShareServiceClient, ShareClientou ShareDirectoryClient par exemple. Consultez exemples pour créer le ShareServiceClient pour en savoir plus sur l’authentification.

• de clé partagée
• signatures d’accès partagé

Compatibilité

Cette bibliothèque est compatible avec Node.js et les navigateurs, et validée par rapport aux versions de LTS Node.js (>=8.16.0) et les dernières versions de Chrome, Firefox et Edge.

Web Workers

Cette bibliothèque nécessite que certains objets DOM soient globalement disponibles lorsqu’ils sont utilisés dans le navigateur, que les travailleurs web ne rendent pas disponibles par défaut. Vous devrez les polyfiller pour que cette bibliothèque fonctionne dans les workers web.

Pour plus d’informations, reportez-vous à notre documentation pour l’utilisation du Kit de développement logiciel (SDK) Azure pour JS dans web Workers

Cette bibliothèque dépend des API DOM suivantes qui nécessitent des polyfills externes chargés lors de l’utilisation dans les workers web :

• document
• DOMParser
• Node
• XMLSerializer

Différences entre les Node.js et les navigateurs

Il existe des différences entre Node.js et le runtime des navigateurs. Lors de la prise en main de cette bibliothèque, faites attention aux API ou aux classes marquées avec « DISPONIBLE UNIQUEMENT DANS NODE.JS RUNTIME » ou « UNIQUEMENT DISPONIBLE DANS LES NAVIGATEURS ».

• Si un fichier contient des données compressées au format gzip ou deflate et que son encodage de contenu est défini en conséquence, le comportement de téléchargement est différent entre Node.js et les navigateurs. Dans Node.js clients de stockage téléchargent le fichier dans son format compressé, tandis que dans les navigateurs, les données seront téléchargées au format décompressé.

Les fonctionnalités, interfaces, classes ou fonctions suivantes sont disponibles uniquement dans Node.js

• Autorisation de clé partagée basée sur le nom du compte et la clé de compte
  • StorageSharedKeyCredential
• Génération de signature d’accès partagé (SAP)
  • generateAccountSASQueryParameters()
  • generateFileSASQueryParameters()
• Chargement et téléchargement parallèles. Notez que ShareFileClient.uploadData() est disponible dans les Node.js et les navigateurs.
  • ShareFileClient.uploadFile()
  • ShareFileClient.uploadStream()
  • ShareFileClient.downloadToBuffer()
  • ShareFileClient.downloadToFile()

Les fonctionnalités, interfaces, classes ou fonctions suivantes sont disponibles uniquement dans les navigateurs

N/A

JavaScript Bundle

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

CORS

Vous devez configurer règles de partage de ressources cross-origin (CORS) pour votre compte de stockage si vous devez développer pour les navigateurs. Accédez au portail Azure et à l’Explorateur Stockage Azure, recherchez votre compte de stockage, créez de nouvelles règles CORS pour les services blob/file/file/table.

Par exemple, vous pouvez créer les paramètres CORS suivants pour le débogage. Mais personnalisez soigneusement les paramètres en fonction de vos besoins dans l’environnement de production.

• Origines autorisées : *
• Verbes autorisés : DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• En-têtes autorisés : *
• En-têtes exposés : *
• Âge maximal (secondes) : 86400

Concepts clés

Les composants suivants et leurs bibliothèques clientes correspondantes composent le service de partage de fichiers Stockage Azure :

• Le compte de stockage lui-même, représenté par un
• Un partage de fichiers dans le compte de stockage, représenté par un ShareClient
• Hiérarchie facultative des répertoires au sein du partage de fichiers, représentée par des instances de ShareDirectoryClient
• Un fichier au sein du partage de fichiers, qui peut avoir une taille maximale de 1 Tio, représentée par un ShareFileClient

Exemples

• Importer le package
• Créer le client de service de partage
• Répertorier les partages dans le compte
• Créer un partage et un répertoire
• Créer un fichier Azure, puis le charger
• Répertorier les fichiers et répertoires sous un répertoire
• Télécharger un fichier et le convertir en chaîne (Node.js)
• Télécharger un fichier et le convertir en chaîne (navigateurs)

Importer le package

Pour utiliser les clients, importez le package dans votre fichier :

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

Vous pouvez également importer sélectivement uniquement les types dont vous avez besoin :

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

Créer le client de service de partage

La ShareServiceClient nécessite une URL vers le service de partage de fichiers et des informations d’identification d’accès. Il accepte également certains paramètres dans le paramètre options.

à l’aide de la chaîne de connexion

Vous pouvez également instancier un ShareServiceClient à l’aide de la méthode statique fromConnectionString() avec la chaîne de connexion complète comme argument. (La chaîne de connexion peut être obtenue à partir du portail Azure.)

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

avec StorageSharedKeyCredential

Transmettez une StorageSharedKeyCredential avec le nom de votre compte et votre clé de compte. (Le nom du compte et la clé de compte peuvent être obtenus à partir du portail 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
);

avec un jeton SAP

En outre, vous pouvez instancier un ShareServiceClient avec des signatures d’accès partagé (SAP). Vous pouvez obtenir le jeton SAP à partir du portail Azure ou en générer un à l’aide de 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}`
);

Répertorier les partages dans le compte

Utilisez ShareServiceClient.listShares() pour itérer des partages dans ce compte, avec la nouvelle syntaxe 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();

Sinon, sans 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();

Créer un partage et un répertoire

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

Créez un fichier Azure, puis chargez-le vers celui-ci

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

Répertorier les fichiers et les répertoires sous un répertoire

Utilisez DirectoryClient.listFilesAndDirectories() pour itérateur sur les fichiers et les répertoires, avec la nouvelle syntaxe for-await-of. La propriété kind peut être utilisée pour identifier si un iterm est un répertoire ou un fichier.

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

Sinon, sans utiliser 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();

Pour obtenir un exemple complet sur l’itération, consultez samples/v12/typescript/src/listFilesAndDirectories.ts.

Téléchargez un fichier et convertissez-le en chaîne (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();

Téléchargez un fichier et convertissez-le en chaîne (Navigateurs)

Pour plus d’informations sur l’utilisation de cette bibliothèque dans le navigateur, reportez-vous à la section 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 exemple complet de scénarios de ShareServiceClient simples se trouve à samples/v12/typescript/src/shareSerivceClient.ts.

Dépannage

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Étapes suivantes

Autres exemples de code

• exemples de stockage de partage de fichiers (JavaScript)
• exemples de stockage de partage de fichiers (TypeScript)
• cas de test de stockage de partage de fichiers

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Consultez également guide spécifique au stockage pour plus d’informations sur la configuration de l’environnement de test pour les bibliothèques de stockage.