BlobServiceClient class

A BlobServiceClient represents a Client to the Azure Storage Blob service allowing you to manipulate blob containers.

Extends

StorageClient

Constructors

BlobServiceClient(string, PipelineLike)

Creates an instance of BlobServiceClient.

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

Creates an instance of BlobServiceClient.

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

createContainer(string, ContainerCreateOptions)

Create a Blob container.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container

deleteContainer(string, ContainerDeleteMethodOptions)

Deletes a Blob container.

findBlobsByTags(string, ServiceFindBlobByTagsOptions)

Returns an async iterable iterator to find all blobs with specified tag under the specified account.

.byPage() returns an async iterable iterator to list the blobs in pages.

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

Example using for await syntax:

let i = 1;
for await (const blob of blobServiceClient.findBlobsByTags("tagkey='tagvalue'")) {
  console.log(`Blob ${i++}: ${container.name}`);
}

Example using iter.next():

let i = 1;
const iter = blobServiceClient.findBlobsByTags("tagkey='tagvalue'");
let blobItem = await iter.next();
while (!blobItem.done) {
  console.log(`Blob ${i++}: ${blobItem.value.name}`);
  blobItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of blobServiceClient.findBlobsByTags("tagkey='tagvalue'").byPage({ maxPageSize: 20 })) {
  if (response.blobs) {
    for (const blob of response.blobs) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  }
}

Example using paging with a marker:

let i = 1;
let iterator = blobServiceClient.findBlobsByTags("tagkey='tagvalue'").byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 blob names
if (response.blobs) {
  for (const blob of response.blobs) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

// Gets next marker
let marker = response.continuationToken;
// Passing next marker as continuationToken
iterator = blobServiceClient
  .findBlobsByTags("tagkey='tagvalue'")
  .byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints blob names
if (response.blobs) {
  for (const blob of response.blobs) {
     console.log(`Blob ${i++}: ${blob.name}`);
  }
}
fromConnectionString(string, StoragePipelineOptions)

Creates an instance of BlobServiceClient from connection string.

generateAccountSasUrl(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for BlobServiceClient constructed with a shared key credential.

Generates a Blob account 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/create-account-sas

generateSasStringToSign(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for BlobServiceClient constructed with a shared key credential.

Generates string to sign for a Blob account 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/create-account-sas

getAccountInfo(ServiceGetAccountInfoOptions)

The Get Account Information operation returns the sku name and account kind for the specified account. The Get Account Information operation is available on service versions beginning with version 2018-03-28.

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

getBlobBatchClient()

Creates a BlobBatchClient object to conduct batch operations.

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

getContainerClient(string)

Creates a ContainerClient object

getProperties(ServiceGetPropertiesOptions)

Gets the properties of a storage account’s Blob service, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

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

getStatistics(ServiceGetStatisticsOptions)

Retrieves statistics related to replication for the Blob service. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the storage account.

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

getUserDelegationKey(Date, Date, ServiceGetUserDelegationKeyOptions)

ONLY AVAILABLE WHEN USING BEARER TOKEN AUTHENTICATION (TokenCredential).

Retrieves a user delegation key for the Blob service. This is only a valid operation when using bearer token authentication.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-user-delegation-key

listContainers(ServiceListContainersOptions)

Returns an async iterable iterator to list all the containers under the specified account.

.byPage() returns an async iterable iterator to list the containers in pages.

Example using for await syntax:

let i = 1;
for await (const container of blobServiceClient.listContainers()) {
  console.log(`Container ${i++}: ${container.name}`);
}

Example using iter.next():

let i = 1;
const iter = blobServiceClient.listContainers();
let containerItem = await iter.next();
while (!containerItem.done) {
  console.log(`Container ${i++}: ${containerItem.value.name}`);
  containerItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  if (response.containerItems) {
    for (const container of response.containerItems) {
      console.log(`Container ${i++}: ${container.name}`);
    }
  }
}

Example using paging with a marker:

let i = 1;
let iterator = blobServiceClient.listContainers().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 container names
if (response.containerItems) {
  for (const container of response.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

// Gets next marker
let marker = response.continuationToken;
// Passing next marker as continuationToken
iterator = blobServiceClient
  .listContainers()
  .byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 container names
if (response.containerItems) {
  for (const container of response.containerItems) {
     console.log(`Container ${i++}: ${container.name}`);
  }
}
setProperties(BlobServiceProperties, ServiceSetPropertiesOptions)

Sets properties for a storage account’s Blob service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings.

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

undeleteContainer(string, string, ServiceUndeleteContainerOptions)

Restore a previously deleted Blob container. This API is only functional if Container Soft Delete is enabled for the storage account associated with the container.

Constructor Details

BlobServiceClient(string, PipelineLike)

Creates an instance of BlobServiceClient.

new BlobServiceClient(url: string, pipeline: PipelineLike)

Parameters

url

string

A Client string pointing to Azure Storage blob service, such as "https://myaccount.blob.core.windows.net". You can append a SAS if using AnonymousCredential, such as "https://myaccount.blob.core.windows.net?sasString".

pipeline
PipelineLike

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

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

Creates an instance of BlobServiceClient.

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

Parameters

url

string

A Client string pointing to Azure Storage blob service, such as "https://myaccount.blob.core.windows.net". You can append a SAS if using AnonymousCredential, such as "https://myaccount.blob.core.windows.net?sasString".

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.

Example using DefaultAzureCredential from @azure/identity:

const account = "<storage account name>";

const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

Example using an account name/key:

const account = "<storage account name>"
const sharedKeyCredential = new StorageSharedKeyCredential(account, "<account key>");

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential
);

Inherited Property Details

accountName

accountName: string

Property Value

string

Inherited From StorageClient.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

Inherited From StorageClient.credential

url

Encoded URL string value.

url: string

Property Value

string

Inherited From StorageClient.url

Method Details

createContainer(string, ContainerCreateOptions)

Create a Blob container.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container

function createContainer(containerName: string, options?: ContainerCreateOptions): Promise<{ containerClient: ContainerClient, containerCreateResponse: ContainerCreateResponse }>

Parameters

containerName

string

Name of the container to create.

options
ContainerCreateOptions

Options to configure Container Create operation.

Returns

Promise<{ containerClient: ContainerClient, containerCreateResponse: ContainerCreateResponse }>

Container creation response and the corresponding container client.

deleteContainer(string, ContainerDeleteMethodOptions)

Deletes a Blob container.

function deleteContainer(containerName: string, options?: ContainerDeleteMethodOptions): Promise<ContainerDeleteResponse>

Parameters

containerName

string

Name of the container to delete.

options
ContainerDeleteMethodOptions

Options to configure Container Delete operation.

Returns

Container deletion response.

findBlobsByTags(string, ServiceFindBlobByTagsOptions)

Returns an async iterable iterator to find all blobs with specified tag under the specified account.

.byPage() returns an async iterable iterator to list the blobs in pages.

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

Example using for await syntax:

let i = 1;
for await (const blob of blobServiceClient.findBlobsByTags("tagkey='tagvalue'")) {
  console.log(`Blob ${i++}: ${container.name}`);
}

Example using iter.next():

let i = 1;
const iter = blobServiceClient.findBlobsByTags("tagkey='tagvalue'");
let blobItem = await iter.next();
while (!blobItem.done) {
  console.log(`Blob ${i++}: ${blobItem.value.name}`);
  blobItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of blobServiceClient.findBlobsByTags("tagkey='tagvalue'").byPage({ maxPageSize: 20 })) {
  if (response.blobs) {
    for (const blob of response.blobs) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  }
}

Example using paging with a marker:

let i = 1;
let iterator = blobServiceClient.findBlobsByTags("tagkey='tagvalue'").byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 blob names
if (response.blobs) {
  for (const blob of response.blobs) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

// Gets next marker
let marker = response.continuationToken;
// Passing next marker as continuationToken
iterator = blobServiceClient
  .findBlobsByTags("tagkey='tagvalue'")
  .byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints blob names
if (response.blobs) {
  for (const blob of response.blobs) {
     console.log(`Blob ${i++}: ${blob.name}`);
  }
}
function findBlobsByTags(tagFilterSqlExpression: string, options?: ServiceFindBlobByTagsOptions): PagedAsyncIterableIterator<FilterBlobItem, ServiceFindBlobsByTagsSegmentResponse, PageSettings>

Parameters

tagFilterSqlExpression

string

The where parameter enables the caller to query blobs whose tags match a given expression. The given expression must evaluate to true for a blob to be returned in the results. The[OData - ABNF] filter syntax rule defines the formal grammar for the value of the where query parameter; however, only a subset of the OData filter syntax is supported in the Blob service.

options
ServiceFindBlobByTagsOptions

Options to find blobs by tags.

Returns

fromConnectionString(string, StoragePipelineOptions)

Creates an instance of BlobServiceClient from connection string.

static function fromConnectionString(connectionString: string, options?: StoragePipelineOptions): BlobServiceClient

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

options
StoragePipelineOptions

Optional. Options to configure the HTTP pipeline.

Returns

generateAccountSasUrl(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for BlobServiceClient constructed with a shared key credential.

Generates a Blob account 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/create-account-sas

function generateAccountSasUrl(expiresOn?: Date, permissions?: AccountSASPermissions, resourceTypes?: string, options?: ServiceGenerateAccountSasUrlOptions): string

Parameters

expiresOn

Date

Optional. The time at which the shared access signature becomes invalid. Default to an hour later if not provided.

permissions
AccountSASPermissions

Specifies the list of permissions to be associated with the SAS.

resourceTypes

string

Specifies the resource types associated with the shared access signature.

options
ServiceGenerateAccountSasUrlOptions

Optional parameters.

Returns

string

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

generateSasStringToSign(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for BlobServiceClient constructed with a shared key credential.

Generates string to sign for a Blob account 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/create-account-sas

function generateSasStringToSign(expiresOn?: Date, permissions?: AccountSASPermissions, resourceTypes?: string, options?: ServiceGenerateAccountSasUrlOptions): string

Parameters

expiresOn

Date

Optional. The time at which the shared access signature becomes invalid. Default to an hour later if not provided.

permissions
AccountSASPermissions

Specifies the list of permissions to be associated with the SAS.

resourceTypes

string

Specifies the resource types associated with the shared access signature.

options
ServiceGenerateAccountSasUrlOptions

Optional parameters.

Returns

string

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

getAccountInfo(ServiceGetAccountInfoOptions)

The Get Account Information operation returns the sku name and account kind for the specified account. The Get Account Information operation is available on service versions beginning with version 2018-03-28.

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

function getAccountInfo(options?: ServiceGetAccountInfoOptions): Promise<ServiceGetAccountInfoResponse>

Parameters

options
ServiceGetAccountInfoOptions

Options to the Service Get Account Info operation.

Returns

Response data for the Service Get Account Info operation.

getBlobBatchClient()

Creates a BlobBatchClient object to conduct batch operations.

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

function getBlobBatchClient(): BlobBatchClient

Returns

A new BlobBatchClient object for this service.

getContainerClient(string)

Creates a ContainerClient object

function getContainerClient(containerName: string): ContainerClient

Parameters

containerName

string

A container name

Returns

A new ContainerClient object for the given container name.

Example usage:

const containerClient = blobServiceClient.getContainerClient("<container name>");

getProperties(ServiceGetPropertiesOptions)

Gets the properties of a storage account’s Blob service, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

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

function getProperties(options?: ServiceGetPropertiesOptions): Promise<ServiceGetPropertiesResponse>

Parameters

options
ServiceGetPropertiesOptions

Options to the Service Get Properties operation.

Returns

Response data for the Service Get Properties operation.

getStatistics(ServiceGetStatisticsOptions)

Retrieves statistics related to replication for the Blob service. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the storage account.

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

function getStatistics(options?: ServiceGetStatisticsOptions): Promise<ServiceGetStatisticsResponse>

Parameters

options
ServiceGetStatisticsOptions

Options to the Service Get Statistics operation.

Returns

Response data for the Service Get Statistics operation.

getUserDelegationKey(Date, Date, ServiceGetUserDelegationKeyOptions)

ONLY AVAILABLE WHEN USING BEARER TOKEN AUTHENTICATION (TokenCredential).

Retrieves a user delegation key for the Blob service. This is only a valid operation when using bearer token authentication.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-user-delegation-key

function getUserDelegationKey(startsOn: Date, expiresOn: Date, options?: ServiceGetUserDelegationKeyOptions): Promise<ServiceGetUserDelegationKeyResponse>

Parameters

startsOn

Date

The start time for the user delegation SAS. Must be within 7 days of the current time

expiresOn

Date

The end time for the user delegation SAS. Must be within 7 days of the current time

Returns

listContainers(ServiceListContainersOptions)

Returns an async iterable iterator to list all the containers under the specified account.

.byPage() returns an async iterable iterator to list the containers in pages.

Example using for await syntax:

let i = 1;
for await (const container of blobServiceClient.listContainers()) {
  console.log(`Container ${i++}: ${container.name}`);
}

Example using iter.next():

let i = 1;
const iter = blobServiceClient.listContainers();
let containerItem = await iter.next();
while (!containerItem.done) {
  console.log(`Container ${i++}: ${containerItem.value.name}`);
  containerItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  if (response.containerItems) {
    for (const container of response.containerItems) {
      console.log(`Container ${i++}: ${container.name}`);
    }
  }
}

Example using paging with a marker:

let i = 1;
let iterator = blobServiceClient.listContainers().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 container names
if (response.containerItems) {
  for (const container of response.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

// Gets next marker
let marker = response.continuationToken;
// Passing next marker as continuationToken
iterator = blobServiceClient
  .listContainers()
  .byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 container names
if (response.containerItems) {
  for (const container of response.containerItems) {
     console.log(`Container ${i++}: ${container.name}`);
  }
}
function listContainers(options?: ServiceListContainersOptions): PagedAsyncIterableIterator<ContainerItem, ServiceListContainersSegmentResponse, PageSettings>

Parameters

options
ServiceListContainersOptions

Options to list containers.

Returns

An asyncIterableIterator that supports paging.

setProperties(BlobServiceProperties, ServiceSetPropertiesOptions)

Sets properties for a storage account’s Blob service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings.

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

function setProperties(properties: BlobServiceProperties, options?: ServiceSetPropertiesOptions): Promise<ServiceSetPropertiesResponse>

Parameters

options
ServiceSetPropertiesOptions

Options to the Service Set Properties operation.

Returns

Response data for the Service Set Properties operation.

undeleteContainer(string, string, ServiceUndeleteContainerOptions)

Restore a previously deleted Blob container. This API is only functional if Container Soft Delete is enabled for the storage account associated with the container.

function undeleteContainer(deletedContainerName: string, deletedContainerVersion: string, options?: ServiceUndeleteContainerOptions): Promise<{ containerClient: ContainerClient, containerUndeleteResponse: ContainerUndeleteResponse }>

Parameters

deletedContainerName

string

Name of the previously deleted container.

deletedContainerVersion

string

Version of the previously deleted container, used to uniquely identify the deleted container.

options
ServiceUndeleteContainerOptions

Options to configure Container Restore operation.

Returns

Promise<{ containerClient: ContainerClient, containerUndeleteResponse: ContainerUndeleteResponse }>

Container deletion response.