@azure/storage-blob

What is @azure/storage-blob?

The @azure/storage-blob npm package is designed for working with Azure Blob Storage. It provides a comprehensive set of features to interact with Azure Blob Storage, including uploading and downloading blobs, managing containers, and handling blob metadata and properties. This package is part of the Azure SDK for JavaScript.

What are @azure/storage-blob's main functionalities?

Uploading blobs

This code sample demonstrates how to upload data to a blob in Azure Blob Storage. It involves creating a BlobServiceClient, getting a reference to a container, and then uploading data to a blob within that container.

const { BlobServiceClient } = require('@azure/storage-blob');
const blobServiceClient = BlobServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING);
const containerClient = blobServiceClient.getContainerClient('my-container');
const blockBlobClient = containerClient.getBlockBlobClient('my-blob');
await blockBlobClient.upload(data, data.length);

Downloading blobs

This code sample shows how to download the content of a blob. It involves creating a BlobServiceClient, getting a container client, and then downloading the blob's content using the block blob client.

const { BlobServiceClient } = require('@azure/storage-blob');
const blobServiceClient = BlobServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING);
const containerClient = blobServiceClient.getContainerClient('my-container');
const blockBlobClient = containerClient.getBlockBlobClient('my-blob');
const downloadBlockBlobResponse = await blockBlobClient.download(0);
const downloadedContent = await streamToString(downloadBlockBlobResponse.readableStreamBody);

Listing blobs in a container

This example demonstrates how to list all blobs in a specific container. It involves creating a BlobServiceClient, obtaining a container client, and iterating over the blobs in the container, printing out their names.

const { BlobServiceClient } = require('@azure/storage-blob');
const blobServiceClient = BlobServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING);
const containerClient = blobServiceClient.getContainerClient('my-container');
for await (const blob of containerClient.listBlobsFlat()) {
  console.log(`Blob name: ${blob.name}`);
}

Other packages similar to @azure/storage-blob

aws-sdk

The AWS SDK for JavaScript allows developers to interact with AWS services, including Amazon S3 for object storage, which is similar to Azure Blob Storage. Compared to @azure/storage-blob, aws-sdk supports a broader range of AWS services but is specific to AWS infrastructure.

README

Azure Storage client library for JavaScript - Blob

Azure Blob storage is Microsoft's object storage solution for the cloud. Blob storage is optimized for storing massive amounts of unstructured data. Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data.

This project provides a client library in JavaScript that makes it easy to consume Microsoft Azure Blob Storage service.

Version: 12.0.0-preview.4

• Package (npm)
• Samples
• API Reference Documentation
• Product documentation
• Source code
• Azure Storage Blob REST APIs

Key concepts

Features

• Blob Storage
  • Get/Set Blob Service Properties
  • Create/List/Delete Containers
  • Create/Read/List/Update/Delete Block Blobs
  • Create/Read/List/Update/Delete Page Blobs
  • Create/Read/List/Update/Delete Append Blobs
• Features new
  • Asynchronous I/O for all operations using the async methods
  • HttpPipeline which enables a high degree of per-request configurability
  • 1-to-1 correlation with the Storage REST API for clarity and simplicity

Compatibility

This library is compatible with Node.js and browsers, and validated against LTS Node.js versions (>=8.16.0) and latest versions of Chrome, Firefox and Edge.

Compatible with IE11

You need polyfills to make this library work with IE11. The easiest way is to use @babel/polyfill, or polyfill service.

You can also load separate polyfills for missed ES feature(s). This library depends on following ES features which need external polyfills loaded.

• Promise
• String.prototype.startsWith
• String.prototype.endsWith
• String.prototype.repeat
• String.prototype.includes
• Array.prototype.includes
• Object.keys (Override IE11's Object.keys with ES6 polyfill forcely to enable ES6 behavior)
• Symbol

Differences between Node.js and browsers

There are differences between Node.js and browsers runtime. When getting started with this library, pay attention to APIs or classes marked with "ONLY AVAILABLE IN NODE.JS RUNTIME" or "ONLY AVAILABLE IN BROWSERS".

Following features, interfaces, classes or functions are only available in Node.js

• Shared Key Authorization based on account name and account key
  • SharedKeyCredential
• Shared Access Signature(SAS) generation
  • generateAccountSASQueryParameters()
  • generateBlobSASQueryParameters()
• Parallel uploading and downloading
  • BlockBlobClient.uploadFile()
  • BlockBlobClient.uploadStream()
  • BlobClient.downloadToBuffer()
  • BlobClient.downloadToFile()

Following features, interfaces, classes or functions are only available in browsers

• Parallel uploading and downloading
  • BlockBlobClient.uploadBrowserData()

Getting started

NPM

The preferred way to install the Azure Blob Storage client library for JavaScript is to use the npm package manager. Simply type the following into a terminal window:

npm install @azure/storage-blob@12.0.0-preview.4

In your TypeScript or JavaScript file, import via following:

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

Or

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

JavaScript bundle

To use the library with JS bundle in the browsers, simply add a script tag to your HTML pages pointing to the downloaded JS bundle file(s):

<script src="https://mydomain/azure-storage-blob.min.js"></script>

The JS bundled file is compatible with UMD standard, if no module system found, following global variable(s) will be exported:

• azblob

Download

Download latest released JS bundles from links in the GitHub release page.

CORS

You need to set up Cross-Origin Resource Sharing (CORS) rules for your storage account if you need to develop for browsers. Go to Azure portal and Azure Storage Explorer, find your storage account, create new CORS rules for blob/queue/file/table service(s).

For example, you can create following CORS settings for debugging. But please customize the settings carefully according to your requirements in production environment.

• Allowed origins: *
• Allowed verbs: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Allowed headers: *
• Exposed headers: *
• Maximum age (seconds): 86400

Examples

Samples can be found at Javascript samples and Typescript samples

Below are the snippets to get started with the Azure Storage blob client library.

Import types

You can use the const Azure = require("@azure/storage-blob"); shown above then use types and functions from Azure. Or you can selectively import certain types,

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

Create the blob service client

Use the constructor to create a instance of BlobServiceClient.

• Recommended way to instantiate a BlobServiceClient - with DefaultAzureCredential from @azure/identity package

  Setup : Reference - Authorize access to blobs and queues with Azure Active Directory from a client application - https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad-app

  • Register a new AAD application and give permissions to access Azure Storage on behalf of the signed-in user

    • Register a new application in the Azure Active Directory(in the azure-portal) - https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
    • In the API permissions section, select Add a permission and choose Microsoft APIs.
    • Pick Azure Storage and select the checkbox next to user_impersonation and then click Add permissions. This would allow the application to access Azure Storage on behalf of the signed-in user.

  • Grant access to Azure Blob data with RBAC in the Azure Portal

    • RBAC roles for blobs and queues - https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad-rbac-portal.
    • In the azure portal, go to your storage-account and assign Storage Blob Data Contributor role to the registered AAD application from Access control (IAM) tab (in the left-side-navbar of your storage account in the azure-portal).

  • Environment setup for the sample

    • From the overview page of your AAD Application, note down the CLIENT ID and TENANT ID. In the "Certificates & Secrets" tab, create a secret and note that down.
    • Make sure you have AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET as environment variables to successfully execute the sample(Can leverage process.env).

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

  [Note - Above steps are only for Node.js]

• Alternatively, you instantiate a BlobServiceClient with a SharedKeyCredential by passing account-name and account-key as arguments. (account-name and account-key can be obtained from the azure portal) [ONLY AVAILABLE IN NODE.JS RUNTIME]

  // Enter your storage account name and shared key
  const account = "account";
  const accountKey = "accountkey";
  
  // Use SharedKeyCredential with storage account and account key
  // SharedKeyCredential is only avaiable in Node.js runtime, not in browsers
  const sharedKeyCredential = new SharedKeyCredential(account, accountKey);
  const blobServiceClient = new BlobServiceClient(
    `https://${account}.blob.core.windows.net`,
    sharedKeyCredential
  );
  

Create a new container

Use BlobServiceClient.getContainerClient() to get a container client instance then create a new container resource.

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

List the containers

Use BlobServiceClient.listContainers() function to iterate the containers, with the new for-await-of syntax:

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

Alternatively without using for-await-of:

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

In addition, pagination is supported for listing too via byPage():

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}`);
    }
  }
}

For a complete sample on iterating containers please see samples/iterators-containers.ts.

Create a blob by uploading data to

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

List blobs inside a container

Similar to listing containers.

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

For a complete sample on iterating blobs please see samples/iterators-blobs.ts.

Download a blob and convert it to a string (Node.js)

// 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 streamToString(downloadBlockBlobResponse.readableStreamBody);
console.log(
  "Downloaded blob content:",
  downloaded
);

// [Node.js only] A helper method used to read a Node.js readable stream into string
async function streamToString(readableStream) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    readableStream.on("data", (data) => {
      chunks.push(data.toString());
    });
    readableStream.on("end", () => {
      resolve(chunks.join(""));
    });
    readableStream.on("error", reject);
  });
}

Download a blob and convert it to a string (Browsers)

  // 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(downloadBlockBlobResponse.blobBody);
  console.log(
    "Downloaded blob content",
    downloaded
  );

// [Browsers only] A helper method used to convert a browser Blob into string.
export async function blobToString(blob: Blob): Promise<string> {
  const fileReader = new FileReader();
  return new Promise<string>((resolve, reject) => {
    fileReader.onloadend = (ev: any) => {
      resolve(ev.target!.result);
    };
    fileReader.onerror = reject;
    fileReader.readAsText(blob);
  });
}

A complete example of basic scenarios is at samples/basic.ts.

Troubleshooting

It could help diagnozing issues by turning on the console logging. Here's an example logger implementation. First, add a custom logger:

class ConsoleHttpPipelineLogger {
  constructor(minimumLogLevel) {
    this.minimumLogLevel = minimumLogLevel;
  }
  log(logLevel, message) {
    const logMessage = `${new Date().toISOString()} ${HttpPipelineLogLevel[logLevel]}: ${message}`;
    switch (logLevel) {
      case HttpPipelineLogLevel.ERROR:
        console.error(logMessage);
        break;
      case HttpPipelineLogLevel.WARNING:
        console.warn(logMessage);
        break;
      case HttpPipelineLogLevel.INFO:
        console.log(logMessage);
        break;
    }
  }
}

Then when creating the BlobServiceClient instance, pass the logger in the options

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential,
  {
    logger: new ConsoleHttpPipelineLogger(HttpPipelineLogLevel.INFO)
  }
);

Authenticating with Azure Active Directory

If you have registered an application with an Azure Active Directory tenant, you can assign it to an RBAC role in your Azure Storage account. This enables you to use the Azure.Identity library to authenticate with Azure Storage as shown in the azureAdAuth.ts sample.

Next steps

More code examples

• Blob Storage Examples
• Blob Storage Examples - Test Cases

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.