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

• Master
• Dev

This project provides a Node.js package and a browser compatible JavaScript Client Library that makes it easy to consume and manage Microsoft Azure Storage Services.

This README page is a reference to the SDK v2. For the new SDK v10, go to Storage SDK v10 for JavaScript.

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:

• Microsoft official API document on docs.microsoft.com
• Generated API references on GitHub pages

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