Upload a blob with TypeScript
This article shows how to upload a blob using the Azure Storage client library for JavaScript. You can upload data to a block blob from a file path, a stream, a buffer, or a text string. You can also upload blobs with index tags.
Prerequisites
- The examples in this article assume you already have a project set up to work with the Azure Blob Storage client library for JavaScript. To learn about setting up your project, including package installation, importing modules, and creating an authorized client object to work with data resources, see Get started with Azure Blob Storage and TypeScript.
- The authorization mechanism must have permissions to perform an upload operation. To learn more, see the authorization guidance for the following REST API operations:
Upload data to a block blob
You can use any of the following methods to upload data to a block blob:
- upload (non-parallel uploading method)
- uploadData
- uploadFile (only available in Node.js runtime)
- uploadStream (only available in Node.js runtime)
Each of these methods can be called using a BlockBlobClient object.
Upload a block blob from a file path
The following example uploads a block blob from a local file path:
async function uploadBlobFromLocalPath(
containerClient: ContainerClient,
blobName: string,
localFilePath: string
): Promise<void> {
// Create blob client from container client
const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);
await blockBlobClient.uploadFile(localFilePath);
}
Upload a block blob from a stream
The following example uploads a block blob by creating a readable stream and uploading the stream:
async function uploadBlobFromReadStream(
containerClient: ContainerClient,
blobName: string,
readStream: fs.ReadStream
): Promise<void> {
// Create blob client from container client
const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);
await blockBlobClient.uploadStream(readStream);
}
Upload a block blob from a buffer
The following example uploads a block blob from a Node.js buffer:
async function uploadBlobFromBuffer(
containerClient: ContainerClient, blobName: string, buffer: Buffer
): Promise<void> {
// Create blob client from container client
const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);
// Upload buffer
await blockBlobClient.uploadData(buffer);
}
Upload a block blob from a string
The following example uploads a block blob from a string:
async function uploadBlobFromString(
containerClient: ContainerClient,
blobName: string,
fileContents: string
): Promise<void> {
// Create blob client from container client
const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);
await blockBlobClient.upload(fileContents, fileContents.length);
}
Upload a block blob with configuration options
You can define client library configuration options when uploading a blob. These options can be tuned to improve performance, enhance reliability, and optimize costs. The code examples in this section show how to set configuration options using the BlockBlobParallelUploadOptions interface, and how to pass those options as a parameter to an upload method call.
Specify data transfer options on upload
You can configure properties in BlockBlobParallelUploadOptions to improve performance for data transfer operations. The following table lists the properties you can configure, along with a description:
Property | Description |
---|---|
blockSize |
The maximum block size to transfer for each request as part of an upload operation. |
concurrency |
The maximum number of parallel requests that are issued at any given time as a part of a single parallel transfer. |
maxSingleShotSize |
If the size of the data is less than or equal to this value, it's uploaded in a single put rather than broken up into chunks. If the data is uploaded in a single shot, the block size is ignored. Default value is 256 MiB. |
The following code example shows how to set values for BlockBlobParallelUploadOptions and include the options as part of an upload method call. The values provided in the samples aren't intended to be a recommendation. To properly tune these values, you need to consider the specific needs of your app.
async function uploadWithTransferOptions(
containerClient: ContainerClient,
blobName: string,
localFilePath: string
): Promise<void> {
// Specify data transfer options
const uploadOptions: BlockBlobParallelUploadOptions = {
blockSize: 4 * 1024 * 1024, // 4 MiB max block size
concurrency: 2, // maximum number of parallel transfer workers
maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
};
// Create blob client from container client
const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);
await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}
Upload a block blob with index tags
Blob index tags categorize data in your storage account using key-value tag attributes. These tags are automatically indexed and exposed as a searchable multi-dimensional index to easily find data.
The following example uploads a block blob with index tags set using BlockBlobParallelUploadOptions:
async function uploadBlobWithIndexTags(
containerClient: ContainerClient,
blobName: string,
localFilePath: string
): Promise<void> {
// Specify index tags for blob
const uploadOptions: BlockBlobParallelUploadOptions = {
tags: {
'Sealed': 'false',
'Content': 'image',
'Date': '2023-06-01',
}
};
// Create blob client from container client
const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);
await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}
Set a blob's access tier on upload
You can set a blob's access tier on upload by using the BlockBlobParallelUploadOptions interface. The following code example shows how to set the access tier when uploading a blob:
async function uploadBlobWithAccessTier(
containerClient: ContainerClient,
blobName: string,
localFilePath: string
): Promise<void> {
// Upload blob to 'Cool' access tier
const uploadOptions: BlockBlobParallelUploadOptions = {
tier: 'Cool'
};
// Create blob client from container client
const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);
await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}
Setting the access tier is only allowed for block blobs. You can set the access tier for a block blob to Hot
, Cool
, Cold
, or Archive
. To set the access tier to Cold
, you must use a minimum client library version of 12.13.0.
To learn more about access tiers, see Access tiers overview.
Resources
To learn more about uploading blobs using the Azure Blob Storage client library for JavaScript and TypeScript, see the following resources.
REST API operations
The Azure SDK for JavaScript and TypeScript contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar language paradigms. The client library methods for uploading blobs use the following REST API operations:
Code samples
View code samples from this article (GitHub):
- Upload from local file path
- Upload from buffer
- Upload from stream
- Upload from string
- Upload with transfer options
- Upload with index tags
- Upload with access tier