Quickstart: Manage blobs with JavaScript v12 SDK in Node.js
In this quickstart, you learn to manage blobs by using Node.js. Blobs are objects that can hold large amounts of text or binary data, including images, documents, streaming media, and archive data.
These example code snippets show you how to perform the following with the Azure Blob storage package library for JavaScript:
- Get the connection string
- Create a container
- Upload blobs to a container
- List the blobs in a container
- Download blobs
- Delete a container
Additional resources:
API reference | Library source code | Package (npm) | Samples
Prerequisites
- An Azure account with an active subscription. Create an account for free.
- An Azure Storage account. Create a storage account.
- Node.js LTS.
- Microsoft Visual Studio Code
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.
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.
Create the Node.js project
Create a JavaScript application named blob-quickstart-v12.
In a console window (such as cmd, PowerShell, or Bash), create a new directory for the project.
mkdir blob-quickstart-v12
Switch to the newly created blob-quickstart-v12 directory.
cd blob-quickstart-v12
Create a package.json.
npm init -y
Open the project in Visual Studio Code:
code .
Install the npm package for blob storage
Install the Azure Storage npm package:
npm install @azure/storage-blob
Install other dependencies used in this quickstart:
npm install uuid dotenv
Create JavaScript file
From the project directory:
Create a new file named
index.js
.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() { console.log('Azure Blob storage v12 - JavaScript quickstart sample'); // Quick start code goes here } main() .then(() => console.log('Done')) .catch((ex) => console.log(ex.message));
Copy your credentials from the Azure portal
When the sample application makes a request to Azure Storage, it must be authorized. To authorize a request, add your storage account credentials to the application as a connection string. To view your storage account credentials, follow these steps:
Sign in to the Azure portal.
Locate your storage account.
In the storage account menu pane, under Security + networking, select Access keys. Here, you can view the account access keys and the complete connection string for each key.
In the Access keys pane, select Show keys.
In the key1 section, locate the Connection string value. Select the Copy to clipboard icon to copy the connection string. You'll add the connection string value to an environment variable in the next section.
Configure your storage connection string
After you copy the connection string, write it to a new environment variable on the local machine running the application. To set the environment variable, open a console window, and follow the instructions for your operating system. Replace <yourconnectionstring>
with your actual connection string.
setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"
After you add the environment variable in Windows, you must start a new instance of the command window.
Restart programs
After you add the environment variable, restart any running programs that will need to read the environment variable. For example, restart your development environment or editor before you continue.
Get the connection string
The code below retrieves the connection string for the storage account from the environment variable created in the Configure your storage connection string section.
Add this code inside the main
function:
const AZURE_STORAGE_CONNECTION_STRING =
process.env.AZURE_STORAGE_CONNECTION_STRING;
if (!AZURE_STORAGE_CONNECTION_STRING) {
throw Error("Azure Storage Connection string not found");
}
Create a container
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.
Add this code to the end of the
main
function:// Create the BlobServiceClient object which will be used to create a container client const blobServiceClient = BlobServiceClient.fromConnectionString( AZURE_STORAGE_CONNECTION_STRING ); // 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. requestId: ", createContainerResponse.requestId );
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);
console.log("\nUploading to Azure storage as blob:\n\t", blobName);
// 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()) {
console.log("\t", blob.name);
}
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
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.
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
From a Visual Studio Code terminal, run the app.
node index.js
The output of the app is similar to the following example:
Azure Blob storage v12 - 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.
Use the storage emulator
This quickstart created a container and blob on the Azure cloud. You can also use the Azure Blob storage npm package to create these resources locally on the Azure Storage emulator for development and testing.
Clean up
- When you're done with this quickstart, delete the
blob-quickstart-v12
directory. - 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.
For tutorials, samples, quickstarts, and other documentation, visit:
- To learn how to deploy a web app that uses Azure Blob storage, see Tutorial: Upload image data in the cloud with Azure Storage
- To see Blob storage sample apps, continue to Azure Blob storage package library v12 JavaScript samples.
- To learn more, see the Azure Blob storage client library for JavaScript.
Feedback
Submit and view feedback for