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

accountName
containerName

The name of the container.
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.
createIfNotExists(ContainerCreateOptions)

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

Marks the specified container for deletion. The container and any blobs contained within it are later deleted during garbage collection.
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.
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.
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.
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.
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".
getAppendBlobClient(string)

Creates an <xref:AppendBlobClient>
getBlobBatchClient()

Creates a BlobBatchClient object to conduct batch operations.
getBlobClient(string)

Creates a <xref:BlobClient>
getBlobLeaseClient(string)

Get a <xref:BlobLeaseClient> that manages leases on the container.
getBlockBlobClient(string)

Creates a <xref:BlockBlobClient>
getPageBlobClient(string)

Creates a <xref: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.
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}, last modified - ${item.properties.lastModified}`);
  }
}

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}, last modified - ${item.properties.lastModified}`);
  }
  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}, last modified - ${blob.properties.lastModified}`);
  }
}

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}, last modified - ${blob.properties.lastModified}`);
  }
}
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.
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.
uploadBlockBlob(string, 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 <xref:BlockBlobClient.stageBlock> and <xref:BlockBlobClient.commitBlockList>.

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

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

accountName 

accountName: string

Property Value

string

containerName

The name of the container.

string containerName

Property Value

string

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

url

Encoded URL string value.

url: string

Property Value

string

Method Details

create(ContainerCreateOptions)

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

function create(options?: ContainerCreateOptions)

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.

function createIfNotExists(options?: ContainerCreateOptions)

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.

function delete(options?: ContainerDeleteMethodOptions)

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.

function deleteBlob(blobName: string, options?: ContainerDeleteBlobOptions)

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.

function deleteIfExists(options?: ContainerDeleteMethodOptions)

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)

Parameters

options
ContainerExistsOptions

Returns

Promise<boolean>

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.

function generateSasUrl(options: ContainerGenerateSasUrlOptions)

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".

function getAccessPolicy(options?: ContainerGetAccessPolicyOptions)

Parameters

options
ContainerGetAccessPolicyOptions

Options to Container Get Access Policy operation.

Returns

Promise<ContainerGetAccessPolicyResponse>

getAppendBlobClient(string)

Creates an <xref:AppendBlobClient>

function getAppendBlobClient(blobName: string)

Parameters

blobName

string

An append blob name

Returns

AppendBlobClient

getBlobBatchClient()

Creates a BlobBatchClient object to conduct batch operations.

function getBlobBatchClient()

Returns

BlobBatchClient

A new BlobBatchClient object for this container.

getBlobClient(string)

Creates a <xref:BlobClient>

function getBlobClient(blobName: string)

Parameters

blobName

string

A blob name

Returns

BlobClient

A new BlobClient object for the given blob name.

getBlobLeaseClient(string)

Get a <xref:BlobLeaseClient> that manages leases on the container.

function getBlobLeaseClient(proposeLeaseId?: string)

Parameters

proposeLeaseId

string

Initial proposed lease Id.

Returns

BlobLeaseClient

A new BlobLeaseClient object for managing leases on the container.

getBlockBlobClient(string)

Creates a <xref:BlockBlobClient>

function getBlockBlobClient(blobName: string)

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 <xref:PageBlobClient>

function getPageBlobClient(blobName: string)

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.

function getProperties(options?: ContainerGetPropertiesOptions)

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}, last modified - ${item.properties.lastModified}`);
  }
}

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}, last modified - ${item.properties.lastModified}`);
  }
  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}, last modified - ${blob.properties.lastModified}`);
  }
}

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}, last modified - ${blob.properties.lastModified}`);
  }
}

function listBlobsByHierarchy(delimiter: string, options?: ContainerListBlobsOptions)

Parameters

delimiter

string

The character or string used to define the virtual hierarchy

options
ContainerListBlobsOptions

Options to list blobs operation.

Returns

PagedAsyncIterableIterator<Object & BlobPrefix | Object & BlobItem, ContainerListBlobHierarchySegmentResponse>

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)

Parameters

options
ContainerListBlobsOptions

Options to list blobs.

Returns

PagedAsyncIterableIterator<BlobItem, ContainerListBlobFlatSegmentResponse>

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.

function setAccessPolicy(access?: PublicAccessType, containerAcl?: SignedIdentifier[], options?: ContainerSetAccessPolicyOptions)

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.

function setMetadata(metadata?: Metadata, options?: ContainerSetMetadataOptions)

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, 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 <xref:BlockBlobClient.stageBlock> and <xref:BlockBlobClient.commitBlockList>.

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

function uploadBlockBlob(blobName: string, body: HttpRequestBody, contentLength: number, options?: BlockBlobUploadOptions)

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<Object>

Block Blob upload response data and the corresponding BlockBlobClient instance.