Quickstart: Manage blobs with JavaScript v12 SDK in Node.js

In this quickstart, you learn to manage blobs by using Node.js. Blobs are objects that can hold large amounts of text or binary data, including images, documents, streaming media, and archive data. You'll upload, download, and list blobs, and you'll create and delete containers.

Additional resources:

• API reference documentation
• Library source code
• Package (Node Package Manager)
• Samples

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• An Azure Storage account. Create a storage account.
• Node.js.

Setting up

This section walks you through preparing a project to work with the Azure Blob storage client library v12 for JavaScript.

Create the project

Create a JavaScript application named blob-quickstart-v12.

1. In a console window (such as cmd, PowerShell, or Bash), create a new directory for the project.

   mkdir blob-quickstart-v12
   

2. Switch to the newly created blob-quickstart-v12 directory.

   cd blob-quickstart-v12
   

3. Create a new text file called package.json. This file defines the Node.js project. Save this file in the blob-quickstart-v12 directory. Here is the contents of the file:

   {
       "name": "blob-quickstart-v12",
       "version": "1.0.0",
       "description": "Use the @azure/storage-blob SDK version 12 to interact with Azure Blob storage",
       "main": "blob-quickstart-v12.js",
       "scripts": {
           "start": "node blob-quickstart-v12.js"
       },
       "author": "Your Name",
       "license": "MIT",
       "dependencies": {
           "@azure/storage-blob": "^12.0.0",
           "@types/dotenv": "^4.0.3",
           "dotenv": "^6.0.0"
       }
   }
   

   You can put your own name in for the author field, if you'd like.

Install the package

While still in the blob-quickstart-v12 directory, install the Azure Blob storage client library for JavaScript package by using the npm install command. This command reads the package.json file and installs the Azure Blob storage client library v12 for JavaScript package and all the libraries on which it depends.

npm install

Set up the app framework

From the project directory:

1. Open another new text file in your code editor

2. Add require calls to load Azure and Node.js modules

3. Create the structure for the program, including basic exception handling

   Here's the code:

   const { BlobServiceClient } = require('@azure/storage-blob');
   const { v1: uuidv1} = require('uuid');
   
   async function main() {
       console.log('Azure Blob storage v12 - JavaScript quickstart sample');
       // Quick start code goes here
   }
   
   main().then(() => console.log('Done')).catch((ex) => console.log(ex.message));
   

4. Save the new file as blob-quickstart-v12.js in the blob-quickstart-v12 directory.

Copy your credentials from the Azure portal

When the sample application makes a request to Azure Storage, it must be authorized. To authorize a request, add your storage account credentials to the application as a connection string. To view your storage account credentials, follow these steps:

1. Sign in to the Azure portal.

2. Locate your storage account.

3. In the storage account menu pane, under Security + networking, select Access keys. Here, you can view the account access keys and the complete connection string for each key.

   

4. In the Access keys pane, select Show keys.

5. In the key1 section, locate the Connection string value. Select the Copy to clipboard icon to copy the connection string. You will add the connection string value to an environment variable in the next section.

   

Configure your storage connection string

After you copy the connection string, write it to a new environment variable on the local machine running the application. To set the environment variable, open a console window, and follow the instructions for your operating system. Replace <yourconnectionstring> with your actual connection string.

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

After you add the environment variable in Windows, you must start a new instance of the command window.

Linux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Restart programs

After you add the environment variable, restart any running programs that will need to read the environment variable. For example, restart your development environment or editor before you continue.

Object model

Azure 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. Blob storage offers three types of resources:

• The storage account
• A container in the storage account
• A blob in the container

The following diagram shows the relationship between these resources.

Use the following JavaScript classes to interact with these resources:

• BlobServiceClient: The BlobServiceClient class allows you to manipulate Azure Storage resources and blob containers.
• ContainerClient: The ContainerClient class allows you to manipulate Azure Storage containers and their blobs.
• BlobClient: The BlobClient class allows you to manipulate Azure Storage blobs.

Code examples

These example code snippets show you how to perform the following with the Azure Blob storage client library for JavaScript:

• Get the connection string
• Create a container
• Upload blobs to a container
• List the blobs in a container
• Download blobs
• Delete a container

Get the connection string

The code below retrieves the connection string for the storage account from the environment variable created in the Configure your storage connection string section.

Add this code inside the main function:

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable on the machine
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the
// environment variable is created after the application is launched in a
// console or with Visual Studio, the shell or application needs to be closed
// and reloaded to take the environment variable into account.
const AZURE_STORAGE_CONNECTION_STRING = process.env.AZURE_STORAGE_CONNECTION_STRING;

Create a container

Decide on a name for the new container. The code below appends a UUID value to the container name to ensure that it is unique.

Create an instance of the BlobServiceClient class by calling the fromConnectionString method. Then, call the getContainerClient method to get a reference to a container. Finally, call create to actually create the container in your storage account.

Add this code to the end of the main function:

// Create the BlobServiceClient object which will be used to create a container client
const blobServiceClient = BlobServiceClient.fromConnectionString(AZURE_STORAGE_CONNECTION_STRING);

// Create a unique name for the container
const containerName = 'quickstart' + uuidv1();

console.log('\nCreating container...');
console.log('\t', containerName);

// Get a reference to a container
const containerClient = blobServiceClient.getContainerClient(containerName);

// Create the container
const createContainerResponse = await containerClient.create();
console.log("Container was created successfully. requestId: ", createContainerResponse.requestId);

Upload blobs to a container

The following code snippet:

1. Creates a text string to upload to a blob.
2. Gets a reference to a BlockBlobClient object by calling the getBlockBlobClient method on the ContainerClient from the Create a container section.
3. Uploads the text string data to the blob by calling the upload method.

Add this code to the end of the main function:

// Create a unique name for the blob
const blobName = 'quickstart' + uuidv1() + '.txt';

// Get a block blob client
const blockBlobClient = containerClient.getBlockBlobClient(blobName);

console.log('\nUploading to Azure storage as blob:\n\t', blobName);

// Upload data to the blob
const data = 'Hello, World!';
const uploadBlobResponse = await blockBlobClient.upload(data, data.length);
console.log("Blob was uploaded successfully. requestId: ", uploadBlobResponse.requestId);

List the blobs in a container

List the blobs in the container by calling the listBlobsFlat method. In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

Add this code to the end of the main function:

console.log('\nListing blobs...');

// List the blob(s) in the container.
for await (const blob of containerClient.listBlobsFlat()) {
    console.log('\t', blob.name);
}

Download blobs

Download the previously created blob by calling the download method. The example code includes a helper function called streamToString, which is used to read a Node.js readable stream into a string.

Add this code to the end of the main function:

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blockBlobClient.download(0);
console.log('\nDownloaded blob content...');
console.log('\t', await streamToString(downloadBlockBlobResponse.readableStreamBody));

Add this helper function after the main function:

// A helper function used to read a Node.js readable stream into a 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);
  });
}

Delete a container

The following code cleans up the resources the app created by removing the entire container using the ​delete method. You can also delete the local files, if you like.

Add this code to the end of the main function:

console.log('\nDeleting container...');

// Delete container
const deleteContainerResponse = await containerClient.delete();
console.log("Container was deleted successfully. requestId: ", deleteContainerResponse.requestId);

Run the code

This app creates a text string and uploads it to Blob storage. The example then lists the blob(s) in the container, downloads the blob, and displays the downloaded data.

From a console prompt, navigate to the directory containing the blob-quickstart-v12.js file, then execute the following node command to run the app.

node blob-quickstart-v12.js

The output of the app is similar to the following example:

Azure Blob storage v12 - JavaScript quickstart sample

Creating container...
         quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da

Uploading to Azure Storage as blob:
         quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Listing blobs...
         quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Downloaded blob content...
         Hello, World!

Deleting container...
Done

Step through the code in your debugger and check your Azure portal throughout the process. Check to see that the container is being created. You can open the blob inside the container and view the contents.

Next steps

In this quickstart, you learned how to upload, download, and list blobs using JavaScript.

For tutorials, samples, quickstarts, and other documentation, visit:

• To learn how to deploy a web app that uses Azure Blob storage, see Tutorial: Upload image data in the cloud with Azure Storage
• To see Blob storage sample apps, continue to Azure Blob storage client library v12 JavaScript samples.
• To learn more, see the Azure Blob storage client library for JavaScript.