Bibliothèque cliente d’objets blob stockage Azure pour JavaScript - version 12.18.0

Article
05/15/2024

Stockage Blob Azure est la solution de stockage d’objets de Microsoft pour le cloud. Stockage Blob est optimisé pour le stockage d’immenses quantités de données non structurées. Les données non structurées sont des données qui n’obéissent pas à un modèle ou une définition de données en particulier, comme des données texte ou binaires.

Ce projet fournit une bibliothèque cliente en JavaScript qui facilite l’utilisation Stockage Microsoft Azure service Blob.

Utilisez les bibliothèques clientes de ce package pour :

Obtenir/définir les propriétés du service Blob
Create/Lister/Supprimer des conteneurs
Create/Read/List/Update/Delete Block Blobs
Create/Read/List/Update/Delete Page Blobs
Create/Read/List/Update/Delete Append Blobs

Liens clés

Prise en main

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 politique de support .

Prérequis

Un abonnement Azure
Un compte de stockage

Installer le package

La meilleure façon d’installer la bibliothèque cliente d’objets blob stockage Azure pour JavaScript consiste à utiliser le gestionnaire de package npm. Tapez ce qui suit dans une fenêtre de terminal :

npm install @azure/storage-blob

Authentifier le client

Stockage Azure prend en charge plusieurs façons de s’authentifier. Pour interagir avec le service Stockage Blob Azure, vous devez créer un instance d’un client de stockage, BlobServiceClient, ContainerClientou BlobClient par exemple. Consultez des exemples pour créer pour en savoir plus sur l’authentification BlobServiceClient .

Azure Active Directory
Clé partagée
Signatures d’accès partagé

Azure Active Directory

Le service Stockage Blob Azure prend en charge l’utilisation d’Azure Active Directory pour authentifier les demandes auprès de ses API. Le package @azure/identity fournit divers types d’informations d’identification que votre application peut utiliser à cette fin. Pour plus d’informations et des @azure/identity exemples pour vous aider à démarrer, consultez le FICHIER LISEZ-MOI.

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 globalement lorsqu’ils sont utilisés dans le navigateur, ce que les workers web ne rendent pas disponibles par défaut. Vous devez les remplir pour que cette bibliothèque fonctionne dans les workers web.

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 workers web :

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 démarrez avec cette bibliothèque, faites attention aux API ou aux classes marquées avec « UNIQUEMENT DISPONIBLE DANS NODE.JS RUNTIME » ou « UNIQUEMENT DISPONIBLE DANS LES NAVIGATEURS ».

Si un objet blob contient des données compressées au format ou deflate et 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 clients de stockage téléchargent l’objet blob dans son format compressé, tandis que dans les navigateurs, les données sont téléchargées au format décompressé.

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement 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é (SAP)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Chargement et téléchargement parallèles. Notez que BlockBlobClient.uploadData() est disponible dans les Node.js et les navigateurs.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement dans les navigateurs

Chargement et téléchargement parallèles
- BlockBlobClient.uploadBrowserData()

Ensemble JavaScript

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 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 de nouvelles règles CORS pour le ou les services blob/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

Le stockage Blob est conçu pour :

Mise à disposition d’images ou de documents directement dans un navigateur.
Stockage de fichiers pour un accès distribué.
Diffusion en continu de vidéo et d’audio.
Écriture dans les fichiers journaux.
Stockage de données pour la sauvegarde et la restauration, la récupération d’urgence et l’archivage.
Stockage des données pour l’analyse par un service local ou hébergé par Azure.

Le stockage Blob offre trois types de ressources :

Compte de stockage utilisé via BlobServiceClient
Un conteneur dans le compte de stockage utilisé via ContainerClient
Objet blob dans un conteneur utilisé via BlobClient

Exemples

Importation du package
Créer le client du service Blob
Create un nouveau conteneur
Répertorier les conteneurs
Create un objet blob en chargeant des données
Répertorier les objets blob à l’intérieur d’un conteneur
Télécharger un objet blob et le convertir en chaîne (Node.js)
Télécharger un objet blob et le convertir en chaîne (Navigateurs)

Importation du package

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

const AzureStorageBlob = require("@azure/storage-blob");

Vous pouvez également importer de manière sélective uniquement les types dont vous avez besoin :

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

Créer le client du service Blob

Nécessite BlobServiceClient une URL vers le service blob et des informations d’identification d’accès. Il accepte également éventuellement certains paramètres dans le options paramètre.

avec `DefaultAzureCredential` à partir du `@azure/identity` package

Méthode recommandée pour instancier un BlobServiceClient

Configuration : Référence - Autoriser l’accès aux objets blob et aux files d’attente avec Azure Active Directory à partir d’une application cliente - /azure/storage/common/storage-auth-aad-app

Inscrire une nouvelle application AAD et accorder des autorisations d’accès au Stockage Azure pour le compte de l’utilisateur connecté
- Inscrire une nouvelle application dans Azure Active Directory (dans le portail azure) - /azure/active-directory/develop/quickstart-register-app
- Dans la API permissions section, sélectionnez Add a permission et choisissez Microsoft APIs.
- Sélectionnez Azure Storage la case à cocher en regard de user_impersonation , puis cliquez sur Add permissions. Cela permettrait à l’application d’accéder au Stockage Azure pour le compte de l’utilisateur connecté.
Accorder l’accès aux données d’objets blob Azure avec RBAC dans le portail Azure
- Rôles RBAC pour les objets blob et les files d’attente - /azure/storage/common/storage-auth-aad-rbac-portal.
- Dans le portail Azure, accédez à votre compte de stockage et attribuez le rôle Contributeur aux données blob de stockage à l’application AAD inscrite à partir de Access control (IAM) l’onglet (dans la barre de navigation à gauche de votre compte de stockage dans le portail azure).
Configuration de l’environnement pour l’exemple
- Dans la page de vue d’ensemble de votre application AAD, notez les CLIENT ID et TENANT ID. Dans l’onglet « Certificats & secrets », créez un secret et notez-le.
- Assurez-vous que vous avez AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET en tant que variables d’environnement pour exécuter correctement l’exemple (Peut tirer parti de process.env).

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

Consultez l’exemple d’authentification Azure AD pour obtenir un exemple complet d’utilisation de cette méthode.

[Remarque : les étapes ci-dessus concernent uniquement Node.js]

utilisation de chaîne de connexion

Vous pouvez également instancier un à l’aide de BlobServiceClient 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.) [DISPONIBLE UNIQUEMENT DANS NODE.JS RUNTIME]

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

Avec `StorageSharedKeyCredential`

Vous pouvez également instancier un BlobServiceClient avec un StorageSharedKeyCredential en transmettant account-name et account-key comme arguments. (Le nom du compte et la clé de compte peuvent être obtenus à partir du portail Azure.) [DISPONIBLE UNIQUEMENT DANS NODE.JS RUNTIME]

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

// 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 sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential
);

avec jeton SAS

En outre, vous pouvez instancier un avec une signature d’accès BlobServiceClient partagé (SAP). Vous pouvez obtenir le jeton SAS à partir du portail Azure ou en générer un à l’aide de generateAccountSASQueryParameters().

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);

Créer un conteneur

Utilisez BlobServiceClient.getContainerClient() pour obtenir un client conteneur instance puis créer une ressource conteneur.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  // Create a container
  const containerName = `newcontainer${new Date().getTime()}`;
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse = await containerClient.create();
  console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);
}

main();

Répertorier les conteneurs

Utilisez BlobServiceClient.listContainers() la fonction pour itérer les conteneurs, avec la nouvelle for-await-of syntaxe :

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

Vous pouvez également utiliser for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let iter = blobServiceClient.listContainers();
  let containerItem = await iter.next();
  while (!containerItem.done) {
    console.log(`Container ${i++}: ${containerItem.value.name}`);
    containerItem = await iter.next();
  }
}

main();

En outre, la pagination est également prise en charge pour l’affichage via byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
    if (response.containerItems) {
      for (const container of response.containerItems) {
        console.log(`Container ${i++}: ${container.name}`);
      }
    }
  }
}

main();

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

Create un objet blob en chargeant des données

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  const content = "Hello world!";
  const blobName = "newblob" + new Date().getTime();
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);
  const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
  console.log(`Upload block blob ${blobName} successfully`, uploadBlobResponse.requestId);
}

main();

Répertorier les objets blob à l’intérieur d’un conteneur

Semblable à la liste des conteneurs.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  let i = 1;
  let blobs = containerClient.listBlobsFlat();
  for await (const blob of blobs) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

main();

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

Télécharger un objet blob et le convertir en chaîne (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [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);
    });
  }
}

main();

Téléchargez un objet blob 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 { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers 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();

Vous trouverez un exemple complet de scénarios simples dans samples/v12/typescript/src/sharedKeyAuth.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

Partager via

Bibliothèque cliente d’objets blob stockage Azure pour JavaScript - version 12.18.0

Prise en main

Environnements actuellement pris en charge

Prérequis

Installer le package

Authentifier le client

Azure Active Directory

Compatibilité

Web Workers

Différences entre les Node.js et les navigateurs

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement dans Node.js

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement dans les navigateurs

Ensemble JavaScript

CORS

Concepts clés

Exemples

Importation du package

Créer le client du service Blob

avec `DefaultAzureCredential` à partir du `@azure/identity` package

utilisation de chaîne de connexion

Avec `StorageSharedKeyCredential`

avec jeton SAS

Créer un conteneur

Répertorier les conteneurs

Create un objet blob en chargeant des données

Répertorier les objets blob à l’intérieur d’un conteneur

Télécharger un objet blob et le convertir en chaîne (Node.js)

Téléchargez un objet blob et convertissez-le en chaîne (navigateurs).

Dépannage

Étapes suivantes

Contribution

Commentaires

Ressources supplémentaires

Partager via

Bibliothèque cliente d’objets blob stockage Azure pour JavaScript - version 12.18.0

Prise en main

Environnements actuellement pris en charge

Prérequis

Installer le package

Authentifier le client

Azure Active Directory

Compatibilité

Web Workers

Différences entre les Node.js et les navigateurs

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement dans Node.js

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement dans les navigateurs

Ensemble JavaScript

CORS

Concepts clés

Exemples

Importation du package

Créer le client du service Blob

avec DefaultAzureCredential à partir du @azure/identity package

utilisation de chaîne de connexion

Avec StorageSharedKeyCredential

avec jeton SAS

Créer un conteneur

Répertorier les conteneurs

Create un objet blob en chargeant des données

Répertorier les objets blob à l’intérieur d’un conteneur

Télécharger un objet blob et le convertir en chaîne (Node.js)

Téléchargez un objet blob et convertissez-le en chaîne (navigateurs).

Dépannage

Étapes suivantes

Contribution

Commentaires

Ressources supplémentaires

avec `DefaultAzureCredential` à partir du `@azure/identity` package

Avec `StorageSharedKeyCredential`