| title | titleSuffix | description | services | author | ms.author | ms.service | ms.topic | ms.date | ms.custom |
|---|---|---|---|---|---|---|---|---|---|
Get started with Azure Blob Storage and JavaScript |
Azure Storage |
Get started developing a JavaScript application that works with Azure Blob Storage. This article helps you set up a project and authorizes access to an Azure Blob Storage endpoint. |
storage |
pauljewellmsft |
pauljewell |
azure-blob-storage |
how-to |
11/30/2022 |
template-how-to, devx-track-js, devguide-js, passwordless-js |
[!INCLUDE storage-dev-guide-selector-getting-started]
This article shows you how to connect to Azure Blob Storage by using the Azure Blob Storage client library v12 for JavaScript. Once connected, your code can operate on containers, blobs, and features of the Blob Storage service.
The sample code snippets are available in GitHub as runnable Node.js files.
API reference | Package (npm) | Library source code | Samples | Give feedback
- Azure subscription - create one for free
- Azure storage account - create a storage account
- Node.js LTS
- For client (browser) applications, you need bundling tools.
-
Open a command prompt and change into your project folder. Change
YOUR-DIRECTORYto your folder name:cd YOUR-DIRECTORY -
If you don't have a
package.jsonfile already in your directory, initialize the project to create the file:npm init -y
-
Install the Azure Blob Storage client library for JavaScript:
npm install @azure/storage-blob
-
If you want to use passwordless connections using Microsoft Entra ID, install the Azure Identity client library for JavaScript:
npm install @azure/identity
Microsoft Entra ID provides the most secure connection by managing the connection identity (managed identity). This passwordless functionality allows you to develop an application that doesn't require any secrets (keys or connection strings) stored in the code.
To connect to Azure without passwords, you need to set up an Azure identity or use an existing identity. Once the identity is set up, make sure to assign the appropriate roles to the identity.
To authorize passwordless access with Microsoft Entra ID, you'll need to use an Azure credential. Which type of credential you need depends on where your application runs. Use this table as a guide.
| Environment | Method |
|---|---|
| Developer environment | Visual Studio Code |
| Developer environment | Service principal |
| Azure-hosted apps | Azure-hosted apps setup |
| On-premises | On-premises app setup |
Your storage resource needs to have one or more of the following Azure RBAC roles assigned to the identity resource you plan to connect with. Setup the Azure Storage roles for each identity you created in the previous step: Azure cloud, local development, on-premises.
After you complete the setup, each identity needs at least one of the appropriate roles:
-
A data access role - such as:
- Storage Blob Data Reader
- Storage Blob Data Contributor
-
A resource role - such as:
- Reader
- Contributor
As you build your application, your code will primarily interact with three types of resources:
- The storage account, which is the unique top-level namespace for your Azure Storage data.
- Containers, which organize the blob data in your storage account.
- Blobs, which store unstructured data like text and binary data.
The following diagram shows the relationship between these resources.
Each type of resource is represented by one or more associated JavaScript clients:
| Class | Description |
|---|---|
| BlobServiceClient | Represents the Blob Storage endpoint for your storage account. |
| ContainerClient | Allows you to manipulate Azure Storage containers and their blobs. |
| BlobClient | Allows you to manipulate Azure Storage blobs. |
The BlobServiceClient object is the top object in the SDK. This client allows you to manipulate the service, containers and blobs.
Once your Azure storage account identity roles and your local environment are set up, create a JavaScript file which includes the @azure/identity package. Create a credential, such as the DefaultAzureCredential, to implement passwordless connections to Blob Storage. Use that credential to authenticate with a BlobServiceClient object.
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/connect-with-default-azure-credential.js" highlight="9-12":::
The dotenv package is used to read your storage account name from a .env file. This file should not be checked into source control. If you use a local service principal as part of your DefaultAzureCredential set up, any security information for that credential will also go into the .env file.
If you plan to deploy the application to servers and clients that run outside of Azure, create one of the credentials that meets your needs.
Create a StorageSharedKeyCredential from the storage account name and account key. Then pass the StorageSharedKeyCredential to the BlobServiceClient class constructor to create a client.
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/connect-with-account-name-and-key.js" highlight="12-15":::
The dotenv package is used to read your storage account name and key from a .env file. This file should not be checked into source control.
For information about how to obtain account keys and best practice guidelines for properly managing and safeguarding your keys, see Manage storage account access keys.
Important
The account access key should be used with caution. If your account access key is lost or accidentally placed in an insecure location, your service may become vulnerable. Anyone who has the access key is able to authorize requests against the storage account, and effectively has access to all the data. DefaultAzureCredential provides enhanced security features and benefits and is the recommended approach for managing authorization to Azure services.
Create a Uri to your resource by using the blob service endpoint and SAS token. Then, create a BlobServiceClient with the Uri. The SAS token is a series of name/value pairs in the querystring in the format such as:
https://YOUR-RESOURCE-NAME.blob.core.windows.net?YOUR-SAS-TOKEN
Depending on which tool you use to generate your SAS token, the querystring ? may already be added to the SAS token.
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/connect-with-sas-token.js" highlight="13-16":::
The dotenv package is used to read your storage account name and SAS token from a .env file. This file should not be checked into source control.
To generate and manage SAS tokens, see any of these articles:
- Grant limited access to Azure Storage resources using shared access signatures (SAS)
- Create a service SAS for a container or blob
Note
For scenarios where shared access signatures (SAS) are used, Microsoft recommends using a user delegation SAS. A user delegation SAS is secured with Microsoft Entra credentials instead of the account key. To learn more, see Create a user delegation SAS with JavaScript.
You can create the ContainerClient object either from the BlobServiceClient, or directly.
Create the ContainerClient object from the BlobServiceClient.
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/create-container-client-with-blob-service-client.js" highlight="19-22, 28-31, 36-38":::
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/create-container-client-with-default-azure-credential.js" highlight="27-30":::
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/create-container-client-with-account-name-and-key.js" highlight="18-21, 29-32":::
Important
The account access key should be used with caution. If your account access key is lost or accidentally placed in an insecure location, your service may become vulnerable. Anyone who has the access key is able to authorize requests against the storage account, and effectively has access to all the data. DefaultAzureCredential provides enhanced security features and benefits and is the recommended approach for managing authorization to Azure services.
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/create-container-client-with-sas-token.js" highlight="19, 24":::
Note
For scenarios where shared access signatures (SAS) are used, Microsoft recommends using a user delegation SAS. A user delegation SAS is secured with Microsoft Entra credentials instead of the account key. To learn more, see Create a user delegation SAS with JavaScript.
The dotenv package is used to read your storage account name from a .env file. This file should not be checked into source control.
You can create any of the BlobClient objects, listed below, either from a ContainerClient, or directly.
List of Blob clients:
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/create-blob-client-with-container-client.js" highlight="19-22, 29-32, 38, 45":::
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/create-blob-client-with-default-azure-credential.js" highlight="28-31":::
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/create-blob-client-with-account-name-and-key.js" highlight="19-22, 34-37":::
Important
The account access key should be used with caution. If your account access key is lost or accidentally placed in an insecure location, your service may become vulnerable. Anyone who has the access key is able to authorize requests against the storage account, and effectively has access to all the data. DefaultAzureCredential provides enhanced security features and benefits and is the recommended approach for managing authorization to Azure services.
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/create-blob-client-with-sas-token.js" highlight="17, 36":::
Note
For scenarios where shared access signatures (SAS) are used, Microsoft recommends using a user delegation SAS. A user delegation SAS is secured with Microsoft Entra credentials instead of the account key. To learn more, see Create a user delegation SAS with JavaScript.
The dotenv package is used to read your storage account name from a .env file. This file should not be checked into source control.