Bibliothèque de client Blob Stockage Azure pour JavaScript - version 12.26.0

Article
11/20/2024

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 :

Get/Set Blob Service Properties
Créer/répertorier/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

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

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 :

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

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

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 de conteneur dans le compte de stockage utilisé via
Un d’objets blob dans un conteneur utilisé via

Exemples

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 :

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

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

const { BlobServiceClient, StorageSharedKeyCredential } = require("@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

Configuration : Référence - Autoriser l’accès aux objets blob et 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 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 - /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).

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 '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]

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 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]

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

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 une instance cliente de conteneur, puis créez une ressource de 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() fonction pour itérer les conteneurs, avec la nouvelle syntaxe 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;
  const containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

Sinon, sans 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;
  const 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 prise en charge pour la description trop 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.

Créer 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

Similaire à 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;
  const 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échargez un objet blob et convertissez-le 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();

Un exemple complet de scénarios simples est à samples/v12/typescript/src/sharedKeyAuth.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 :

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.

Impressions

Partager via

Bibliothèque de client Blob Stockage Azure pour JavaScript - version 12.26.0

Commencer

Environnements actuellement pris en charge

Conditions préalables

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 uniquement disponibles dans les navigateurs

JavaScript Bundle

CORS

Concepts clés

Exemples

Importer le package

Créer le client du service blob

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

à l’aide de la chaîne de connexion

avec `StorageSharedKeyCredential`

avec un jeton SAP

Créer un 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 conteneur

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

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

Dépannage

Étapes suivantes

Contribuant

Ressources supplémentaires

Partager via

Bibliothèque de client Blob Stockage Azure pour JavaScript - version 12.26.0

Commencer

Environnements actuellement pris en charge

Conditions préalables

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 uniquement disponibles dans les navigateurs

JavaScript Bundle

CORS

Concepts clés

Exemples

Importer le package

Créer le client du service blob

avec DefaultAzureCredential à partir du package de @azure/identity

à l’aide de la chaîne de connexion

avec StorageSharedKeyCredential

avec un jeton SAP

Créer un 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 conteneur

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

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

Dépannage

Étapes suivantes

Contribuant

Ressources supplémentaires

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

avec `StorageSharedKeyCredential`