Share via

Bibliothèque cliente de partage de fichiers stockage Azure pour JavaScript - version 12.18.1

  • Article

Azure Files offre des partages de fichiers complètement managés dans le cloud, accessibles via le protocole SMB (Server Message Block) standard. Les partages de fichiers Azure peuvent être montés simultanément via des déploiements cloud ou locaux de Windows, Linux et macOS. En outre, les partages de fichiers Azure peuvent être mis en cache sur les serveurs Windows avec Azure File Sync pour un accès rapide à proximité 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 de ce package pour :

  • Obtenir/définir les propriétés du service de fichiers
  • Create/Liste/Supprimer des partages de fichiers
  • Create/Liste/Supprimer des répertoires de fichiers
  • Create/Read/List/Update/Delete Files

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

Liens clés :

Prise en main

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre politique de support .

Prérequis

Installer le package

La méthode recommandée pour installer la bibliothèque cliente stockage de fichiers 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 Partage de fichiers stockage Azure, vous devez créer un instance d’un client de stockage , ShareServiceClientShareClientou ShareDirectoryClient par exemple. Consultez les exemples de création de pour en savoir plus sur l’authentification ShareServiceClient .

Compatibilité

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

Web Workers

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

Pour plus d’informations, consultez notre documentation sur 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 lorsqu’ils sont utilisés dans les web Workers :

Différences entre les Node.js et les navigateurs

Il existe des différences entre le runtime Node.js et le runtime des navigateurs. Lorsque vous commencez à utiliser cette bibliothèque, faites attention aux API ou aux classes marquées « UNIQUEMENT DISPONIBLE DANS NODE.JS RUNTIME » ou « UNIQUEMENT DISPONIBLE DANS LES NAVIGATEURS ».

  • Si un fichier contient des données compressées au format ou et deflate que son encodage de contenu est défini en gzip conséquence, le comportement de téléchargement est différent entre Node.js et les navigateurs. Dans Node.js les clients de stockage téléchargent le fichier dans son format compressé, tandis que dans les navigateurs, les données sont téléchargées au format décompressé.
Les fonctionnalités, interfaces, classes ou fonctions suivantes sont uniquement disponibles dans Node.js
  • Autorisation de clé partagée en fonction du nom du compte et de la clé de compte
    • StorageSharedKeyCredential
  • Génération de signature d’accès partagé (SAS)
    • generateAccountSASQueryParameters()
    • generateFileSASQueryParameters()
  • Chargement et téléchargement parallèles. Notez qu’il 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 uniquement disponibles dans les navigateurs

N/A

Ensemble JavaScript

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

CORS

Vous devez configurer des règles CORS (Cross-Origin Resource Sharing) pour votre compte de stockage si vous devez développer pour les navigateurs. Accédez à Portail Azure et Explorateur Stockage Azure, recherchez votre compte de stockage, créez des 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 constituent le service De partage de fichiers stockage Azure :

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

Exemples

Importation du package

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

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

Sinon, importez de manière sélective uniquement les types dont vous avez besoin :

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

Create le client de service de partage

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

utilisation de chaîne de connexion

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

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

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

Avec StorageSharedKeyCredential

Passez un StorageSharedKeyCredential avec votre nom de 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 jeton SAS

En outre, vous pouvez instancier un avec une signature d’accès ShareServiceClient partagé (SAP). Vous pouvez obtenir le jeton SAS à 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 les partages dans ce compte, avec la nouvelle for-await-of syntaxe :

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

Create un nouveau 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();

Create un fichier Azure, puis le charger dans 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 répertoires sous un répertoire

Utilisez DirectoryClient.listFilesAndDirectories() pour itérer sur les fichiers et les répertoires, avec la nouvelle for-await-of syntaxe. La kind propriété peut être utilisée pour déterminer 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 d’itération, consultez samples/v12/typescript/src/listFilesAndDirectories.ts.

Télécharger un fichier et le convertir 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écharger un fichier et le convertir en chaîne (Navigateurs)

Pour plus d’informations sur l’utilisation de cette bibliothèque dans le navigateur, consultez la section JavaScript Bundle .

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

Voici un exemple complet de scénarios simples ShareServiceClient dans samples/v12/typescript/src/shareSerivceClient.ts.

Dépannage

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir 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 @azure/logger :

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

setLogLevel("info");

Étapes suivantes

Autres exemples de code

Contribution

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.

Reportez-vous également au Guide spécifique au stockage pour plus d’informations sur la configuration de l’environnement de test pour les bibliothèques de stockage.

Impressions