BlockBlobClient class

  • Reference
Package:
@azure/storage-blob

BlockBlobClient defines a set of operations applicable to block blobs.

Extends
BlobClient

Constructors

BlockBlobClient(string, PipelineLike)

Creates an instance of BlockBlobClient. This method accepts an encoded URL or non-encoded URL pointing to a block blob. Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped. If a blob name includes ? or %, blob name must be encoded in the URL.
BlockBlobClient(string, StorageSharedKeyCredential | AnonymousCredential | TokenCredential, StoragePipelineOptions)

Creates an instance of BlockBlobClient. This method accepts an encoded URL or non-encoded URL pointing to a block blob. Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped. If a blob name includes ? or %, blob name must be encoded in the URL.
BlockBlobClient(string, string, string, StoragePipelineOptions)

Creates an instance of BlockBlobClient.

Properties

containerName

The name of the storage container the blob is associated with.
name

The name of the blob.

Inherited Properties

accountName
credential

Such as AnonymousCredential, StorageSharedKeyCredential or any credential from the @azure/identity package to authenticate requests to the service. You can also provide an object that implements the TokenCredential interface. If not specified, AnonymousCredential is used.
url

Encoded URL string value.

Methods

commitBlockList(string[], BlockBlobCommitBlockListOptions)

Writes a blob by specifying the list of block IDs that make up the blob. In order to be written as part of a blob, a block must have been successfully written to the server in a prior stageBlock operation. You can call commitBlockList to update a blob by uploading only those blocks that have changed, then committing the new and existing blocks together. Any blocks not specified in the block list and permanently deleted.

See https://docs.microsoft.com/rest/api/storageservices/put-block-list
getBlockList(BlockListType, BlockBlobGetBlockListOptions)

Returns the list of blocks that have been uploaded as part of a block blob using the specified block list filter.

See https://docs.microsoft.com/rest/api/storageservices/get-block-list
query(string, BlockBlobQueryOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Quick query for a JSON or CSV formatted blob.

Example usage (Node.js):

// Query and convert a blob to a string
const queryBlockBlobResponse = await blockBlobClient.query("select * from BlobStorage");
const downloaded = (await streamToBuffer(queryBlockBlobResponse.readableStreamBody)).toString();
console.log("Query blob content:", downloaded);

async function streamToBuffer(readableStream) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}
stageBlock(string, HttpRequestBody, number, BlockBlobStageBlockOptions)

Uploads the specified block to the block blob's "staging area" to be later committed by a call to commitBlockList.

See https://docs.microsoft.com/rest/api/storageservices/put-block
stageBlockFromURL(string, string, number, number, BlockBlobStageBlockFromURLOptions)

The Stage Block From URL operation creates a new block to be committed as part of a blob where the contents are read from a URL. This API is available starting in version 2018-03-28.

See https://docs.microsoft.com/en-us/rest/api/storageservices/put-block-from-url
syncUploadFromURL(string, BlockBlobSyncUploadFromURLOptions)

Creates a new Block Blob where the contents of the blob are read from a given URL. This API is supported beginning with the 2020-04-08 version. Partial updates are not supported with Put Blob from URL; the content of an existing blob is overwritten with the content of the new blob. To perform partial updates to a block blob’s contents using a source URL, use stageBlockFromURL and commitBlockList.
upload(HttpRequestBody, number, BlockBlobUploadOptions)

Creates a new block blob, or updates the content of an existing block blob. Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use stageBlock and commitBlockList.

This is a non-parallel uploading method, please use uploadFile, uploadStream or uploadBrowserData for better performance with concurrency uploading.

See https://docs.microsoft.com/rest/api/storageservices/put-blob
uploadBrowserData(Blob | ArrayBuffer | ArrayBufferView, BlockBlobParallelUploadOptions)

ONLY AVAILABLE IN BROWSERS.

Uploads a browser Blob/File/ArrayBuffer/ArrayBufferView object to block blob.

When buffer length lesser than or equal to 256MB, this method will use 1 upload call to finish the upload. Otherwise, this method will call stageBlock to upload blocks, and finally call commitBlockList to commit the block list.

A common blobHTTPHeaders option to set is blobContentType, enabling the browser to provide functionality based on file type.
uploadData(Blob | ArrayBuffer | ArrayBufferView | Buffer, BlockBlobParallelUploadOptions)

Uploads a Buffer(Node.js)/Blob(browsers)/ArrayBuffer/ArrayBufferView object to a BlockBlob.

When data length is no more than the specifiled maxSingleShotSize (default is <xref:BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES>), this method will use 1 upload call to finish the upload. Otherwise, this method will call stageBlock to upload blocks, and finally call commitBlockList to commit the block list.

A common blobHTTPHeaders option to set is blobContentType, enabling the browser to provide functionality based on file type.
uploadFile(string, BlockBlobParallelUploadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Uploads a local file in blocks to a block blob.

When file size lesser than or equal to 256MB, this method will use 1 upload call to finish the upload. Otherwise, this method will call stageBlock to upload blocks, and finally call commitBlockList to commit the block list.
uploadStream(Readable, number, number, BlockBlobUploadStreamOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Uploads a Node.js Readable stream into block blob.

PERFORMANCE IMPROVEMENT TIPS:

  • Input stream highWaterMark is better to set a same value with bufferSize parameter, which will avoid Buffer.concat() operations.
withSnapshot(string)

Creates a new BlockBlobClient object identical to the source but with the specified snapshot timestamp. Provide "" will remove the snapshot and return a URL to the base blob.

Inherited Methods

abortCopyFromURL(string, BlobAbortCopyFromURLOptions)

Aborts a pending asynchronous Copy Blob operation, and leaves a destination blob with zero length and full metadata. Version 2012-02-12 and newer.

See https://docs.microsoft.com/en-us/rest/api/storageservices/abort-copy-blob
beginCopyFromURL(string, BlobBeginCopyFromURLOptions)

Asynchronously copies a blob to a destination within the storage account. This method returns a long running operation poller that allows you to wait indefinitely until the copy is completed. You can also cancel a copy before it is completed by calling cancelOperation on the poller. Note that the onProgress callback will not be invoked if the operation completes in the first request, and attempting to cancel a completed copy will result in an error being thrown.

In version 2012-02-12 and later, the source for a Copy Blob operation can be a committed blob in any Azure storage account. Beginning with version 2015-02-21, the source for a Copy Blob operation can be an Azure file in any Azure storage account. Only storage accounts created on or after June 7th, 2012 allow the Copy Blob operation to copy from another storage account.

See https://docs.microsoft.com/en-us/rest/api/storageservices/copy-blob

Example using automatic polling:

const copyPoller = await blobClient.beginCopyFromURL('url');
const result = await copyPoller.pollUntilDone();

Example using manual polling:

const copyPoller = await blobClient.beginCopyFromURL('url');
while (!poller.isDone()) {
   await poller.poll();
}
const result = copyPoller.getResult();

Example using progress updates:

const copyPoller = await blobClient.beginCopyFromURL('url', {
  onProgress(state) {
    console.log(`Progress: ${state.copyProgress}`);
  }
});
const result = await copyPoller.pollUntilDone();

Example using a changing polling interval (default 15 seconds):

const copyPoller = await blobClient.beginCopyFromURL('url', {
  intervalInMs: 1000 // poll blob every 1 second for copy progress
});
const result = await copyPoller.pollUntilDone();

Example using copy cancellation:

const copyPoller = await blobClient.beginCopyFromURL('url');
// cancel operation after starting it.
try {
  await copyPoller.cancelOperation();
  // calls to get the result now throw PollerCancelledError
  await copyPoller.getResult();
} catch (err) {
  if (err.name === 'PollerCancelledError') {
    console.log('The copy was cancelled.');
  }
}
createSnapshot(BlobCreateSnapshotOptions)

Creates a read-only snapshot of a blob.

See https://docs.microsoft.com/en-us/rest/api/storageservices/snapshot-blob
delete(BlobDeleteOptions)

Marks the specified blob or snapshot for deletion. The blob is later deleted during garbage collection. Note that in order to delete a blob, you must delete all of its snapshots. You can delete both at the same time with the Delete Blob operation.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-blob
deleteIfExists(BlobDeleteOptions)

Marks the specified blob or snapshot for deletion if it exists. The blob is later deleted during garbage collection. Note that in order to delete a blob, you must delete all of its snapshots. You can delete both at the same time with the Delete Blob operation.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-blob
deleteImmutabilityPolicy(BlobDeleteImmutabilityPolicyOptions)

Delete the immutablility policy on the blob.
download(number, number, BlobDownloadOptions)

Reads or downloads a blob from the system, including its metadata and properties. You can also call Get Blob to read a snapshot.

  • In Node.js, data returns in a Readable stream readableStreamBody
  • In browsers, data returns in a promise blobBody

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-blob
downloadToBuffer(Buffer, number, number, BlobDownloadToBufferOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure Blob in parallel to a buffer. Offset and count are optional, downloads the entire blob if they are not provided.

Warning: Buffers can only support files up to about one gigabyte on 32-bit systems or about two gigabytes on 64-bit systems due to limitations of Node.js/V8. For blobs larger than this size, consider downloadToFile.
downloadToBuffer(number, number, BlobDownloadToBufferOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure Blob in parallel to a buffer. Offset and count are optional, downloads the entire blob if they are not provided.

Warning: Buffers can only support files up to about one gigabyte on 32-bit systems or about two gigabytes on 64-bit systems due to limitations of Node.js/V8. For blobs larger than this size, consider downloadToFile.
downloadToFile(string, number, number, BlobDownloadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure Blob to a local file. Fails if the the given file path already exits. Offset and count are optional, pass 0 and undefined respectively to download the entire blob.
exists(BlobExistsOptions)

Returns true if the Azure blob resource represented by this client exists; false otherwise.

NOTE: use this function with care since an existing blob might be deleted by other clients or applications. Vice versa new blobs might be added by other clients or applications after this function completes.
generateSasUrl(BlobGenerateSasUrlOptions)

Only available for BlobClient constructed with a shared key credential.

Generates a Blob Service Shared Access Signature (SAS) URI based on the client properties and parameters passed in. The SAS is signed by the shared key credential of the client.

See https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas
getAppendBlobClient()

Creates a AppendBlobClient object.
getBlobLeaseClient(string)

Get a BlobLeaseClient that manages leases on the blob.
getBlockBlobClient()

Creates a BlockBlobClient object.
getPageBlobClient()

Creates a PageBlobClient object.
getProperties(BlobGetPropertiesOptions)

Returns all user-defined metadata, standard HTTP properties, and system properties for the blob. It does not return the content of the blob.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-blob-properties

WARNING: The metadata object returned in the response will have its keys in lowercase, even if they originally contained uppercase characters. This differs from the metadata keys returned by the methods of ContainerClient that list blobs using the includeMetadata option, which will retain their original casing.
getTags(BlobGetTagsOptions)

Gets the tags associated with the underlying blob.
setAccessTier(string, BlobSetTierOptions)

Sets the tier on a blob. The operation is allowed on a page blob in a premium storage account and on a block blob in a blob storage account (locally redundant storage only). A premium page blob's tier determines the allowed size, IOPS, and bandwidth of the blob. A block blob's tier determines Hot/Cool/Archive storage type. This operation does not update the blob's ETag.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-tier
setHTTPHeaders(BlobHTTPHeaders, BlobSetHTTPHeadersOptions)

Sets system properties on the blob.

If no value provided, or no value provided for the specified blob HTTP headers, these blob HTTP headers without a value will be cleared.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-properties
setImmutabilityPolicy(BlobImmutabilityPolicy, BlobSetImmutabilityPolicyOptions)

Set immutablility policy on the blob.
setLegalHold(boolean, BlobSetLegalHoldOptions)

Set legal hold on the blob.
setMetadata(Metadata, BlobSetMetadataOptions)

Sets user-defined metadata for the specified blob as one or more name-value pairs.

If no option provided, or no metadata defined in the parameter, the blob metadata will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-metadata
setTags(Tags, BlobSetTagsOptions)

Sets tags on the underlying blob. A blob can have up to 10 tags. Tag keys must be between 1 and 128 characters. Tag values must be between 0 and 256 characters. Valid tag key and value characters include lower and upper case letters, digits (0-9), space (' '), plus ('+'), minus ('-'), period ('.'), foward slash ('/'), colon (':'), equals ('='), and underscore ('_').
syncCopyFromURL(string, BlobSyncCopyFromURLOptions)

The synchronous Copy From URL operation copies a blob or an internet resource to a new blob. It will not return a response until the copy is complete.

See https://docs.microsoft.com/en-us/rest/api/storageservices/copy-blob-from-url
undelete(BlobUndeleteOptions)

Restores the contents and metadata of soft deleted blob and any associated soft deleted snapshots. Undelete Blob is supported only on version 2017-07-29 or later.

See https://docs.microsoft.com/en-us/rest/api/storageservices/undelete-blob
withVersion(string)

Creates a new BlobClient object pointing to a version of this blob. Provide "" will remove the versionId and return a Client to the base blob.

Constructor Details

BlockBlobClient(string, PipelineLike)

Creates an instance of BlockBlobClient. This method accepts an encoded URL or non-encoded URL pointing to a block blob. Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped. If a blob name includes ? or %, blob name must be encoded in the URL.

new BlockBlobClient(url: string, pipeline: PipelineLike)

Parameters

url

string

A URL string pointing to Azure Storage block blob, such as "https://myaccount.blob.core.windows.net/mycontainer/blockblob". You can append a SAS if using AnonymousCredential, such as "https://myaccount.blob.core.windows.net/mycontainer/blockblob?sasString". This method accepts an encoded URL or non-encoded URL pointing to a blob. Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped. However, if a blob name includes ? or %, blob name must be encoded in the URL. Such as a blob named "my?blob%", the URL should be "https://myaccount.blob.core.windows.net/mycontainer/my%3Fblob%25".

pipeline
PipelineLike

Call newPipeline() to create a default pipeline, or provide a customized pipeline.

BlockBlobClient(string, StorageSharedKeyCredential | AnonymousCredential | TokenCredential, StoragePipelineOptions)

Creates an instance of BlockBlobClient. This method accepts an encoded URL or non-encoded URL pointing to a block blob. Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped. If a blob name includes ? or %, blob name must be encoded in the URL.

new BlockBlobClient(url: string, credential?: StorageSharedKeyCredential | AnonymousCredential | TokenCredential, options?: StoragePipelineOptions)

Parameters

url

string

A URL string pointing to Azure Storage block blob, such as "https://myaccount.blob.core.windows.net/mycontainer/blockblob". You can append a SAS if using AnonymousCredential, such as "https://myaccount.blob.core.windows.net/mycontainer/blockblob?sasString". This method accepts an encoded URL or non-encoded URL pointing to a blob. Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped. However, if a blob name includes ? or %, blob name must be encoded in the URL. Such as a blob named "my?blob%", the URL should be "https://myaccount.blob.core.windows.net/mycontainer/my%3Fblob%25".

credential

StorageSharedKeyCredential | AnonymousCredential | TokenCredential

Such as AnonymousCredential, StorageSharedKeyCredential or any credential from the @azure/identity package to authenticate requests to the service. You can also provide an object that implements the TokenCredential interface. If not specified, AnonymousCredential is used.

options
StoragePipelineOptions

Optional. Options to configure the HTTP pipeline.

BlockBlobClient(string, string, string, StoragePipelineOptions)

Creates an instance of BlockBlobClient.

new BlockBlobClient(connectionString: string, containerName: string, blobName: string, options?: StoragePipelineOptions)

Parameters

connectionString

string

Account connection string or a SAS connection string of an Azure storage account. [ Note - Account connection string can only be used in NODE.JS runtime. ] Account connection string example - DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net SAS connection string example - BlobEndpoint=https://myaccount.blob.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString

containerName

string

Container name.

blobName

string

Blob name.

options
StoragePipelineOptions

Optional. Options to configure the HTTP pipeline.

Property Details

containerName

The name of the storage container the blob is associated with.

string containerName

Property Value

string

name

The name of the blob.

string name

Property Value

string

Inherited Property Details

accountName 

accountName: string

Property Value

string

Inherited From BlobClient.accountName

credential

Such as AnonymousCredential, StorageSharedKeyCredential or any credential from the @azure/identity package to authenticate requests to the service. You can also provide an object that implements the TokenCredential interface. If not specified, AnonymousCredential is used.

credential: StorageSharedKeyCredential | AnonymousCredential | TokenCredential

Property Value

StorageSharedKeyCredential | AnonymousCredential | TokenCredential

Inherited From BlobClient.credential

url

Encoded URL string value.

url: string

Property Value

string

Inherited From BlobClient.url

Method Details

commitBlockList(string[], BlockBlobCommitBlockListOptions)

Writes a blob by specifying the list of block IDs that make up the blob. In order to be written as part of a blob, a block must have been successfully written to the server in a prior stageBlock operation. You can call commitBlockList to update a blob by uploading only those blocks that have changed, then committing the new and existing blocks together. Any blocks not specified in the block list and permanently deleted.

See https://docs.microsoft.com/rest/api/storageservices/put-block-list

function commitBlockList(blocks: string[], options?: BlockBlobCommitBlockListOptions): Promise<BlockBlobCommitBlockListResponse>

Parameters

blocks

string[]

Array of 64-byte value that is base64-encoded

options
BlockBlobCommitBlockListOptions

Options to the Block Blob Commit Block List operation.

Returns

Promise<BlockBlobCommitBlockListResponse>

Response data for the Block Blob Commit Block List operation.

getBlockList(BlockListType, BlockBlobGetBlockListOptions)

Returns the list of blocks that have been uploaded as part of a block blob using the specified block list filter.

See https://docs.microsoft.com/rest/api/storageservices/get-block-list

function getBlockList(listType: BlockListType, options?: BlockBlobGetBlockListOptions): Promise<BlockBlobGetBlockListResponse>

Parameters

listType
BlockListType

Specifies whether to return the list of committed blocks, the list of uncommitted blocks, or both lists together.

options
BlockBlobGetBlockListOptions

Options to the Block Blob Get Block List operation.

Returns

Promise<BlockBlobGetBlockListResponse>

Response data for the Block Blob Get Block List operation.

query(string, BlockBlobQueryOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Quick query for a JSON or CSV formatted blob.

Example usage (Node.js):

// Query and convert a blob to a string
const queryBlockBlobResponse = await blockBlobClient.query("select * from BlobStorage");
const downloaded = (await streamToBuffer(queryBlockBlobResponse.readableStreamBody)).toString();
console.log("Query blob content:", downloaded);

async function streamToBuffer(readableStream) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

function query(query: string, options?: BlockBlobQueryOptions): Promise<BlobDownloadResponseModel>

Parameters

query

string

options
BlockBlobQueryOptions

Returns

Promise<BlobDownloadResponseModel>

stageBlock(string, HttpRequestBody, number, BlockBlobStageBlockOptions)

Uploads the specified block to the block blob's "staging area" to be later committed by a call to commitBlockList.

See https://docs.microsoft.com/rest/api/storageservices/put-block

function stageBlock(blockId: string, body: HttpRequestBody, contentLength: number, options?: BlockBlobStageBlockOptions): Promise<BlockBlobStageBlockResponse>

Parameters

blockId

string

A 64-byte value that is base64-encoded

body
HttpRequestBody

Data to upload to the staging area.

contentLength

number

Number of bytes to upload.

options
BlockBlobStageBlockOptions

Options to the Block Blob Stage Block operation.

Returns

Promise<BlockBlobStageBlockResponse>

Response data for the Block Blob Stage Block operation.

stageBlockFromURL(string, string, number, number, BlockBlobStageBlockFromURLOptions)

The Stage Block From URL operation creates a new block to be committed as part of a blob where the contents are read from a URL. This API is available starting in version 2018-03-28.

See https://docs.microsoft.com/en-us/rest/api/storageservices/put-block-from-url

function stageBlockFromURL(blockId: string, sourceURL: string, offset?: number, count?: number, options?: BlockBlobStageBlockFromURLOptions): Promise<BlockBlobStageBlockFromURLResponse>

Parameters

blockId

string

A 64-byte value that is base64-encoded

sourceURL

string

Specifies the URL of the blob. The value may be a URL of up to 2 KB in length that specifies a blob. The value should be URL-encoded as it would appear in a request URI. The source blob must either be public or must be authenticated via a shared access signature. If the source blob is public, no authentication is required to perform the operation. Here are some examples of source object URLs: - https://myaccount.blob.core.windows.net/mycontainer/myblob - https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=

offset

number

From which position of the blob to download, greater than or equal to 0

count

number

How much data to be downloaded, greater than 0. Will download to the end when undefined

options
BlockBlobStageBlockFromURLOptions

Options to the Block Blob Stage Block From URL operation.

Returns

Promise<BlockBlobStageBlockFromURLResponse>

Response data for the Block Blob Stage Block From URL operation.

syncUploadFromURL(string, BlockBlobSyncUploadFromURLOptions)

Creates a new Block Blob where the contents of the blob are read from a given URL. This API is supported beginning with the 2020-04-08 version. Partial updates are not supported with Put Blob from URL; the content of an existing blob is overwritten with the content of the new blob. To perform partial updates to a block blob’s contents using a source URL, use stageBlockFromURL and commitBlockList.

function syncUploadFromURL(sourceURL: string, options?: BlockBlobSyncUploadFromURLOptions): Promise<BlockBlobPutBlobFromUrlResponse>

Parameters

sourceURL

string

Specifies the URL of the blob. The value may be a URL of up to 2 KB in length that specifies a blob. The value should be URL-encoded as it would appear in a request URI. The source blob must either be public or must be authenticated via a shared access signature. If the source blob is public, no authentication is required to perform the operation. Here are some examples of source object URLs: - https://myaccount.blob.core.windows.net/mycontainer/myblob - https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=

options
BlockBlobSyncUploadFromURLOptions

Optional parameters.

Returns

Promise<BlockBlobPutBlobFromUrlResponse>

upload(HttpRequestBody, number, BlockBlobUploadOptions)

Creates a new block blob, or updates the content of an existing block blob. Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use stageBlock and commitBlockList.

This is a non-parallel uploading method, please use uploadFile, uploadStream or uploadBrowserData for better performance with concurrency uploading.

See https://docs.microsoft.com/rest/api/storageservices/put-blob

function upload(body: HttpRequestBody, contentLength: number, options?: BlockBlobUploadOptions): Promise<BlockBlobUploadResponse>

Parameters

body
HttpRequestBody

Blob, string, ArrayBuffer, ArrayBufferView or a function which returns a new Readable stream whose offset is from data source beginning.

contentLength

number

Length of body in bytes. Use Buffer.byteLength() to calculate body length for a string including non non-Base64/Hex-encoded characters.

options
BlockBlobUploadOptions

Options to the Block Blob Upload operation.

Returns

Promise<BlockBlobUploadResponse>

Response data for the Block Blob Upload operation.

Example usage:

const content = "Hello world!";
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);

uploadBrowserData(Blob | ArrayBuffer | ArrayBufferView, BlockBlobParallelUploadOptions)

Warning

This API is now deprecated.

Use uploadData instead.

ONLY AVAILABLE IN BROWSERS.

Uploads a browser Blob/File/ArrayBuffer/ArrayBufferView object to block blob.

When buffer length lesser than or equal to 256MB, this method will use 1 upload call to finish the upload. Otherwise, this method will call stageBlock to upload blocks, and finally call commitBlockList to commit the block list.

A common blobHTTPHeaders option to set is blobContentType, enabling the browser to provide functionality based on file type.

function uploadBrowserData(browserData: Blob | ArrayBuffer | ArrayBufferView, options?: BlockBlobParallelUploadOptions): Promise<BlobUploadCommonResponse>

Parameters

browserData

Blob | ArrayBuffer | ArrayBufferView

Blob, File, ArrayBuffer or ArrayBufferView

options
BlockBlobParallelUploadOptions

Options to upload browser data.

Returns

Promise<BlobUploadCommonResponse>

Response data for the Blob Upload operation.

uploadData(Blob | ArrayBuffer | ArrayBufferView | Buffer, BlockBlobParallelUploadOptions)

Uploads a Buffer(Node.js)/Blob(browsers)/ArrayBuffer/ArrayBufferView object to a BlockBlob.

When data length is no more than the specifiled maxSingleShotSize (default is <xref:BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES>), this method will use 1 upload call to finish the upload. Otherwise, this method will call stageBlock to upload blocks, and finally call commitBlockList to commit the block list.

A common blobHTTPHeaders option to set is blobContentType, enabling the browser to provide functionality based on file type.

function uploadData(data: Blob | ArrayBuffer | ArrayBufferView | Buffer, options?: BlockBlobParallelUploadOptions): Promise<BlobUploadCommonResponse>

Parameters

data

Blob | ArrayBuffer | ArrayBufferView | Buffer

Buffer(Node.js), Blob, ArrayBuffer or ArrayBufferView

options
BlockBlobParallelUploadOptions

Returns

Promise<BlobUploadCommonResponse>

uploadFile(string, BlockBlobParallelUploadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Uploads a local file in blocks to a block blob.

When file size lesser than or equal to 256MB, this method will use 1 upload call to finish the upload. Otherwise, this method will call stageBlock to upload blocks, and finally call commitBlockList to commit the block list.

function uploadFile(filePath: string, options?: BlockBlobParallelUploadOptions): Promise<BlobUploadCommonResponse>

Parameters

filePath

string

Full path of local file

options
BlockBlobParallelUploadOptions

Options to Upload to Block Blob operation.

Returns

Promise<BlobUploadCommonResponse>

Response data for the Blob Upload operation.

uploadStream(Readable, number, number, BlockBlobUploadStreamOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Uploads a Node.js Readable stream into block blob.

PERFORMANCE IMPROVEMENT TIPS:

  • Input stream highWaterMark is better to set a same value with bufferSize parameter, which will avoid Buffer.concat() operations.
function uploadStream(stream: Readable, bufferSize?: number, maxConcurrency?: number, options?: BlockBlobUploadStreamOptions): Promise<BlobUploadCommonResponse>

Parameters

stream

Readable

Node.js Readable stream

bufferSize

number

Size of every buffer allocated, also the block size in the uploaded block blob. Default value is 8MB

maxConcurrency

number

Max concurrency indicates the max number of buffers that can be allocated, positive correlation with max uploading concurrency. Default value is 5

options
BlockBlobUploadStreamOptions

Options to Upload Stream to Block Blob operation.

Returns

Promise<BlobUploadCommonResponse>

Response data for the Blob Upload operation.

withSnapshot(string)

Creates a new BlockBlobClient object identical to the source but with the specified snapshot timestamp. Provide "" will remove the snapshot and return a URL to the base blob.

function withSnapshot(snapshot: string): BlockBlobClient

Parameters

snapshot

string

The snapshot timestamp.

Returns

BlockBlobClient

A new BlockBlobClient object identical to the source but with the specified snapshot timestamp.

Inherited Method Details

abortCopyFromURL(string, BlobAbortCopyFromURLOptions)

Aborts a pending asynchronous Copy Blob operation, and leaves a destination blob with zero length and full metadata. Version 2012-02-12 and newer.

See https://docs.microsoft.com/en-us/rest/api/storageservices/abort-copy-blob

function abortCopyFromURL(copyId: string, options?: BlobAbortCopyFromURLOptions): Promise<BlobAbortCopyFromURLResponse>

Parameters

copyId

string

Id of the Copy From URL operation.

options
BlobAbortCopyFromURLOptions

Optional options to the Blob Abort Copy From URL operation.

Returns

Promise<BlobAbortCopyFromURLResponse>

Inherited From BlobClient.abortCopyFromURL

beginCopyFromURL(string, BlobBeginCopyFromURLOptions)

Asynchronously copies a blob to a destination within the storage account. This method returns a long running operation poller that allows you to wait indefinitely until the copy is completed. You can also cancel a copy before it is completed by calling cancelOperation on the poller. Note that the onProgress callback will not be invoked if the operation completes in the first request, and attempting to cancel a completed copy will result in an error being thrown.

In version 2012-02-12 and later, the source for a Copy Blob operation can be a committed blob in any Azure storage account. Beginning with version 2015-02-21, the source for a Copy Blob operation can be an Azure file in any Azure storage account. Only storage accounts created on or after June 7th, 2012 allow the Copy Blob operation to copy from another storage account.

See https://docs.microsoft.com/en-us/rest/api/storageservices/copy-blob

Example using automatic polling:

const copyPoller = await blobClient.beginCopyFromURL('url');
const result = await copyPoller.pollUntilDone();

Example using manual polling:

const copyPoller = await blobClient.beginCopyFromURL('url');
while (!poller.isDone()) {
   await poller.poll();
}
const result = copyPoller.getResult();

Example using progress updates:

const copyPoller = await blobClient.beginCopyFromURL('url', {
  onProgress(state) {
    console.log(`Progress: ${state.copyProgress}`);
  }
});
const result = await copyPoller.pollUntilDone();

Example using a changing polling interval (default 15 seconds):

const copyPoller = await blobClient.beginCopyFromURL('url', {
  intervalInMs: 1000 // poll blob every 1 second for copy progress
});
const result = await copyPoller.pollUntilDone();

Example using copy cancellation:

const copyPoller = await blobClient.beginCopyFromURL('url');
// cancel operation after starting it.
try {
  await copyPoller.cancelOperation();
  // calls to get the result now throw PollerCancelledError
  await copyPoller.getResult();
} catch (err) {
  if (err.name === 'PollerCancelledError') {
    console.log('The copy was cancelled.');
  }
}

function beginCopyFromURL(copySource: string, options?: BlobBeginCopyFromURLOptions): Promise<PollerLikeWithCancellation<PollOperationState<BlobBeginCopyFromURLResponse>, BlobBeginCopyFromURLResponse>>

Parameters

copySource

string

url to the source Azure Blob/File.

options
BlobBeginCopyFromURLOptions

Optional options to the Blob Start Copy From URL operation.

Returns

Promise<PollerLikeWithCancellation<PollOperationState<BlobBeginCopyFromURLResponse>, BlobBeginCopyFromURLResponse>>

Inherited From BlobClient.beginCopyFromURL

createSnapshot(BlobCreateSnapshotOptions)

Creates a read-only snapshot of a blob.

See https://docs.microsoft.com/en-us/rest/api/storageservices/snapshot-blob

function createSnapshot(options?: BlobCreateSnapshotOptions): Promise<BlobCreateSnapshotResponse>

Parameters

options
BlobCreateSnapshotOptions

Optional options to the Blob Create Snapshot operation.

Returns

Promise<BlobCreateSnapshotResponse>

Inherited From BlobClient.createSnapshot

delete(BlobDeleteOptions)

Marks the specified blob or snapshot for deletion. The blob is later deleted during garbage collection. Note that in order to delete a blob, you must delete all of its snapshots. You can delete both at the same time with the Delete Blob operation.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-blob

function delete(options?: BlobDeleteOptions): Promise<BlobDeleteResponse>

Parameters

options
BlobDeleteOptions

Optional options to Blob Delete operation.

Returns

Promise<BlobDeleteResponse>

Inherited From BlobClient.delete

deleteIfExists(BlobDeleteOptions)

Marks the specified blob or snapshot for deletion if it exists. The blob is later deleted during garbage collection. Note that in order to delete a blob, you must delete all of its snapshots. You can delete both at the same time with the Delete Blob operation.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-blob

function deleteIfExists(options?: BlobDeleteOptions): Promise<BlobDeleteIfExistsResponse>

Parameters

options
BlobDeleteOptions

Optional options to Blob Delete operation.

Returns

Promise<BlobDeleteIfExistsResponse>

Inherited From BlobClient.deleteIfExists

deleteImmutabilityPolicy(BlobDeleteImmutabilityPolicyOptions)

Delete the immutablility policy on the blob.

function deleteImmutabilityPolicy(options?: BlobDeleteImmutabilityPolicyOptions): Promise<BlobDeleteImmutabilityPolicyResponse>

Parameters

options
BlobDeleteImmutabilityPolicyOptions

Optional options to delete immutability policy on the blob.

Returns

Promise<BlobDeleteImmutabilityPolicyResponse>

Inherited From BlobClient.deleteImmutabilityPolicy

download(number, number, BlobDownloadOptions)

Reads or downloads a blob from the system, including its metadata and properties. You can also call Get Blob to read a snapshot.

  • In Node.js, data returns in a Readable stream readableStreamBody
  • In browsers, data returns in a promise blobBody

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-blob

function download(offset?: number, count?: number, options?: BlobDownloadOptions): Promise<BlobDownloadResponseParsed>

Parameters

offset

number

From which position of the blob to download, greater than or equal to 0

count

number

How much data to be downloaded, greater than 0. Will download to the end when undefined

options
BlobDownloadOptions

Optional options to Blob Download operation.

Example usage (Node.js):

// Download and convert a blob to a string
const downloadBlockBlobResponse = await blobClient.download();
const downloaded = await streamToBuffer(downloadBlockBlobResponse.readableStreamBody);
console.log("Downloaded blob content:", downloaded.toString());

async function streamToBuffer(readableStream) {
return new Promise((resolve, reject) => {
const chunks = [];
readableStream.on("data", (data) => {
chunks.push(data instanceof Buffer ? data : Buffer.from(data));
});
readableStream.on("end", () => {
resolve(Buffer.concat(chunks));
});
readableStream.on("error", reject);
});
}

Example usage (browser):

// Download and convert a blob to a string
const downloadBlockBlobResponse = await blobClient.download();
const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
console.log(
  "Downloaded blob content",
  downloaded
);

async function blobToString(blob: Blob): Promise<string> {
  const fileReader = new FileReader();
  return new Promise<string>((resolve, reject) => {
    fileReader.onloadend = (ev: any) => {
      resolve(ev.target!.result);
    };
    fileReader.onerror = reject;
    fileReader.readAsText(blob);
  });
}

Returns

Promise<BlobDownloadResponseParsed>

Inherited From BlobClient.download

downloadToBuffer(Buffer, number, number, BlobDownloadToBufferOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure Blob in parallel to a buffer. Offset and count are optional, downloads the entire blob if they are not provided.

Warning: Buffers can only support files up to about one gigabyte on 32-bit systems or about two gigabytes on 64-bit systems due to limitations of Node.js/V8. For blobs larger than this size, consider downloadToFile.

function downloadToBuffer(buffer: Buffer, offset?: number, count?: number, options?: BlobDownloadToBufferOptions): Promise<Buffer>

Parameters

buffer

Buffer

Buffer to be fill, must have length larger than count

offset

number

From which position of the block blob to download(in bytes)

count

number

How much data(in bytes) to be downloaded. Will download to the end when passing undefined

options
BlobDownloadToBufferOptions

BlobDownloadToBufferOptions

Returns

Promise<Buffer>

Inherited From BlobClient.downloadToBuffer

downloadToBuffer(number, number, BlobDownloadToBufferOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure Blob in parallel to a buffer. Offset and count are optional, downloads the entire blob if they are not provided.

Warning: Buffers can only support files up to about one gigabyte on 32-bit systems or about two gigabytes on 64-bit systems due to limitations of Node.js/V8. For blobs larger than this size, consider downloadToFile.

function downloadToBuffer(offset?: number, count?: number, options?: BlobDownloadToBufferOptions): Promise<Buffer>

Parameters

offset

number

From which position of the block blob to download(in bytes)

count

number

How much data(in bytes) to be downloaded. Will download to the end when passing undefined

options
BlobDownloadToBufferOptions

BlobDownloadToBufferOptions

Returns

Promise<Buffer>

Inherited From BlobClient.downloadToBuffer

downloadToFile(string, number, number, BlobDownloadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure Blob to a local file. Fails if the the given file path already exits. Offset and count are optional, pass 0 and undefined respectively to download the entire blob.

function downloadToFile(filePath: string, offset?: number, count?: number, options?: BlobDownloadOptions): Promise<BlobDownloadResponseParsed>

Parameters

filePath

string

offset

number

From which position of the block blob to download.

count

number

How much data to be downloaded. Will download to the end when passing undefined.

options
BlobDownloadOptions

Options to Blob download options.

Returns

Promise<BlobDownloadResponseParsed>

The response data for blob download operation, but with readableStreamBody set to undefined since its content is already read and written into a local file at the specified path.

Inherited From BlobClient.downloadToFile

exists(BlobExistsOptions)

Returns true if the Azure blob resource represented by this client exists; false otherwise.

NOTE: use this function with care since an existing blob might be deleted by other clients or applications. Vice versa new blobs might be added by other clients or applications after this function completes.

function exists(options?: BlobExistsOptions): Promise<boolean>

Parameters

options
BlobExistsOptions

options to Exists operation.

Returns

Promise<boolean>

Inherited From BlobClient.exists

generateSasUrl(BlobGenerateSasUrlOptions)

Only available for BlobClient constructed with a shared key credential.

Generates a Blob Service Shared Access Signature (SAS) URI based on the client properties and parameters passed in. The SAS is signed by the shared key credential of the client.

See https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas

function generateSasUrl(options: BlobGenerateSasUrlOptions): Promise<string>

Parameters

options
BlobGenerateSasUrlOptions

Optional parameters.

Returns

Promise<string>

The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token.

Inherited From BlobClient.generateSasUrl

getAppendBlobClient()

Creates a AppendBlobClient object.

function getAppendBlobClient(): AppendBlobClient

Returns

AppendBlobClient

Inherited From BlobClient.getAppendBlobClient

getBlobLeaseClient(string)

Get a BlobLeaseClient that manages leases on the blob.

function getBlobLeaseClient(proposeLeaseId?: string): BlobLeaseClient

Parameters

proposeLeaseId

string

Initial proposed lease Id.

Returns

BlobLeaseClient

A new BlobLeaseClient object for managing leases on the blob.

Inherited From BlobClient.getBlobLeaseClient

getBlockBlobClient()

Creates a BlockBlobClient object.

function getBlockBlobClient(): BlockBlobClient

Returns

BlockBlobClient

Inherited From BlobClient.getBlockBlobClient

getPageBlobClient()

Creates a PageBlobClient object.

function getPageBlobClient(): PageBlobClient

Returns

PageBlobClient

Inherited From BlobClient.getPageBlobClient

getProperties(BlobGetPropertiesOptions)

Returns all user-defined metadata, standard HTTP properties, and system properties for the blob. It does not return the content of the blob.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-blob-properties

WARNING: The metadata object returned in the response will have its keys in lowercase, even if they originally contained uppercase characters. This differs from the metadata keys returned by the methods of ContainerClient that list blobs using the includeMetadata option, which will retain their original casing.

function getProperties(options?: BlobGetPropertiesOptions): Promise<BlobGetPropertiesResponse>

Parameters

options
BlobGetPropertiesOptions

Optional options to Get Properties operation.

Returns

Promise<BlobGetPropertiesResponse>

Inherited From BlobClient.getProperties

getTags(BlobGetTagsOptions)

Gets the tags associated with the underlying blob.

function getTags(options?: BlobGetTagsOptions): Promise<BlobGetTagsResponse>

Parameters

options
BlobGetTagsOptions

Returns

Promise<BlobGetTagsResponse>

Inherited From BlobClient.getTags

setAccessTier(string, BlobSetTierOptions)

Sets the tier on a blob. The operation is allowed on a page blob in a premium storage account and on a block blob in a blob storage account (locally redundant storage only). A premium page blob's tier determines the allowed size, IOPS, and bandwidth of the blob. A block blob's tier determines Hot/Cool/Archive storage type. This operation does not update the blob's ETag.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-tier

function setAccessTier(tier: string, options?: BlobSetTierOptions): Promise<BlobSetTierResponse>

Parameters

tier

string

The tier to be set on the blob. Valid values are Hot, Cool, or Archive.

options
BlobSetTierOptions

Optional options to the Blob Set Tier operation.

Returns

Promise<BlobSetTierResponse>

Inherited From BlobClient.setAccessTier

setHTTPHeaders(BlobHTTPHeaders, BlobSetHTTPHeadersOptions)

Sets system properties on the blob.

If no value provided, or no value provided for the specified blob HTTP headers, these blob HTTP headers without a value will be cleared.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-properties

function setHTTPHeaders(blobHTTPHeaders?: BlobHTTPHeaders, options?: BlobSetHTTPHeadersOptions): Promise<BlobSetHTTPHeadersResponse>

Parameters

blobHTTPHeaders
BlobHTTPHeaders

If no value provided, or no value provided for the specified blob HTTP headers, these blob HTTP headers without a value will be cleared. A common header to set is blobContentType enabling the browser to provide functionality based on file type.

options
BlobSetHTTPHeadersOptions

Optional options to Blob Set HTTP Headers operation.

Returns

Promise<BlobSetHTTPHeadersResponse>

Inherited From BlobClient.setHTTPHeaders

setImmutabilityPolicy(BlobImmutabilityPolicy, BlobSetImmutabilityPolicyOptions)

Set immutablility policy on the blob.

function setImmutabilityPolicy(immutabilityPolicy: BlobImmutabilityPolicy, options?: BlobSetImmutabilityPolicyOptions): Promise<BlobSetImmutabilityPolicyResponse>

Parameters

immutabilityPolicy
BlobImmutabilityPolicy
options
BlobSetImmutabilityPolicyOptions

Optional options to set immutability policy on the blob.

Returns

Promise<BlobSetImmutabilityPolicyResponse>

Inherited From BlobClient.setImmutabilityPolicy

setLegalHold(boolean, BlobSetLegalHoldOptions)

Set legal hold on the blob.

function setLegalHold(legalHoldEnabled: boolean, options?: BlobSetLegalHoldOptions): Promise<BlobSetLegalHoldResponse>

Parameters

legalHoldEnabled

boolean

options
BlobSetLegalHoldOptions

Optional options to set legal hold on the blob.

Returns

Promise<BlobSetLegalHoldResponse>

Inherited From BlobClient.setLegalHold

setMetadata(Metadata, BlobSetMetadataOptions)

Sets user-defined metadata for the specified blob as one or more name-value pairs.

If no option provided, or no metadata defined in the parameter, the blob metadata will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-metadata

function setMetadata(metadata?: Metadata, options?: BlobSetMetadataOptions): Promise<BlobSetMetadataResponse>

Parameters

metadata
Metadata

Replace existing metadata with this value. If no value provided the existing metadata will be removed.

options
BlobSetMetadataOptions

Optional options to Set Metadata operation.

Returns

Promise<BlobSetMetadataResponse>

Inherited From BlobClient.setMetadata

setTags(Tags, BlobSetTagsOptions)

Sets tags on the underlying blob. A blob can have up to 10 tags. Tag keys must be between 1 and 128 characters. Tag values must be between 0 and 256 characters. Valid tag key and value characters include lower and upper case letters, digits (0-9), space (' '), plus ('+'), minus ('-'), period ('.'), foward slash ('/'), colon (':'), equals ('='), and underscore ('_').

function setTags(tags: Tags, options?: BlobSetTagsOptions): Promise<BlobSetTagsResponse>

Parameters

tags
Tags
options
BlobSetTagsOptions

Returns

Promise<BlobSetTagsResponse>

Inherited From BlobClient.setTags

syncCopyFromURL(string, BlobSyncCopyFromURLOptions)

The synchronous Copy From URL operation copies a blob or an internet resource to a new blob. It will not return a response until the copy is complete.

See https://docs.microsoft.com/en-us/rest/api/storageservices/copy-blob-from-url

function syncCopyFromURL(copySource: string, options?: BlobSyncCopyFromURLOptions): Promise<BlobCopyFromURLResponse>

Parameters

copySource

string

The source URL to copy from, Shared Access Signature(SAS) maybe needed for authentication

options
BlobSyncCopyFromURLOptions

Returns

Promise<BlobCopyFromURLResponse>

Inherited From BlobClient.syncCopyFromURL

undelete(BlobUndeleteOptions)

Restores the contents and metadata of soft deleted blob and any associated soft deleted snapshots. Undelete Blob is supported only on version 2017-07-29 or later.

See https://docs.microsoft.com/en-us/rest/api/storageservices/undelete-blob

function undelete(options?: BlobUndeleteOptions): Promise<BlobUndeleteResponse>

Parameters

options
BlobUndeleteOptions

Optional options to Blob Undelete operation.

Returns

Promise<BlobUndeleteResponse>

Inherited From BlobClient.undelete

withVersion(string)

Creates a new BlobClient object pointing to a version of this blob. Provide "" will remove the versionId and return a Client to the base blob.

function withVersion(versionId: string): BlobClient

Parameters

versionId

string

The versionId.

Returns

BlobClient

A new BlobClient object pointing to the version of this blob.

Inherited From BlobClient.withVersion