ContainerClient class

建立 ContainerClient 的實例。 此方法接受指向容器的 URL。 編碼的 URL 字串不會逸出兩次，只會逸出 URL 路徑中的特殊字元。 如果 Blob 名稱包含 ？ 或 %，Blob 名稱必須在 URL 中編碼。

new ContainerClient(url: string, pipeline: PipelineLike)

參數

建立 ContainerClient 的實例。 此方法接受指向容器的 URL。 編碼的 URL 字串不會逸出兩次，只會逸出 URL 路徑中的特殊字元。 如果 Blob 名稱包含 ？ 或 %，Blob 名稱必須在 URL 中編碼。

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

參數

建立 ContainerClient 的實例。

new ContainerClient(connectionString: string, containerName: string, options?: StoragePipelineOptions)

參數

容器的名稱。

string containerName

屬性值

accountName: string

屬性值

繼承自 StorageClient.accountName

例如 AnonymousCredential、StorageSharedKeyCredential 或任何來自 @azure/identity 套件的認證，以驗證對服務的要求。 您也可以提供實作 TokenCredential 介面的物件。 如果未指定，則會使用 AnonymousCredential。

credential: StorageSharedKeyCredential | AnonymousCredential | TokenCredential

屬性值

繼承自 StorageClient.credential

編碼的 URL 字串值。

url: string

屬性值

繼承自 StorageClient.url

在指定的帳戶下建立新的容器。 如果已有相同名稱的容器存在，則作業會失敗。

請參閱 https://docs.microsoft.com/en-us/rest/api/storageservices/create-container 命名規則：請參閱 https://learn.microsoft.com/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata

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

參數

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

傳回

在指定的帳戶下建立新的容器。 如果已有相同名稱的容器存在，則不會變更。

請參閱 https://docs.microsoft.com/en-us/rest/api/storageservices/create-container 命名規則：請參閱 https://learn.microsoft.com/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata

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

參數

傳回

標記要刪除的指定容器。 容器及其內含的任何 Blob 稍後會在垃圾收集期間刪除。

請參閱 https://docs.microsoft.com/en-us/rest/api/storageservices/delete-container

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

參數

傳回

標示要刪除的指定 Blob 或快照集。 Blob 稍後會在垃圾收集期間刪除。 請注意，若要刪除 Blob，您必須刪除其所有快照集。 您可以使用刪除 Blob 作業同時刪除兩者。

請參閱 https://docs.microsoft.com/en-us/rest/api/storageservices/delete-blob

function deleteBlob(blobName: string, options?: ContainerDeleteBlobOptions): Promise<BlobDeleteResponse>

參數

傳回

封鎖 Blob 刪除響應數據。

如果指定的容器存在，則標記要刪除的容器。 容器及其內含的任何 Blob 稍後會在垃圾收集期間刪除。

請參閱 https://docs.microsoft.com/en-us/rest/api/storageservices/delete-container

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

參數

傳回

如果此用戶端所代表的 Azure 容器資源存在，則傳回 true;否則為 false。

注意：請小心使用此函式，因為其他用戶端或應用程式可能會刪除現有的容器。 反之亦然，具有相同名稱的新容器可能會在此函式完成之後由其他用戶端或應用程式新增。

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

參數

傳回

傳回異步反覆運算器，以在指定的容器下尋找具有指定標籤的所有 Blob。

.byPage（） 會傳回異步可迭代反覆運算器，以列出分頁中的 Blob。

使用 for await 語法的範例：

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

使用 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();
}

使用 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}`);
    }
  }
}

使用分頁搭配標記的範例：

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>

參數

傳回

僅適用於使用共用密鑰認證建構的 ContainerClient。

根據傳入的用戶端屬性和參數，產生要簽署 Blob 容器服務共用存取簽章 （SAS） URI 的字串。 SAS 是由客戶端的共用金鑰認證所簽署。

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

function generateSasStringToSign(options: ContainerGenerateSasUrlOptions): string

參數

傳回

由此用戶端所代表資源的 URI 所組成的 SAS URI，後面接著產生的 SAS 令牌。

僅適用於使用共用密鑰認證建構的 ContainerClient。

根據傳入的用戶端屬性和參數，產生 Blob 容器服務共用存取簽章 （SAS） URI。 SAS 是由客戶端的共用金鑰認證所簽署。

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

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

參數

傳回

由此用戶端所代表資源的 URI 所組成的 SAS URI，後面接著產生的 SAS 令牌。

根據傳入的用戶端屬性和參數，產生要簽署 Blob 容器服務共用存取簽章 （SAS） URI 的字串。 SAS 是由輸入使用者委派密鑰所簽署。

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

function generateUserDelegationSasStringToSign(options: ContainerGenerateSasUrlOptions, userDelegationKey: UserDelegationKey): string

參數

傳回

由此用戶端所代表資源的 URI 所組成的 SAS URI，後面接著產生的 SAS 令牌。

根據傳入的用戶端屬性和參數，產生 Blob 容器服務共用存取簽章 （SAS） URI。 SAS 是由輸入使用者委派密鑰所簽署。

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

function generateUserDelegationSasUrl(options: ContainerGenerateSasUrlOptions, userDelegationKey: UserDelegationKey): Promise<string>

參數

傳回

由此用戶端所代表資源的 URI 所組成的 SAS URI，後面接著產生的 SAS 令牌。

取得指定容器的許可權。 許可權會指出是否可以公開存取容器數據。

警告：剖析 startOn 和 expiresOn 字串時，JavaScript 日期可能會失去精確度。 例如，新的 Date（“2018-12-31T03：44：23.8827891Z”）將會取得 “2018-12-31T03：44：23.882Z”。

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

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

參數

傳回

取得帳戶資訊作業會傳回指定帳戶的 SKU 名稱和帳戶種類。 從 2018-03-28 版開始的服務版本，即可取得帳戶資訊作業。

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

function getAccountInfo(options?: ContainerGetAccountInfoOptions): Promise<ContainerGetAccountInfoResponse>

參數

傳回

服務取得帳戶資訊作業的響應數據。

建立 AppendBlobClient

function getAppendBlobClient(blobName: string): AppendBlobClient

參數

傳回

建立 BlobBatchClient 物件來執行批次作業。

請參閱 https://docs.microsoft.com/en-us/rest/api/storageservices/blob-batch

function getBlobBatchClient(): BlobBatchClient

傳回

這個容器的新 BlobBatchClient 物件。

建立 BlobClient

function getBlobClient(blobName: string): BlobClient

參數

傳回

指定 Blob 名稱的新 BlobClient 物件。

取得管理容器租用的 BlobLeaseClient。

function getBlobLeaseClient(proposeLeaseId?: string): BlobLeaseClient

參數

傳回

用於管理容器租用的新 BlobLeaseClient 物件。

建立 BlockBlobClient

function getBlockBlobClient(blobName: string): BlockBlobClient

參數

const content = "Hello world!";

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

傳回

建立 PageBlobClient

function getPageBlobClient(blobName: string): PageBlobClient

參數

傳回

傳回指定容器的所有使用者定義元數據和系統屬性。 傳回的數據不包含容器的 Blob 清單。

請參閱 https://docs.microsoft.com/en-us/rest/api/storageservices/get-container-properties

警告：回應中傳回的 metadata 物件會以小寫表示，即使它們原本包含大寫字元也一樣。 這與使用 listContainers 選項 BlobServiceCl ient includeMetadata 方法所傳回的元數據索引鍵不同，這會保留其原始大小寫。

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

參數

傳回

傳回異步可反覆運算迭代器，依階層列出所有 Blob。 在指定的帳戶下。

.byPage（） 會傳回可同步反覆運算器，以依頁面階層列出 Blob。

使用 for await 語法的範例：

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

使用 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();
}

使用 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}`);
  }
}

使用頁面大小上限的分頁範例：

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>

參數

傳回

傳回異步反覆運算器，以列出指定帳戶下的所有 Blob。

.byPage（） 會傳回異步可迭代反覆運算器，以列出分頁中的 Blob。

使用 for await 語法的範例：

// 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}`);
}

使用 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();
}

使用 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}`);
  }
}

使用分頁搭配標記的範例：

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>

參數

傳回

支援分頁的 asyncIterableIterator。

設定指定容器的許可權。 許可權會指出容器中的 Blob 是否可以公開存取。

當您設定容器的許可權時，會取代現有的許可權。 如果未提供任何存取權或 containerAcl，則會移除現有的容器 ACL。

當您在容器上建立預存存取原則時，最多可能需要 30 秒才會生效。 在此間隔期間，與預存存取原則相關聯的共用存取簽章將會失敗，狀態代碼為 403（禁止），直到存取原則變成作用中為止。

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

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

參數

傳回

設定指定容器的一或多個使用者定義名稱/值組。

如果未提供任何選項，或參數中未定義任何元數據，則會移除容器元數據。

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

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

參數

傳回

建立新的區塊 Blob，或更新現有區塊 Blob 的內容。

更新現有的區塊 Blob 會覆寫 Blob 上任何現有的元數據。 不支援部分更新;現有 Blob 的內容會以新內容覆寫。 若要執行區塊 Blob 的部分更新，請使用 stageBlock 和 commitBlockList。

這是非平行上傳方法，請使用 uploadFile、uploadStream 或 uploadBrowserData，以取得並行上傳的更佳效能。

請參閱 https://docs.microsoft.com/rest/api/storageservices/put-blob

function uploadBlockBlob(blobName: string, body: RequestBodyType, contentLength: number, options?: BlockBlobUploadOptions): Promise<{ blockBlobClient: BlockBlobClient, response: BlockBlobUploadResponse }>

參數

傳回

封鎖 Blob 上傳回應數據和對應的 BlockBlobClient 實例。