Share via

ContainerClient class

  • Reference
Package:
@azure/storage-blob

A ContainerClient represents a URL to the Azure Storage container allowing you to manipulate its blobs.

Extends

StorageClient

Constructors

ContainerClient(string, PipelineLike)

Creates an instance of ContainerClient. This method accepts an URL pointing to a container. 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.
ContainerClient(string, StorageSharedKeyCredential | AnonymousCredential | TokenCredential, StoragePipelineOptions)

Creates an instance of ContainerClient. This method accepts an URL pointing to a container. 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.
ContainerClient(string, string, StoragePipelineOptions)

Creates an instance of ContainerClient.

Properties

containerName

The name of the container.

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

create(ContainerCreateOptions)

Creates a new container under the specified account. If the container with the same name already exists, the operation fails.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container Naming rules: See https://learn.microsoft.com/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata
createIfNotExists(ContainerCreateOptions)

Creates a new container under the specified account. If the container with the same name already exists, it is not changed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container Naming rules: See https://learn.microsoft.com/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata
delete(ContainerDeleteMethodOptions)

Marks the specified container for deletion. The container and any blobs contained within it are later deleted during garbage collection.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-container
deleteBlob(string, ContainerDeleteBlobOptions)

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(ContainerDeleteMethodOptions)

Marks the specified container for deletion if it exists. The container and any blobs contained within it are later deleted during garbage collection.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-container
exists(ContainerExistsOptions)

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

NOTE: use this function with care since an existing container might be deleted by other clients or applications. Vice versa new containers with the same name might be added by other clients or applications after this function completes.
findBlobsByTags(string, ContainerFindBlobByTagsOptions)

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

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

Example using for await syntax:

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

Example using iter.next():

let i = 1;
const iter = containerClient.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 containerClient.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 = containerClient.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 = containerClient
  .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}`);
  }
}
generateSasStringToSign(ContainerGenerateSasUrlOptions)

Only available for ContainerClient constructed with a shared key credential.

Generates string to sign for a Blob Container 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
generateSasUrl(ContainerGenerateSasUrlOptions)

Only available for ContainerClient constructed with a shared key credential.

Generates a Blob Container 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
getAccessPolicy(ContainerGetAccessPolicyOptions)

Gets the permissions for the specified container. The permissions indicate whether container data may be accessed publicly.

WARNING: JavaScript Date will potentially lose precision when parsing startsOn and expiresOn strings. For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z".

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-container-acl
getAccountInfo(ContainerGetAccountInfoOptions)

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
getAppendBlobClient(string)

Creates an AppendBlobClient
getBlobBatchClient()

Creates a BlobBatchClient object to conduct batch operations.

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

Creates a BlobClient
getBlobLeaseClient(string)

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

Creates a BlockBlobClient
getPageBlobClient(string)

Creates a PageBlobClient
getProperties(ContainerGetPropertiesOptions)

Returns all user-defined metadata and system properties for the specified container. The data returned does not include the container's list of blobs.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-container-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 listContainers method of BlobServiceClient using the includeMetadata option, which will retain their original casing.
listBlobsByHierarchy(string, ContainerListBlobsOptions)

Returns an async iterable iterator to list all the blobs by hierarchy. under the specified account.

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

Example using for await syntax:

for await (const item of containerClient.listBlobsByHierarchy("/")) {
  if (item.kind === "prefix") {
    console.log(`\tBlobPrefix: ${item.name}`);
  } else {
    console.log(`\tBlobItem: name - ${item.name}`);
  }
}

Example using iter.next():

let iter = containerClient.listBlobsByHierarchy("/", { prefix: "prefix1/" });
let entity = await iter.next();
while (!entity.done) {
  let item = entity.value;
  if (item.kind === "prefix") {
    console.log(`\tBlobPrefix: ${item.name}`);
  } else {
    console.log(`\tBlobItem: name - ${item.name}`);
  }
  entity = await iter.next();
}

Example using byPage():

console.log("Listing blobs by hierarchy by page");
for await (const response of containerClient.listBlobsByHierarchy("/").byPage()) {
  const segment = response.segment;
  if (segment.blobPrefixes) {
    for (const prefix of segment.blobPrefixes) {
      console.log(`\tBlobPrefix: ${prefix.name}`);
    }
  }
  for (const blob of response.segment.blobItems) {
    console.log(`\tBlobItem: name - ${blob.name}`);
  }
}

Example using paging with a max page size:

console.log("Listing blobs by hierarchy by page, specifying a prefix and a max page size");

let i = 1;
for await (const response of containerClient
  .listBlobsByHierarchy("/", { prefix: "prefix2/sub1/" })
  .byPage({ maxPageSize: 2 })) {
  console.log(`Page ${i++}`);
  const segment = response.segment;

  if (segment.blobPrefixes) {
    for (const prefix of segment.blobPrefixes) {
      console.log(`\tBlobPrefix: ${prefix.name}`);
    }
  }

  for (const blob of response.segment.blobItems) {
    console.log(`\tBlobItem: name - ${blob.name}`);
  }
}
listBlobsFlat(ContainerListBlobsOptions)

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

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

Example using for await syntax:

// Get the containerClient before you run these snippets,
// Can be obtained from `blobServiceClient.getContainerClient("<your-container-name>");`
let i = 1;
for await (const blob of containerClient.listBlobsFlat()) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

Example using iter.next():

let i = 1;
let iter = containerClient.listBlobsFlat();
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 containerClient.listBlobsFlat().byPage({ maxPageSize: 20 })) {
  for (const blob of response.segment.blobItems) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

Example using paging with a marker:

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

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

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken

iterator = containerClient.listBlobsFlat().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 blob names
for (const blob of response.segment.blobItems) {
  console.log(`Blob ${i++}: ${blob.name}`);
}
setAccessPolicy(PublicAccessType, SignedIdentifier[], ContainerSetAccessPolicyOptions)

Sets the permissions for the specified container. The permissions indicate whether blobs in a container may be accessed publicly.

When you set permissions for a container, the existing permissions are replaced. If no access or containerAcl provided, the existing container ACL will be removed.

When you establish a stored access policy on a container, it may take up to 30 seconds to take effect. During this interval, a shared access signature that is associated with the stored access policy will fail with status code 403 (Forbidden), until the access policy becomes active.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-container-acl
setMetadata(Metadata, ContainerSetMetadataOptions)

Sets one or more user-defined name-value pairs for the specified container.

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

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-container-metadata
uploadBlockBlob(string, RequestBodyType, 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

Constructor Details

ContainerClient(string, PipelineLike)

Creates an instance of ContainerClient. This method accepts an URL pointing to a container. 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 ContainerClient(url: string, pipeline: PipelineLike)

Parameters

url

string

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

pipeline
PipelineLike

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

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

Creates an instance of ContainerClient. This method accepts an URL pointing to a container. 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 ContainerClient(url: string, credential?: StorageSharedKeyCredential | AnonymousCredential | TokenCredential, options?: StoragePipelineOptions)

Parameters

url

string

A URL string pointing to Azure Storage container, such as "https://myaccount.blob.core.windows.net/mycontainer". You can append a SAS if using AnonymousCredential, such as "https://myaccount.blob.core.windows.net/mycontainer?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.

ContainerClient(string, string, StoragePipelineOptions)

Creates an instance of ContainerClient.

new ContainerClient(connectionString: string, containerName: 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.

options
StoragePipelineOptions

Optional. Options to configure the HTTP pipeline.

Property Details

containerName

The name of the container.

string containerName

Property Value

string

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

StorageSharedKeyCredential | AnonymousCredential | TokenCredential

Inherited From StorageClient.credential

url

Encoded URL string value.

url: string

Property Value

string

Inherited From StorageClient.url

Method Details

create(ContainerCreateOptions)

Creates a new container under the specified account. If the container with the same name already exists, the operation fails.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container Naming rules: See https://learn.microsoft.com/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata

function create(options?: ContainerCreateOptions): Promise<ContainerCreateResponse>

Parameters

options
ContainerCreateOptions

Options to Container Create operation.

Example usage:

const containerClient = blobServiceClient.getContainerClient("<container name>");
const createContainerResponse = await containerClient.create();
console.log("Container was created successfully", createContainerResponse.requestId);

Returns

Promise<ContainerCreateResponse>

createIfNotExists(ContainerCreateOptions)

Creates a new container under the specified account. If the container with the same name already exists, it is not changed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container Naming rules: See https://learn.microsoft.com/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata

function createIfNotExists(options?: ContainerCreateOptions): Promise<ContainerCreateIfNotExistsResponse>

Parameters

options
ContainerCreateOptions

Returns

Promise<ContainerCreateIfNotExistsResponse>

delete(ContainerDeleteMethodOptions)

Marks the specified container for deletion. The container and any blobs contained within it are later deleted during garbage collection.

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

function delete(options?: ContainerDeleteMethodOptions): Promise<ContainerDeleteResponse>

Parameters

options
ContainerDeleteMethodOptions

Options to Container Delete operation.

Returns

Promise<ContainerDeleteResponse>

deleteBlob(string, ContainerDeleteBlobOptions)

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 deleteBlob(blobName: string, options?: ContainerDeleteBlobOptions): Promise<BlobDeleteResponse>

Parameters

blobName

string

options
ContainerDeleteBlobOptions

Options to Blob Delete operation.

Returns

Promise<BlobDeleteResponse>

Block blob deletion response data.

deleteIfExists(ContainerDeleteMethodOptions)

Marks the specified container for deletion if it exists. The container and any blobs contained within it are later deleted during garbage collection.

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

function deleteIfExists(options?: ContainerDeleteMethodOptions): Promise<ContainerDeleteIfExistsResponse>

Parameters

options
ContainerDeleteMethodOptions

Options to Container Delete operation.

Returns

Promise<ContainerDeleteIfExistsResponse>

exists(ContainerExistsOptions)

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

NOTE: use this function with care since an existing container might be deleted by other clients or applications. Vice versa new containers with the same name might be added by other clients or applications after this function completes.

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

Parameters

options
ContainerExistsOptions

Returns

Promise<boolean>

findBlobsByTags(string, ContainerFindBlobByTagsOptions)

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

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

Example using for await syntax:

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

Example using iter.next():

let i = 1;
const iter = containerClient.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 containerClient.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 = containerClient.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 = containerClient
  .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?: ContainerFindBlobByTagsOptions): PagedAsyncIterableIterator<FilterBlobItem, ContainerFindBlobsByTagsSegmentResponse, 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
ContainerFindBlobByTagsOptions

Options to find blobs by tags.

Returns

PagedAsyncIterableIterator<FilterBlobItem, ContainerFindBlobsByTagsSegmentResponse, PageSettings>

generateSasStringToSign(ContainerGenerateSasUrlOptions)

Only available for ContainerClient constructed with a shared key credential.

Generates string to sign for a Blob Container 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 generateSasStringToSign(options: ContainerGenerateSasUrlOptions): string

Parameters

options
ContainerGenerateSasUrlOptions

Optional parameters.

Returns

string

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

generateSasUrl(ContainerGenerateSasUrlOptions)

Only available for ContainerClient constructed with a shared key credential.

Generates a Blob Container 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: ContainerGenerateSasUrlOptions): Promise<string>

Parameters

options
ContainerGenerateSasUrlOptions

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.

getAccessPolicy(ContainerGetAccessPolicyOptions)

Gets the permissions for the specified container. The permissions indicate whether container data may be accessed publicly.

WARNING: JavaScript Date will potentially lose precision when parsing startsOn and expiresOn strings. For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z".

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

function getAccessPolicy(options?: ContainerGetAccessPolicyOptions): Promise<ContainerGetAccessPolicyResponse>

Parameters

options
ContainerGetAccessPolicyOptions

Options to Container Get Access Policy operation.

Returns

Promise<ContainerGetAccessPolicyResponse>

getAccountInfo(ContainerGetAccountInfoOptions)

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?: ContainerGetAccountInfoOptions): Promise<ContainerGetAccountInfoResponse>

Parameters

options
ContainerGetAccountInfoOptions

Options to the Service Get Account Info operation.

Returns

Promise<ContainerGetAccountInfoResponse>

Response data for the Service Get Account Info operation.

getAppendBlobClient(string)

Creates an AppendBlobClient

function getAppendBlobClient(blobName: string): AppendBlobClient

Parameters

blobName

string

An append blob name

Returns

AppendBlobClient

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

BlobBatchClient

A new BlobBatchClient object for this container.

getBlobClient(string)

Creates a BlobClient

function getBlobClient(blobName: string): BlobClient

Parameters

blobName

string

A blob name

Returns

BlobClient

A new BlobClient object for the given blob name.

getBlobLeaseClient(string)

Get a BlobLeaseClient that manages leases on the container.

function getBlobLeaseClient(proposeLeaseId?: string): BlobLeaseClient

Parameters

proposeLeaseId

string

Initial proposed lease Id.

Returns

BlobLeaseClient

A new BlobLeaseClient object for managing leases on the container.

getBlockBlobClient(string)

Creates a BlockBlobClient

function getBlockBlobClient(blobName: string): BlockBlobClient

Parameters

blobName

string

A block blob name

Example usage:

const content = "Hello world!";

const blockBlobClient = containerClient.getBlockBlobClient("<blob name>");
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);

Returns

BlockBlobClient

getPageBlobClient(string)

Creates a PageBlobClient

function getPageBlobClient(blobName: string): PageBlobClient

Parameters

blobName

string

A page blob name

Returns

PageBlobClient

getProperties(ContainerGetPropertiesOptions)

Returns all user-defined metadata and system properties for the specified container. The data returned does not include the container's list of blobs.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-container-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 listContainers method of BlobServiceClient using the includeMetadata option, which will retain their original casing.

function getProperties(options?: ContainerGetPropertiesOptions): Promise<ContainerGetPropertiesResponse>

Parameters

options
ContainerGetPropertiesOptions

Options to Container Get Properties operation.

Returns

Promise<ContainerGetPropertiesResponse>

listBlobsByHierarchy(string, ContainerListBlobsOptions)

Returns an async iterable iterator to list all the blobs by hierarchy. under the specified account.

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

Example using for await syntax:

for await (const item of containerClient.listBlobsByHierarchy("/")) {
  if (item.kind === "prefix") {
    console.log(`\tBlobPrefix: ${item.name}`);
  } else {
    console.log(`\tBlobItem: name - ${item.name}`);
  }
}

Example using iter.next():

let iter = containerClient.listBlobsByHierarchy("/", { prefix: "prefix1/" });
let entity = await iter.next();
while (!entity.done) {
  let item = entity.value;
  if (item.kind === "prefix") {
    console.log(`\tBlobPrefix: ${item.name}`);
  } else {
    console.log(`\tBlobItem: name - ${item.name}`);
  }
  entity = await iter.next();
}

Example using byPage():

console.log("Listing blobs by hierarchy by page");
for await (const response of containerClient.listBlobsByHierarchy("/").byPage()) {
  const segment = response.segment;
  if (segment.blobPrefixes) {
    for (const prefix of segment.blobPrefixes) {
      console.log(`\tBlobPrefix: ${prefix.name}`);
    }
  }
  for (const blob of response.segment.blobItems) {
    console.log(`\tBlobItem: name - ${blob.name}`);
  }
}

Example using paging with a max page size:

console.log("Listing blobs by hierarchy by page, specifying a prefix and a max page size");

let i = 1;
for await (const response of containerClient
  .listBlobsByHierarchy("/", { prefix: "prefix2/sub1/" })
  .byPage({ maxPageSize: 2 })) {
  console.log(`Page ${i++}`);
  const segment = response.segment;

  if (segment.blobPrefixes) {
    for (const prefix of segment.blobPrefixes) {
      console.log(`\tBlobPrefix: ${prefix.name}`);
    }
  }

  for (const blob of response.segment.blobItems) {
    console.log(`\tBlobItem: name - ${blob.name}`);
  }
}

function listBlobsByHierarchy(delimiter: string, options?: ContainerListBlobsOptions): PagedAsyncIterableIterator<({ kind: "prefix" } & BlobPrefix) | ({ kind: "blob" } & BlobItem), ContainerListBlobHierarchySegmentResponse, PageSettings>

Parameters

delimiter

string

The character or string used to define the virtual hierarchy

options
ContainerListBlobsOptions

Options to list blobs operation.

Returns

PagedAsyncIterableIterator<({ kind: "prefix" } & BlobPrefix) | ({ kind: "blob" } & BlobItem), ContainerListBlobHierarchySegmentResponse, PageSettings>

listBlobsFlat(ContainerListBlobsOptions)

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

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

Example using for await syntax:

// Get the containerClient before you run these snippets,
// Can be obtained from `blobServiceClient.getContainerClient("<your-container-name>");`
let i = 1;
for await (const blob of containerClient.listBlobsFlat()) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

Example using iter.next():

let i = 1;
let iter = containerClient.listBlobsFlat();
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 containerClient.listBlobsFlat().byPage({ maxPageSize: 20 })) {
  for (const blob of response.segment.blobItems) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

Example using paging with a marker:

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

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

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken

iterator = containerClient.listBlobsFlat().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 blob names
for (const blob of response.segment.blobItems) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

function listBlobsFlat(options?: ContainerListBlobsOptions): PagedAsyncIterableIterator<BlobItem, ContainerListBlobFlatSegmentResponse, PageSettings>

Parameters

options
ContainerListBlobsOptions

Options to list blobs.

Returns

PagedAsyncIterableIterator<BlobItem, ContainerListBlobFlatSegmentResponse, PageSettings>

An asyncIterableIterator that supports paging.

setAccessPolicy(PublicAccessType, SignedIdentifier[], ContainerSetAccessPolicyOptions)

Sets the permissions for the specified container. The permissions indicate whether blobs in a container may be accessed publicly.

When you set permissions for a container, the existing permissions are replaced. If no access or containerAcl provided, the existing container ACL will be removed.

When you establish a stored access policy on a container, it may take up to 30 seconds to take effect. During this interval, a shared access signature that is associated with the stored access policy will fail with status code 403 (Forbidden), until the access policy becomes active.

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

function setAccessPolicy(access?: PublicAccessType, containerAcl?: SignedIdentifier[], options?: ContainerSetAccessPolicyOptions): Promise<ContainerSetAccessPolicyResponse>

Parameters

access
PublicAccessType

The level of public access to data in the container.

containerAcl

SignedIdentifier[]

Array of elements each having a unique Id and details of the access policy.

options
ContainerSetAccessPolicyOptions

Options to Container Set Access Policy operation.

Returns

Promise<ContainerSetAccessPolicyResponse>

setMetadata(Metadata, ContainerSetMetadataOptions)

Sets one or more user-defined name-value pairs for the specified container.

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

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

function setMetadata(metadata?: Metadata, options?: ContainerSetMetadataOptions): Promise<ContainerSetMetadataResponse>

Parameters

metadata
Metadata

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

options
ContainerSetMetadataOptions

Options to Container Set Metadata operation.

Returns

Promise<ContainerSetMetadataResponse>

uploadBlockBlob(string, RequestBodyType, 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 uploadBlockBlob(blobName: string, body: RequestBodyType, contentLength: number, options?: BlockBlobUploadOptions): Promise<{ blockBlobClient: BlockBlobClient, response: BlockBlobUploadResponse }>

Parameters

blobName

string

Name of the block blob to create or update.

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 configure the Block Blob Upload operation.

Returns

Promise<{ blockBlobClient: BlockBlobClient, response: BlockBlobUploadResponse }>

Block Blob upload response data and the corresponding BlockBlobClient instance.