Quickstart: Azure Blob Storage client library for Node.js

Get started with the Azure Blob Storage client library for Node.js to manage blobs and containers. Follow these steps to install the package and try out example code for basic tasks.

API reference | Library source code | Package (npm) | Samples

Prerequisites

Create the Node.js project

Create a JavaScript application named blob-quickstart.

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

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

    cd blob-quickstart
    
  3. Create a package.json.

    npm init -y
    
  4. Open the project in Visual Studio Code:

    code .
    

Install the packages

From the project directory, install the following packages using the npm install command.

  1. Install the Azure Storage npm package:

    npm install @azure/storage-blob
    
  2. Install the Azure Identity npm package for a passwordless connection:

    npm install @azure/identity
    
  3. Install other dependencies used in this quickstart:

    npm install uuid dotenv
    

Create JavaScript file

From the project directory:

  1. Create a new file named index.js.

  2. Copy the following code into the file. More code will be added as you go through this quickstart.

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

Object model

Azure Blob storage is optimized for storing massive amounts of unstructured data. Unstructured data is data that doesn't 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.

Diagram of Blob storage architecture

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 do the following tasks with the Azure Blob Storage client library for JavaScript:

Sample code is also available on GitHub.

Authenticate to Azure and authorize access to blob data

Application requests to Azure Blob Storage must be authorized. Using the DefaultAzureCredential class provided by the Azure Identity client library is the recommended approach for implementing passwordless connections to Azure services in your code, including Blob Storage.

You can also authorize requests to Azure Blob Storage by using the account access key. However, this approach should be used with caution. Developers must be diligent to never expose the access key in an unsecure location. Anyone who has the access key is able to authorize requests against the storage account, and effectively has access to all the data. DefaultAzureCredential offers improved management and security benefits over the account key to allow passwordless authentication. Both options are demonstrated in the following example.

DefaultAzureCredential supports multiple authentication methods and determines which method should be used at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code.

The order and locations in which DefaultAzureCredential looks for credentials can be found in the Azure Identity library overview.

For example, your app can authenticate using your Azure CLI sign-in credentials with when developing locally. Your app can then use a managed identity once it has been deployed to Azure. No code changes are required for this transition.

Assign roles to your Azure AD user account

When developing locally, make sure that the user account that is accessing blob data has the correct permissions. You'll need Storage Blob Data Contributor to read and write blob data. To assign yourself this role, you'll need to be assigned the User Access Administrator role, or another role that includes the Microsoft.Authorization/roleAssignments/write action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. You can learn more about the available scopes for role assignments on the scope overview page.

In this scenario, you'll assign permissions to your user account, scoped to the storage account, to follow the Principle of Least Privilege. This practice gives users only the minimum permissions needed and creates more secure production environments.

The following example will assign the Storage Blob Data Contributor role to your user account, which provides both read and write access to blob data in your storage account.

Important

In most cases it will take a minute or two for the role assignment to propagate in Azure, but in rare cases it may take up to eight minutes. If you receive authentication errors when you first run your code, wait a few moments and try again.

  1. In the Azure portal, locate your storage account using the main search bar or left navigation.

  2. On the storage account overview page, select Access control (IAM) from the left-hand menu.

  3. On the Access control (IAM) page, select the Role assignments tab.

  4. Select + Add from the top menu and then Add role assignment from the resulting drop-down menu.

    A screenshot showing how to assign a role.

  5. Use the search box to filter the results to the desired role. For this example, search for Storage Blob Data Contributor and select the matching result and then choose Next.

  6. Under Assign access to, select User, group, or service principal, and then choose + Select members.

  7. In the dialog, search for your Azure AD username (usually your user@domain email address) and then choose Select at the bottom of the dialog.

  8. Select Review + assign to go to the final page, and then Review + assign again to complete the process.

Sign in and connect your app code to Azure using DefaultAzureCredential

You can authorize access to data in your storage account using the following steps:

  1. Make sure you're authenticated with the same Azure AD account you assigned the role to on your storage account. You can authenticate via the Azure CLI, Visual Studio Code, or Azure PowerShell.

    Sign-in to Azure through the Azure CLI using the following command:

    az login
    
  2. To use DefaultAzureCredential, make sure that the @azure\identity package is installed, and the class is imported:

    const { DefaultAzureCredential } = require('@azure/identity');
    
  3. Add this code inside the try block. When the code runs on your local workstation, DefaultAzureCredential uses the developer credentials of the prioritized tool you're logged into to authenticate to Azure. Examples of these tools include Azure CLI or Visual Studio Code.

    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    if (!accountName) throw Error('Azure Storage accountName not found');
    
    const blobServiceClient = new BlobServiceClient(
      `https://${accountName}.blob.core.windows.net`,
      new DefaultAzureCredential()
    );
    
  4. Make sure to update the storage account name, AZURE_STORAGE_ACCOUNT_NAME, in the .env file or your environment's variables. The storage account name can be found on the overview page of the Azure portal.

    A screenshot showing how to find the storage account name.

    Note

    When deployed to Azure, this same code can be used to authorize requests to Azure Storage from an application running in Azure. However, you'll need to enable managed identity on your app in Azure. Then configure your storage account to allow that managed identity to connect. For detailed instructions on configuring this connection between Azure services, see the Auth from Azure-hosted apps tutorial.

Create a container

  1. Decide on a name for the new container. Container names must be lowercase.

    For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

  2. Add this code to the end of the main function:

    // 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.\n\trequestId:${createContainerResponse.requestId}\n\tURL: ${containerClient.url}`
    );
    

    The preceding code creates 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.

Upload blobs to a container

Copy the following code to the end of the main function to upload a text string to a blob:

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

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

// Display blob name and url
console.log(
  `\nUploading to Azure storage as blob\n\tname: ${blobName}:\n\tURL: ${blockBlobClient.url}`
);

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

The preceding code gets a reference to a BlockBlobClient object by calling the getBlockBlobClient method on the ContainerClient from the Create a container section. The code uploads the text string data to the blob by calling the upload method.

List the blobs in a container

Add the following code to the end of the main function to list the blobs in the container.

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

// List the blob(s) in the container.
for await (const blob of containerClient.listBlobsFlat()) {
  // Get Blob Client from name, to get the URL
  const tempBlockBlobClient = containerClient.getBlockBlobClient(blob.name);

  // Display blob name and URL
  console.log(
    `\n\tname: ${blob.name}\n\tURL: ${tempBlockBlobClient.url}\n`
  );
}

The preceding code calls the listBlobsFlat method. In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

Download blobs

  1. Add the following code to the end of the main function to download the previously created blob into the app runtime.

    // 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 streamToText(downloadBlockBlobResponse.readableStreamBody)
    );
    

    The preceding code calls the download method.

  2. Copy the following code after the main function to convert a stream back into a string.

    // Convert stream to text
    async function streamToText(readable) {
      readable.setEncoding('utf8');
      let data = '';
      for await (const chunk of readable) {
        data += chunk;
      }
      return data;
    }
    

Delete a container

Add this code to the end of the main function to delete the container and all its blobs:

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

const deleteContainerResponse = await containerClient.delete();
console.log(
  'Container was deleted successfully. requestId: ',
  deleteContainerResponse.requestId
);

The preceding 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.

Run the code

  1. From a Visual Studio Code terminal, run the app.

    node index.js
    
  2. The output of the app is similar to the following example:

    Azure Blob storage - 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.

Clean up

  1. When you're done with this quickstart, delete the blob-quickstart directory.
  2. If you're done using your Azure Storage resource, use the Azure CLI to remove the Storage resource.

Next steps

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

To see Blob storage sample apps, continue to: