azure-storage

Microsoft Azure Storage SDK for Node.js

Showing:

Popularity

Downloads/wk

141K

GitHub Stars

480

Maintenance

Last Commit

1mo ago

Contributors

58

Package

Dependencies

11

License

Apache-2.0

Type Definitions

Built-In

Tree-Shakeable

No?

Reviews

Average Rating

4.5/52
Read All Reviews
rajamcasoft
ravinderveerla

Top Feedback

2Great Documentation
2Easy to Use
1Slow

Readme

Microsoft Azure Storage SDK for Node.js and JavaScript for Browsers

NPM version Build Status Coverage Status

This project provides a Node.js package azure-storage which is browser compatible JavaScript Client Library as well to consume and manage Microsoft Azure Storage Services.

Please note, newer packages @azure/storage-blob, @azure/storage-queue and @azure/storage-file are available as of November 2019 and @azure/data-tables is available as of June 2021 for the individual services. While the legacy azure-storage package will continue to receive critical bug fixes, we strongly encourage you to upgrade.

Below are a set of links with information on both the latest and legacy packages for the different Storage services from Azure. For more, please read State of the Azure SDK 2021

PackageVersionDescriptionAPI Reference Links
@azure/storage-blobv12The next generation SDK for Azure Blob StorageAPI Reference for Blob SDK
@azure/storage-queuev12The next generation SDK for Azure Queue StorageAPI Reference for Queues SDK
@azure/storage-file-sharev12The next generation SDK for Azure FilesAPI Reference for Files SDK
@azure/data-tablesv12The next generation SDK for Azure Table StorageAPI Reference for Tables SDK
azure-storagev2Legacy Storage SDK in this repository (Blob/Queue/File/Table, callback style)API Reference for legacy Storage SDK
@azure/arm-storagev7 & aboveManagement SDKs including Storage Resource Provider APIsAPI Reference for Storage Management SDK

Features

  • Blobs
    • Create/Delete Containers
    • Create/Read/Update/Delete Blobs
  • Tables
    • Create/Delete Tables
    • Query/Create/Read/Update/Delete Entities
  • Files
    • Create/Delete Shares
    • Create/Delete Directories
    • Create/Read/Update/Delete Files
  • Queues
    • Create/Delete Queues
    • Insert/Peek Queue Messages
    • Advanced Queue Operations
  • Service Properties
    • Get Service Properties
    • Set Service Properties

Please check details on API reference documents:

Getting Started

Install

npm install azure-storage

Usage

var azure = require('azure-storage');

When using the Storage SDK, you must provide connection information for the storage account to use. This can be provided using:

  • Environment variables - AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY, or AZURE_STORAGE_CONNECTION_STRING.

  • Constructors - For example, var tableSvc = azure.createTableService(accountName, accountKey);

Blob Storage

The createContainerIfNotExists method can be used to create a container in which to store a blob:

var azure = require('azure-storage');
var blobService = azure.createBlobService();
blobService.createContainerIfNotExists('taskcontainer', {
  publicAccessLevel: 'blob'
}, function(error, result, response) {
  if (!error) {
    // if result = true, container was created.
    // if result = false, container already existed.
  }
});

To upload a file (assuming it is called task1-upload.txt and it is placed in the same folder as the script below), the method createBlockBlobFromLocalFile can be used.

var azure = require('azure-storage');
var blobService = azure.createBlobService();

blobService.createBlockBlobFromLocalFile('mycontainer', 'taskblob', 'task1-upload.txt', function(error, result, response) {
  if (!error) {
    // file uploaded
  }
});

For page blobs, use createPageBlobFromLocalFile. There are other methods for uploading blobs also, such as createBlockBlobFromText or createPageBlobFromStream.

There are also several ways to download block and page blobs. For example, getBlobToStream downloads the blob to a stream:

var blobService = azure.createBlobService();
var fs = require('fs');
blobService.getBlobToStream('mycontainer', 'taskblob', fs.createWriteStream('output.txt'), function(error, result, response) {
  if (!error) {
    // blob retrieved
  }
});

To create a Shared Access Signature (SAS), use the generateSharedAccessSignature method. Additionally you can use the date helper functions to easily create a SAS that expires at some point relative to the current time.

var azure = require('azure-storage');
var blobService = azure.createBlobService();

var startDate = new Date();
var expiryDate = new Date(startDate);
expiryDate.setMinutes(startDate.getMinutes() + 100);
startDate.setMinutes(startDate.getMinutes() - 100);

var sharedAccessPolicy = {
  AccessPolicy: {
    Permissions: azure.BlobUtilities.SharedAccessPermissions.READ,
    Start: startDate,
    Expiry: expiryDate
  }
};

var token = blobService.generateSharedAccessSignature(containerName, blobName, sharedAccessPolicy);
var sasUrl = blobService.getUrl(containerName, blobName, token);

Table Storage

To ensure a table exists, call createTableIfNotExists:

var azure = require('azure-storage');
var tableService = azure.createTableService();
tableService.createTableIfNotExists('mytable', function(error, result, response) {
  if (!error) {
    // result contains true if created; false if already exists
  }
});

A new entity can be added by calling insertEntity or insertOrReplaceEntity:

var azure = require('azure-storage');
var tableService = azure.createTableService();
var entGen = azure.TableUtilities.entityGenerator;
var entity = {
  PartitionKey: entGen.String('part2'),
  RowKey: entGen.String('row1'),
  boolValueTrue: entGen.Boolean(true),
  boolValueFalse: entGen.Boolean(false),
  intValue: entGen.Int32(42),
  dateValue: entGen.DateTime(new Date(Date.UTC(2011, 10, 25))),
  complexDateValue: entGen.DateTime(new Date(Date.UTC(2013, 02, 16, 01, 46, 20)))
};
tableService.insertEntity('mytable', entity, function(error, result, response) {
  if (!error) {
    // result contains the ETag for the new entity
  }
});

Instead of creating entities manually, you can use entityGenerator:

var azure = require('azure-storage');
var entGen = azure.TableUtilities.entityGenerator;
var task = {
  PartitionKey: entGen.String('hometasks'),
  RowKey: entGen.String('1'),
  description: entGen.String('take out the trash'),
  dueDate: entGen.DateTime(new Date(Date.UTC(2015, 6, 20)))
};

The method retrieveEntity can then be used to fetch the entity that was just inserted:

var azure = require('azure-storage');
var tableService = azure.createTableService();
tableService.retrieveEntity('mytable', 'part2', 'row1', function(error, result, response) {
  if (!error) {
    // result contains the entity
  }
});

The method replaceEntity or insertOrReplaceEntity can be called to update/edit an existing entry. In the following example we assume that an entity 'part2', 'row1' with a field 'taskDone' set to false already exists.

var azure = require('azure-storage');
var tableService = azure.createTableService();
var entity = {
  PartitionKey: entGen.String('part2'),
  RowKey: entGen.String('row1'),
  taskDone: entGen.Boolean(true),
};

tableService.insertOrReplaceEntity('mytable', entity, function(error, result, response) {
  if (!error) {
    // result contains the entity with field 'taskDone' set to `true`
  }
});

Use TableQuery to build complex queries:

var azure = require('azure-storage');
var tableService = azure.createTableService();
var query = new azure.TableQuery()
  .top(5)
  .where('PartitionKey eq ?', 'part2');

tableService.queryEntities('mytable', query, null, function(error, result, response) {
  if (!error) {
    // result.entries contains entities matching the query
  }
});

Queue Storage

The createQueueIfNotExists method can be used to ensure a queue exists:

var azure = require('azure-storage');
var queueService = azure.createQueueService();
queueService.createQueueIfNotExists('taskqueue', function(error) {
  if (!error) {
    // Queue exists
  }
});

The createMessage method can then be called to insert the message into the queue:

var queueService = azure.createQueueService();
queueService.createMessage('taskqueue', 'Hello world!', function(error) {
  if (!error) {
    // Message inserted
  }
});

It is then possible to call the getMessage method, process the message and then call deleteMessage inside the callback. This two-step process ensures messages don't get lost when they are removed from the queue.

var queueService = azure.createQueueService(),
  queueName = 'taskqueue';
queueService.getMessages(queueName, function(error, serverMessages) {
  if (!error) {
    // Process the message in less than 30 seconds, the message
    // text is available in serverMessages[0].messageText

    queueService.deleteMessage(queueName, serverMessages[0].messageId, serverMessages[0].popReceipt, function(error) {
      if (!error) {
        // Message deleted
      }
    });
  }
});

File Storage

The createShareIfNotExists method can be used to create a share in which to store a file or a directory of files:

var azure = require('azure-storage');
var fileService = azure.createFileService();
fileService.createShareIfNotExists('taskshare', function(error, result, response) {
  if (!error) {
    // if result = true, share was created.
    // if result = false, share already existed.
  }
});

To create a directory, the method createDirectoryIfNotExists can be used.

var azure = require('azure-storage');
var fileService = azure.createFileService();

fileService.createDirectoryIfNotExists('taskshare', 'taskdirectory', function(error, result, response) {
  if (!error) {
    // if result.created = true, share was created.
    // if result.created = false, share already existed.
  }
});

To upload a file (assuming it is called task1-upload.txt and it is placed in the same folder as the script below), the method createFileFromLocalFile can be used.

var azure = require('azure-storage');
var fileService = azure.createFileService();

fileService.createFileFromLocalFile('taskshare', 'taskdirectory', 'taskfile', 'task1-upload.txt', function(error, result, response) {
  if (!error) {
    // file uploaded
  }
});

To upload a file from a stream, the method createFileFromStream can be used. The var myFileBuffer in the script below is a native Node Buffer, or ArrayBuffer object if within a browser environment.

 var stream = require('stream');
 var azure = require('azure-storage');
 var fileService = azure.createFileService();

 var fileStream = new stream.Readable();
 fileStream.push(myFileBuffer);
 fileStream.push(null);

 fileService.createFileFromStream('taskshare', 'taskdirectory', 'taskfile', fileStream, myFileBuffer.length, function(error, result, response) {
   if (!error) {
     // file uploaded
   }
 });

To create a file from a text string, the method createFileFromText can be used. A Node Buffer or ArrayBuffer object containing the text can also be supplied.

 var azure = require('azure-storage');
 var fileService = azure.createFileService();

 var text = 'Hello World!';

 fileService.createFileFromText('taskshare', 'taskdirectory', 'taskfile', text, function(error, result, response) {
   if (!error) {
     // file created
   }
 });

There are also several ways to download files. For example, getFileToStream downloads the file to a stream:

var fileService = azure.createFileService();
var fs = require('fs');
fileService.getFileToStream('taskshare', 'taskdirectory', 'taskfile', fs.createWriteStream('output.txt'), function(error, result, response) {
  if (!error) {
    // file retrieved
  }
});

Service Properties

The getServiceProperties method can be used to fetch the logging, metrics and CORS settings on your storage account:

var azure = require('azure-storage');
var blobService = azure.createBlobService();

blobService.getServiceProperties(function(error, result, response) {  
  if (!error) {
     var serviceProperties = result;
     // properties are fetched
  } 
});  

The setServiceProperties method can be used to modify the logging, metrics and CORS settings on your storage account:

var azure = require('azure-storage');
var blobService = azure.createBlobService();

var serviceProperties = generateServiceProperties(); 

blobService.setServiceProperties(serviceProperties, function(error, result, response) {  
  if (!error) {
    // properties are set
  }
});  

function generateServiceProperties() {
  return serviceProperties = {
    Logging: {
      Version: '1.0',
      Delete: true,
      Read: true,
      Write: true,
      RetentionPolicy: {
        Enabled: true,
        Days: 10,
      },
    },
    HourMetrics: {
      Version: '1.0',
      Enabled: true,
      IncludeAPIs: true,
      RetentionPolicy: {
        Enabled: true,
        Days: 10,
      },
    },
    MinuteMetrics: {
      Version: '1.0',
      Enabled: true,
      IncludeAPIs: true,
      RetentionPolicy: {
        Enabled: true,
        Days: 10,
      },
    },
    Cors: {
      CorsRule: [
        {
          AllowedOrigins: ['www.azure.com', 'www.microsoft.com'],
          AllowedMethods: ['GET', 'PUT'],
          AllowedHeaders: ['x-ms-meta-data*', 'x-ms-meta-target*', 'x-ms-meta-xyz', 'x-ms-meta-foo'],
          ExposedHeaders: ['x-ms-meta-data*', 'x-ms-meta-source*', 'x-ms-meta-abc', 'x-ms-meta-bcd'],
          MaxAgeInSeconds: 500,
        },
        {
          AllowedOrigins: ['www.msdn.com', 'www.asp.com'],
          AllowedMethods: ['GET', 'PUT'],
          AllowedHeaders: ['x-ms-meta-data*', 'x-ms-meta-target*', 'x-ms-meta-xyz', 'x-ms-meta-foo'],
          ExposedHeaders: ['x-ms-meta-data*', 'x-ms-meta-source*', 'x-ms-meta-abc', 'x-ms-meta-bcd'],
          MaxAgeInSeconds: 500,
        },
      ],
    },
  };
}

When modifying the service properties, you can fetch the properties and then modify the them to prevent overwriting the existing settings.

var azure = require('azure-storage');
var blobService = azure.createBlobService();

blobService.getServiceProperties(function(error, result, response) {  
  if (!error) {
    var serviceProperties = result;
     
    // modify the properties

    blobService.setServiceProperties(serviceProperties, function(error, result, response) {  
      if (!error) {
        // properties are set
      }
    });
  } 
});

Retry Policies

By default, no retry will be performed with service instances newly created by Azure storage client library for Node.js. Two pre-written retry polices ExponentialRetryPolicyFilter and LinearRetryPolicyFilter are available with modifiable settings, and can be used through associating filter. Any custom retry logic may be used by customizing RetryPolicyFilter instance.

For how to use pre-written retry policies and how to define customized retry policy, please refer to retrypolicysample in samples directory.

Code Samples

How-Tos focused around accomplishing specific tasks are available on the Microsoft Azure Node.js Developer Center.

Running Tests

Unit tests can then be run from the module's root directory using:

npm test

Running test is also supported by Grunt by:

grunt # mochaTest as the default task

By default the unit tests are ran with Nock recording data. To run tests against real storage account, please set environment variable to turn off Nock by:

set NOCK_OFF=true

and set up the following environment variable for storage account credentials by

set AZURE_STORAGE_CONNECTION_STRING="valid storage connection string"

To record the data in a test pass against real storage account for future Nock usage:

set AZURE_NOCK_RECORD=true

In order to be able to use a proxy like fiddler, an additional environment variable should be set up:

set NODE_TLS_REJECT_UNAUTHORIZED=0
set HTTP_PROXY=http://127.0.0.1:8888

On Linux, please use export other than set to set the variables.

Azure Storage JavaScript Client Library for Browsers

Azure Storage Node.js Client Library is compatible with Browserify. This means you can bundle your Node.js application which depends on the Node.js Client Library using Browserify.

You can also choose to download the JavaScript Client Library provided by us, or generate the library by yourself. Please refer to the README.md under browser folder for detailed usage guidelines.

Downloading Azure Storage JavaScript Client Library

It's recommended to use the Azure Storage JavaScript Client Library provided by us. Please download the latest library.

Generating Azure Storage JavaScript Client Library

We also provide browserify bundle scripts which generate Azure Storage JavaScript Client Library. The bundle script reduces the size of the Storage Client Library by splitting into smaller files, one per storage service. For more detailed information, refer to README.md under browser folder.

JsDoc

JsDoc can be generated by grunt jsdoc.

To load the docs by devserver after generation, run grunt doc and then browse the docs at http://localhost:8888.

Need Help?

Be sure to check out the Microsoft Azure Developer Forums on MSDN if you have trouble with the provided code or use StackOverflow.

Learn More

Contribute

We gladly accept community contributions.

  • Issues: Please report bugs using the Issues section of GitHub
  • Forums: Interact with the development teams on StackOverflow or the Microsoft Azure Forums
  • Source Code Contributions: If you would like to become an active contributor to this project please follow the instructions provided in Contributing.md.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

For general suggestions about Microsoft Azure please use our UserVoice forum.

Rate & Review

Great Documentation2
Easy to Use2
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow1
Buggy0
Abandoned0
Unwelcoming Community0
100
rajamcasoftIndia43 Ratings45 Reviews
8 months ago
Easy to Use
Great Documentation

Package released by Microsoft for for their own product. It is a flawless package used to handle the storage file content as a blob and other service. I am using this for read and write images and files in t blob storage container. Using this as base service we can generate the vanishing url for our images used i our websites. So that users won't copy the files. Fast and secure.


0
Ravinder62 Ratings45 Reviews
Exploring the new technologies and frameworks
7 months ago
Great Documentation
Easy to Use
Slow

we are extensively using the azure storage in our cloud projects where we can connect to the azure storage blob in order to store the generated reports and we also connect to azure storage tables using this library in order to store and retrieve the repots meta data information. don't know some times we feel this library taking more time than expected.


0

Tutorials

No tutorials found
Add a tutorial