Bibliothèque cliente Azure Storage Blob pour JavaScript - version 12.29.1

Azure Storage Blob est la solution de stockage d’objets de Microsoft pour le cloud. Le stockage d’objets blob est optimisé pour stocker des quantités massives de données non structurées. Les données non structurées sont des données qui ne respectent pas un modèle de données particulier ou une définition, telles que des données texte ou binaires.

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

Utilisez les bibliothèques clientes dans ce package pour :

Obtenir/définir les propriétés du service d’objets blob
Créer/Lister/Supprimer des conteneurs
Créer/lire/liste/mettre à jour/supprimer des objets blob de blocs
Créer/lire/liste/mettre à jour/supprimer des objets blob de pages
Créer/lire/liste/mettre à jour/supprimer des objets blob d’ajout

Liens clés

Mise en route

Environnements actuellement pris en charge

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

Consultez notre politique d’assistance pour plus de détails.

Prerequisites

Un abonnement Azure
Un compte de stockage

Installer le package

La méthode recommandée pour installer la bibliothèque de client 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 une instance d’un client de stockage , BlobServiceClient, ContainerClientou BlobClient par exemple. Consultez exemples pour créer le BlobServiceClient pour en savoir plus sur l’authentification.

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 pour ce faire. Pour plus d’informations et d’exemples, consultez le README pour @azure/identity pour commencer.

Compatibility

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.

Travailleurs du Web

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 :

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 objet blob 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 l’objet blob dans son format compressé, tandis que dans les navigateurs, les données seront téléchargées au format décompressé.

Fonctionnalités, interfaces, classes ou fonctions 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()
- 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 uniquement disponibles dans les navigateurs

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

Offre groupée JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus de détails sur la procédure à suivre, veuillez consulter notre documentation sur les offres groupées.

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

Le stockage d’objets blob est conçu pour :

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

Le stockage Blob offre trois types de ressources :

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

Examples

Importer le package
Créer le client du service blob
Créer un de conteneur
Répertorier les conteneurs
Créer un objet blob en chargeant des données
Répertorier les objets blob à l’intérieur d’un de 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)

Importer le package

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

import * as AzureStorageBlob from "@azure/storage-blob";

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

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

Créer le client du service blob

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

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

Méthode recommandée pour instancier un BlobServiceClient

Installation : Référence - Autoriser l’accès aux objets blob et aux files d’attente avec Azure Active Directory à partir d’une application cliente - https://learn.microsoft.com/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) - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- Dans la section API permissions, sélectionnez Add a permission et choisissez Microsoft APIs.
- Sélectionnez Azure Storage et cochez la case 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 Blob Azure avec RBAC dans le portail Azure
- Rôles RBAC pour les objets blob et les files d’attente - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- Dans le portail Azure, accédez à votre compte de stockage et attribuez rôle Contributeur aux données blob de stockage au rôle AAD inscrit à partir de l’onglet Access control (IAM) (dans la barre de navigation de gauche de votre compte de stockage dans le portail Azure).
Configuration de l’environnement pour l’exemple
- Dans la page vue d’ensemble de votre application AAD, notez les CLIENT ID et les TENANT ID. Sous l’onglet « Certificats & secrets », créez un secret et notez-le.
- Vérifiez 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).

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@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 'authentification Azure AD pour obtenir un exemple complet à l’aide de cette méthode.

[Remarque - Les étapes ci-dessus ne concernent que Node.js]

à l’aide de la chaîne de connexion

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

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

avec `StorageSharedKeyCredential`

Vous pouvez également instancier un BlobServiceClient avec un StorageSharedKeyCredential en passant le nom du compte et la clé de compte en tant qu’arguments. (Le nom du compte et la clé de compte peuvent être obtenus à partir du portail Azure.) [DISPONIBLE UNIQUEMENT DANS NODE.JS RUNTIME]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

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 un jeton SAP

En outre, vous pouvez instancier un BlobServiceClient 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().

import { BlobServiceClient } from "@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 une instance cliente de conteneur, puis créez une ressource de conteneur.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

Répertorier les conteneurs

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

Sinon, sans utiliser for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

En outre, la pagination est prise en charge pour la description trop via byPage():

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

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

Créer un objet blob en chargeant des données

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

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

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

Similaire à la liste des conteneurs.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

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

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

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const blobName = "<blob name>";
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();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

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

Veuillez vous référer à la section Bundle JavaScript pour plus d’informations sur l’utilisation de cette bibliothèque dans le navigateur.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const blobName = "<blob name>";
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 blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

Un exemple complet de scénarios simples se trouve à l’adresse samples/v12/typescript/src/sharedKeyAuth.ts.

Troubleshooting

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:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Étapes suivantes

Autres exemples de code :

Contributing

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.

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-10-17