What is @azure/storage-blob?
The @azure/storage-blob npm package is designed for working with Azure Blob Storage. It provides a comprehensive set of features to interact with Azure Blob Storage, including uploading and downloading blobs, managing containers, and handling blob metadata and properties. This package is part of the Azure SDK for JavaScript.
What are @azure/storage-blob's main functionalities?
Uploading blobs
This code sample demonstrates how to upload data to a blob in Azure Blob Storage. It involves creating a BlobServiceClient, getting a reference to a container, and then uploading data to a blob within that container.
const { BlobServiceClient } = require('@azure/storage-blob');
const blobServiceClient = BlobServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING);
const containerClient = blobServiceClient.getContainerClient('my-container');
const blockBlobClient = containerClient.getBlockBlobClient('my-blob');
await blockBlobClient.upload(data, data.length);
Downloading blobs
This code sample shows how to download the content of a blob. It involves creating a BlobServiceClient, getting a container client, and then downloading the blob's content using the block blob client.
const { BlobServiceClient } = require('@azure/storage-blob');
const blobServiceClient = BlobServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING);
const containerClient = blobServiceClient.getContainerClient('my-container');
const blockBlobClient = containerClient.getBlockBlobClient('my-blob');
const downloadBlockBlobResponse = await blockBlobClient.download(0);
const downloadedContent = await streamToString(downloadBlockBlobResponse.readableStreamBody);
Listing blobs in a container
This example demonstrates how to list all blobs in a specific container. It involves creating a BlobServiceClient, obtaining a container client, and iterating over the blobs in the container, printing out their names.
const { BlobServiceClient } = require('@azure/storage-blob');
const blobServiceClient = BlobServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING);
const containerClient = blobServiceClient.getContainerClient('my-container');
for await (const blob of containerClient.listBlobsFlat()) {
console.log(`Blob name: ${blob.name}`);
}
Other packages similar to @azure/storage-blob
aws-sdk
The AWS SDK for JavaScript allows developers to interact with AWS services, including Amazon S3 for object storage, which is similar to Azure Blob Storage. Compared to @azure/storage-blob, aws-sdk supports a broader range of AWS services but is specific to AWS infrastructure.
Azure Storage SDK V10 for JavaScript - Blob
Introduction
This project provides a SDK in JavaScript that makes it easy to consume Microsoft Azure Storage services.
Please note that this version of the SDK is a compete overhaul of the current Azure Storage SDK for Node.js and JavaScript in Browsers, and is based on the new Storage SDK architecture.
Features
- Blob Storage
- Get/Set Blob Service Properties
- Create/List/Delete Containers
- Create/Read/List/Update/Delete Block Blobs
- Create/Read/List/Update/Delete Page Blobs
- Create/Read/List/Update/Delete Append Blobs
- Features new
- Asynchronous I/O for all operations using the async methods
- HttpPipeline which enables a high degree of per-request configurability
- 1-to-1 correlation with the Storage REST API for clarity and simplicity
Compatibility
This SDK is compatible with Node.js and browsers, and validated against LTS Node.js versions (>=6.5) and latest versions of Chrome, Firefox and Edge.
Compatible with IE11
You need polyfills to make this library work with IE11. The easiest way is to use @babel/polyfill, or polyfill service.
Or you can load separate polyfills for missed ES feature(s).
This library depends on following ES6 features which need external polyfills loaded.
Promise
String.prototype.startsWith
String.prototype.endsWith
String.prototype.repeat
String.prototype.includes
Differences between Node.js and browsers
There are differences between Node.js and browsers runtime. When getting start with this SDK, pay attention to APIs or classes marked with "ONLY AVAILABLE IN NODE.JS RUNTIME" or "ONLY AVAILABLE IN BROWSERS".
Following features, interfaces, classes or functions are only available in Node.js
- Shared Key Authorization based on account name and account key
- Shared Access Signature(SAS) generation
generateAccountSASQueryParameters()
generateBlobSASQueryParameters()
- Parallel uploading and downloading
uploadFileToBlockBlob()
uploadStreamToBlockBlob()
downloadBlobToBuffer()
Following features, interfaces, classes or functions are only available in browsers
- Parallel uploading and downloading
uploadBrowserDataToBlockBlob()
Getting Started
NPM
The preferred way to install the Azure Storage SDK for JavaScript is to use the npm package manager. Simply type the following into a terminal window:
npm install @azure/storage-blob
In your TypeScript or JavaScript file, import via following:
import * as Azure from "@azure/storage-blob";
Or
const Azure = require("@azure/storage-blob");
JavaScript Bundle
To use the SDK with JS bundle in the browsers, simply add a script tag to your HTML pages pointing to the downloaded JS bundle file(s):
<script src="https://mydomain/azure-storage.blob.min.js"></script>
The JS bundled file is compatible with UMD standard, if no module system found, following global variable(s) will be exported:
Download
Download latest released JS bundles from links in the GitHub release page. Or from following links directly:
CORS
You need to set up Cross-Origin Resource Sharing (CORS) rules for your storage account if you need to develop for browsers. Go to Azure portal and Azure Storage Explorer, find your storage account, create new CORS rules for blob/queue/file/table service(s).
For example, you can create following CORS settings for debugging. But please customize the settings carefully according to your requirements in production environment.
- Allowed origins: *
- Allowed verbs: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
- Allowed headers: *
- Exposed headers: *
- Maximum age (seconds): 86400
SDK Architecture
The Azure Storage SDK for JavaScript provides low-level and high-level APIs.
-
ServiceURL, ContainerURL and BlobURL objects provide the low-level API functionality and map one-to-one to the Azure Storage Blob REST APIs.
-
The high-level APIs provide convenience abstractions such as uploading a large stream to a block blob (using multiple PutBlock requests).
Code Samples
const {
Aborter,
BlobURL,
BlockBlobURL,
ContainerURL,
ServiceURL,
StorageURL,
SharedKeyCredential,
AnonymousCredential,
TokenCredential
} = require("@azure/storage-blob");
async function main() {
const account = "account";
const accountKey = "accountkey";
const sharedKeyCredential = new SharedKeyCredential(account, accountKey);
const tokenCredential = new TokenCredential("token");
tokenCredential.token = "renewedToken";
const anonymousCredential = new AnonymousCredential();
const pipeline = StorageURL.newPipeline(sharedKeyCredential);
const serviceURL = new ServiceURL(
`https://${account}.blob.core.windows.net`,
pipeline
);
let marker;
do {
const listContainersResponse = await serviceURL.listContainersSegment(
Aborter.none,
marker
);
marker = listContainersResponse.nextMarker;
for (const container of listContainersResponse.containerItems) {
console.log(`Container: ${container.name}`);
}
} while (marker);
const containerName = `newcontainer${new Date().getTime()}`;
const containerURL = ContainerURL.fromServiceURL(serviceURL, containerName);
const createContainerResponse = await containerURL.create(Aborter.none);
console.log(
`Create container ${containerName} successfully`,
createContainerResponse.requestId
);
const content = "hello";
const blobName = "newblob" + new Date().getTime();
const blobURL = BlobURL.fromContainerURL(containerURL, blobName);
const blockBlobURL = BlockBlobURL.fromBlobURL(blobURL);
const uploadBlobResponse = await blockBlobURL.upload(
Aborter.none,
content,
content.length
);
console.log(
`Upload block blob ${blobName} successfully`,
uploadBlobResponse.requestId
);
marker = undefined;
do {
const listBlobsResponse = await containerURL.listBlobFlatSegment(
Aborter.none,
marker
);
marker = listBlobsResponse.nextMarker;
for (const blob of listBlobsResponse.segment.blobItems) {
console.log(`Blob: ${blob.name}`);
}
} while (marker);
const downloadBlockBlobResponse = await blobURL.download(Aborter.none, 0);
console.log(
"Downloaded blob content",
await streamToString(downloadBlockBlobResponse.readableStreamBody)
);
await containerURL.delete(Aborter.none);
console.log("deleted container");
}
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);
});
}
main()
.then(() => {
console.log("Successfully executed sample.");
})
.catch(err => {
console.log(err.message);
});
More Code Samples
License
This project is licensed under MIT.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.
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.