BlockBlobClient class

创建 BlockBlobClient 的实例。 此方法接受指向块 Blob 的编码 URL 或非编码 URL。 编码的 URL 字符串不会转义两次，只会转义 URL 路径中的特殊字符。 如果 Blob 名称包含？ 或 %，blob 名称必须在 URL 中编码。

new BlockBlobClient(url: string, pipeline: PipelineLike)

参数

创建 BlockBlobClient 的实例。 此方法接受指向块 Blob 的编码 URL 或非编码 URL。 编码的 URL 字符串不会转义两次，只会转义 URL 路径中的特殊字符。 如果 Blob 名称包含？ 或 %，blob 名称必须在 URL 中编码。

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

参数

创建 BlockBlobClient 的实例。

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

参数

accountName: string

属性值

Blob 与之关联的存储容器的名称。

string containerName

属性值

例如 AnonymousCredential、StorageSharedKeyCredential 或任何来自 @azure/identity 包的凭据，用于对服务的请求进行身份验证。 还可以提供实现 TokenCredential 接口的对象。 如果未指定，则使用 AnonymousCredential。

credential: StorageSharedKeyCredential | AnonymousCredential | TokenCredential

属性值

Blob 的名称。

string name

属性值

编码的 URL 字符串值。

url: string

属性值

中止挂起的异步复制 Blob作，并将目标 Blob 保留长度为零和完整元数据。 版本 2012-02-12 及更新。

function abortCopyFromURL(copyId: string, options?: BlobAbortCopyFromURLOptions)

参数

返回

将 Blob 异步复制到存储帐户中的目标。 此方法返回一个长时间运行的作轮询器，该轮询程序允许无限期等待，直到复制完成。 还可以通过在投票器上调用 cancelOperation 来取消副本，然后再取消该副本。 请注意，如果作在第一个请求中完成，并且尝试取消已完成的副本将导致引发错误，则不会调用 onProgress 回调。 在版本 2012-02-12 及更高版本中，复制 Blob作的源可以是任何 Azure 存储帐户中的已提交 Blob。 从版本 2015-02-21 开始，复制 Blob作的源可以是任何 Azure 存储帐户中的 Azure 文件。 只有 2012 年 6 月 7 日或之后创建的存储帐户才允许复制 Blob作从另一个存储帐户复制。

function beginCopyFromURL(copySource: string, options?: BlobBeginCopyFromURLOptions)

参数

返回

通过指定构成 Blob 的块 ID 列表来写入 Blob。 为了作为 Blob 的一部分写入，块必须在之前 <xref:stageBlock>作中成功写入服务器。 可以通过仅上传已更改的块，然后将新的和现有块提交到一起来调用 <xref:commitBlockList> 来更新 blob。 块列表中未指定并永久删除的任何块。

function commitBlockList(blocks: string[], options?: BlockBlobCommitBlockListOptions)

参数

返回

块 Blob 提交块列表作的响应数据。

创建 Blob 的只读快照。

function createSnapshot(options?: BlobCreateSnapshotOptions)

参数

返回

标记要删除的指定 Blob 或快照。 稍后在垃圾回收期间删除该 Blob。 请注意，若要删除 Blob，必须删除其所有快照。 可以使用“删除 Blob”作同时删除两者。

function delete(options?: BlobDeleteOptions)

参数

返回

标记指定的 blob 或快照以将其删除（如果存在）。 稍后在垃圾回收期间删除该 Blob。 请注意，若要删除 Blob，必须删除其所有快照。 可以使用“删除 Blob”作同时删除两者。

function deleteIfExists(options?: BlobDeleteOptions)

参数

返回

删除 Blob 上的不可变性策略。

function deleteImmutabilityPolicy(options?: BlobDeleteImmutabilityPolicyOptions)

参数

返回

从系统读取或下载 blob，包括其元数据和属性。 还可以调用 Get Blob 来读取快照。

• 在 Node.js中，数据在可读流 readableStreamBody 中返回
• 在浏览器中，数据在 promise blobBody 中返回

function download(offset?: number, count?: number, options?: BlobDownloadOptions)

参数

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

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

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

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

返回

仅在NODE.JS运行时中可用。 将 Azure Blob 并行下载到缓冲区。 偏移量和计数是可选的，如果未提供，则下载整个 Blob。

警告：由于 Node.js/V8 的限制，缓冲区只能支持 32 位系统上最多一千兆字节的文件或 64 位系统上的大约 2 GB 文件。 对于大于此大小的 Blob，请考虑 <xref:downloadToFile>。

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

参数

返回

仅在NODE.JS运行时中可用。 将 Azure Blob 并行下载到缓冲区。 偏移量和计数是可选的，如果未提供，则下载整个 Blob。

警告：由于 Node.js/V8 的限制，缓冲区只能支持 32 位系统上最多一千兆字节的文件或 64 位系统上的大约 2 GB 文件。 对于大于此大小的 Blob，请考虑 <xref:downloadToFile>。

function downloadToBuffer(offset?: number, count?: number, options?: BlobDownloadToBufferOptions)

参数

返回

仅在NODE.JS运行时中可用。 将 Azure Blob 下载到本地文件。 如果给定的文件路径已退出，则失败。 偏移量和计数是可选的，分别传递 0 和未定义以下载整个 Blob。

function downloadToFile(filePath: string, offset?: number, count?: number, options?: BlobDownloadOptions)

参数

返回

Blob 下载作的响应数据，但已将 readableStreamBody 设置为未定义，因为它的内容已读取并写入到指定路径的本地文件中。

如果此客户端表示的 Azure Blob 资源存在，则返回 true;否则为 false。 注意：请谨慎使用此函数，因为现有 Blob 可能被其他客户端或应用程序删除。 反之亦然，此函数完成后，其他客户端或应用程序可能会添加新的 Blob。

function exists(options?: BlobExistsOptions)

参数

返回

仅适用于使用共享密钥凭据构造的 BlobClient。 基于传入的客户端属性和参数生成 Blob 服务共享访问签名 （SAS） URI。 SAS 由客户端的共享密钥凭据签名。

function generateSasUrl(options: BlobGenerateSasUrlOptions)

参数

返回

由此客户端表示的资源的 URI 组成的 SAS URI，后跟生成的 SAS 令牌。

创建 AppendBlobClient 对象。

function getAppendBlobClient()

返回

获取管理 blob 上的租约的 <xref:BlobLeaseClient>。

function getBlobLeaseClient(proposeLeaseId?: string)

参数

返回

一个新的 BlobLeaseClient 对象，用于管理 Blob 上的租约。

创建 BlockBlobClient 对象。

function getBlockBlobClient()

返回

返回已使用指定的块列表筛选器作为块 Blob 的一部分上传的块列表。

function getBlockList(listType: BlockListType, options?: BlockBlobGetBlockListOptions)

参数

返回

块 Blob 获取块列表作的响应数据。

创建 PageBlobClient 对象。

function getPageBlobClient()

返回

返回 Blob 的所有用户定义的元数据、标准 HTTP 属性和系统属性。 它不返回 Blob 的内容。

function getProperties(options?: BlobGetPropertiesOptions)

参数

返回

获取与基础 Blob 关联的标记。

function getTags(options?: BlobGetTagsOptions)

参数

返回

仅在NODE.JS运行时中可用。 快速查询 JSON 或 CSV 格式的 Blob。

示例用法（Node.js）：

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

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

function query(query: string, options?: BlockBlobQueryOptions)

参数

返回

设置 Blob 上的层。 该作允许在高级存储帐户中的页 Blob 和 Blob 存储帐户中的块 Blob 上（仅限本地冗余存储）。 高级页 Blob 层确定 Blob 允许的大小、IOPS 和带宽。 块 Blob 层确定热/冷/存档存储类型。 此作不会更新 Blob 的 ETag。

function setAccessTier(tier: BlockBlobTier | PremiumPageBlobTier | string, options?: BlobSetTierOptions)

参数

返回

设置 Blob 上的系统属性。 如果未提供任何值，或者未为指定的 Blob HTTP 标头提供任何值，则清除不带值的这些 blob HTTP 标头。

function setHTTPHeaders(blobHTTPHeaders?: BlobHTTPHeaders, options?: BlobSetHTTPHeadersOptions)

参数

返回

在 Blob 上设置不可变性策略。

function setImmutabilityPolicy(immutabilityPolicy: BlobImmutabilityPolicy, options?: BlobSetImmutabilityPolicyOptions)

参数

返回

设置 Blob 的法律保留。

function setLegalHold(legalHoldEnabled: boolean, options?: BlobSetLegalHoldOptions)

参数

返回

将指定 Blob 的用户定义元数据设置为一个或多个名称值对。 如果未提供任何选项，或者参数中未定义任何元数据，将删除 blob 元数据。

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

参数

返回

设置基础 Blob 上的标记。 Blob 最多可以有 10 个标记。 标记键必须介于 1 到 128 个字符之间。 标记值必须介于 0 到 256 个字符之间。 有效的标记键和值字符包括小写字母和大写字母、数字（0-9）、空格（'）、加（'+'）、减号（'-'）、句点（'.'）、正斜杠（'/'）、冒号（'：'）、等号（'='）和下划线('_')。

function setTags(tags: Tags, options?: BlobSetTagsOptions)

参数

返回

将指定的块上传到块 blob 的“暂存区域”，以便稍后通过调用 commitBlockList 提交。

function stageBlock(blockId: string, body: HttpRequestBody, contentLength: number, options?: BlockBlobStageBlockOptions)

参数

返回

块 Blob 阶段块作的响应数据。

阶段阻止 URL作创建一个新块，作为从 URL 读取内容的 Blob 的一部分提交。 此 API 从版本 2018-03-28 开始提供。

function stageBlockFromURL(blockId: string, sourceURL: string, offset?: number, count?: number, options?: BlockBlobStageBlockFromURLOptions)

参数

返回

块 Blob 阶段块的 URL作的响应数据。

同步的“从 URL 复制”作将 Blob 或 Internet 资源复制到新的 Blob。 在复制完成之前，它不会返回响应。

function syncCopyFromURL(copySource: string, options?: BlobSyncCopyFromURLOptions)

参数

返回

创建一个新的块 Blob，其中从给定 URL 读取 Blob 的内容。 从 2020-04-08 版本开始，支持此 API。 URL 中的 Put Blob 不支持部分更新;现有 Blob 的内容将被新 Blob 的内容覆盖。 若要使用源 URL 对块 blob 的内容执行部分更新，请使用 <xref:stageBlockFromURL> 和 <xref:commitBlockList>。

function syncUploadFromURL(sourceURL: string, options?: BlockBlobSyncUploadFromURLOptions)

参数

返回

还原软删除 Blob 的内容和元数据以及任何关联的软删除快照。 仅在版本 2017-07-29 或更高版本上支持取消删除 Blob。

function undelete(options?: BlobUndeleteOptions)

参数

返回

创建新的块 blob，或更新现有块 Blob 的内容。 更新现有块 Blob 会覆盖 Blob 上的任何现有元数据。 不支持部分更新;现有 Blob 的内容将被新内容覆盖。 若要执行块 blob 的部分更新，请使用 <xref:stageBlock> 和 <xref:commitBlockList>。 这是一种非并行上传方法，请使用 <xref:uploadFile>、<xref:uploadStream> 或 <xref:uploadBrowserData>，以提高并发上传的性能。

function upload(body: HttpRequestBody, contentLength: number, options?: BlockBlobUploadOptions)

参数

返回

块 Blob 上传作的响应数据。

示例用法：

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

仅在浏览器中可用。 将浏览器 Blob/File/ArrayBuffer/ArrayBufferView 对象上传到块 Blob。

当缓冲区长度小于或等于 256MB 时，此方法将使用 1 个上传调用来完成上传。 否则，此方法将调用 <xref:stageBlock> 来上传块，最后调用 <xref:commitBlockList> 提交块列表。

要设置的常见 <xref:BlockBlobParallelUploadOptions.blobHTTPHeaders> 选项是 blobContentType，使浏览器能够基于文件类型提供功能。

function uploadBrowserData(browserData: Blob | ArrayBuffer | ArrayBufferView, options?: BlockBlobParallelUploadOptions)

参数

返回

Blob 上传作的响应数据。

将 Buffer（Node.js）/Blob（浏览器）/ArrayBuffer/ArrayBufferView 对象上传到 BlockBlob。 当数据长度不超过指定 <xref:BlockBlobParallelUploadOptions.maxSingleShotSize>（默认值为 <xref:BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES>），此方法将使用 1 个 <xref:upload> 调用来完成上传。 否则，此方法将调用 <xref:stageBlock> 来上传块，最后调用 <xref:commitBlockList> 提交块列表。

要设置的常见 <xref:BlockBlobParallelUploadOptions.blobHTTPHeaders> 选项是 blobContentType，使浏览器能够基于文件类型提供功能。

function uploadData(data: Buffer | Blob | ArrayBuffer | ArrayBufferView, options?: BlockBlobParallelUploadOptions)

参数

返回

仅在NODE.JS运行时中可用。 将块中的本地文件上传到块 Blob。

当文件大小小于或等于 256MB 时，此方法将使用 1 个上传调用来完成上传。 否则，此方法将调用 stageBlock 以上传块，最后调用 commitBlockList 以提交块列表。

function uploadFile(filePath: string, options?: BlockBlobParallelUploadOptions)

参数

返回

Blob 上传作的响应数据。

仅在NODE.JS运行时中可用。 将 Node.js 可读流上传到块 blob 中。

性能改进提示：

• 输入流 highWaterMark 最好使用 bufferSize 参数设置相同的值，这将避免 Buffer.concat（）作。

function uploadStream(stream: Readable, bufferSize?: number, maxConcurrency?: number, options?: BlockBlobUploadStreamOptions)

参数

返回

Blob 上传作的响应数据。

创建与源相同的新 BlockBlobClient 对象，但具有指定的快照时间戳。 提供“”将删除快照，并将 URL 返回到基本 Blob。

function withSnapshot(snapshot: string)

参数

返回

与源相同的新 BlockBlobClient 对象，但具有指定的快照时间戳。

创建一个新的 BlobClient 对象，该对象指向此 Blob 的版本。 提供“”将删除 versionId 并将客户端返回到基本 Blob。

function withVersion(versionId: string)

参数

返回

一个新的 BlobClient 对象，指向此 Blob 的版本。