This project provides a Node.js package that makes it easy to consume and manage Microsoft Azure Storage Services.
If you are looking for the Node.js SDK for other Azure services, visit https://github.com/Azure/azure-sdk-for-node.
- Tables
- Create/Delete Tables
- Query/Create/Read/Update/Delete Entities
- Blobs
- Create/Delete Containers
- Create/Read/Update/Delete Blobs
- 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.
npm install azure-storage
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);
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:
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
}
});
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
}
});
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);
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
}
});
}
});
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 = true, share was created.
// if result = 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
}
});
There are other methods for uploading files also, such as createFileFromText or createFileFromStream.
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
}
});
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
}
});
}
});
How-Tos focused around accomplishing specific tasks are available on the Microsoft Azure Node.js Developer Center.
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 variables for storage account credentials by
set AZURE_STORAGE_CONNECTION_STRING="valid storage connection string"
or
set AZURE_STORAGE_ACCOUNT="valid storage account name"
set AZURE_STORAGE_ACCESS_KEY="valid storage account key"
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.
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.
Be sure to check out the Microsoft Azure Developer Forums on MSDN if you have trouble with the provided code or use StackOverflow.
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 [email protected] with any additional questions or comments.
For general suggestions about Microsoft Azure please use our UserVoice forum.