你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

放置块列表

Put Block List操作通过指定构成 Blob 的块 ID 列表来写入 Blob。 若要作为 Blob 的一部分写入,必须在之前的 Put 块 操作中成功将块写入服务器。

可以调用Put Block List来更新 Blob,这样将仅上载已更改的块,然后一起提交新块和现有块。 为此,请指定是从提交的块列表或未提交的块列表提交块,还是提交块的最近上载版本,无论块可能属于哪个列表。

请求

可以按如下方式构建Put Block List请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称:

PUT 方法请求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1

模拟的存储服务 URI

在针对模拟的存储服务发出请求时,请将模拟器主机名和 BLOB 服务端口指定为 127.0.0.1:10000,后跟模拟的存储帐户名称:

PUT 方法请求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist HTTP/1.1

存储模拟器仅支持最大 2 GiB 的 Blob 大小。

有关详细信息,请参阅使用用于开发和测试的Azure 存储 Emulator

URI 参数

可以在请求 URI 上指定以下附加参数。

参数 说明
timeout 可选。 timeout 参数以秒表示。 有关详细信息,请参阅 为 Blob 服务操作设置超时

请求标头

下表介绍必需的和可选的请求标头。

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息,请参阅授权对Azure 存储的请求
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权对Azure 存储的请求
x-ms-version 所有授权请求都是必需的。 指定用于此请求的操作的版本。 有关详细信息,请参阅Azure 存储服务的版本控制
Content-Length 必需。 请求内容的长度(字节)。 此标头是指块列表的内容长度,而不是 Blob 本身的内容长度。
Content-MD5 可选。 请求内容的 MD5 哈希值。 此哈希值用于验证传输期间请求内容的完整性。 如果这两个哈希值不匹配,操作会失败,并显示错误代码 400(错误请求)。

此标头与请求内容相关联,而不与 Blob 本身的内容相关联。
x-ms-content-crc64 可选。 请求内容的 crc64 哈希。 此哈希值用于验证传输期间请求内容的完整性。 如果这两个哈希值不匹配,操作会失败,并显示错误代码 400(错误请求)。

此标头与请求内容相关联,而不与 Blob 本身的内容相关联。

如果存在 Content-MD5 和 x-ms-content-crc64 标头,则请求将失败并显示 400 (错误请求) 。

版本 2019-02-02 或更高版本支持此标头。
x-ms-blob-cache-control 可选。 设置 Blob 的缓存控制。 如果指定,则此属性存储在 Blob 中并通过读请求返回。

如果请求时未指定此属性,则在请求成功时将为 Blob 清除此属性。
x-ms-blob-content-type 可选。 设置 Blob 的内容类型。 如果指定,则此属性存储在 Blob 中并通过读请求返回。

如果未指定内容类型,则设置为默认类型,即 application/octet-stream
x-ms-blob-content-encoding 可选。 设置 Blob 的内容编码。 如果指定,则此属性存储在 Blob 中并通过读请求返回。

如果请求时未指定此属性,则在请求成功时将为 Blob 清除此属性。
x-ms-blob-content-language 可选。 设置 Blob 的内容语言。 如果指定,则此属性存储在 Blob 中并通过读请求返回。

如果请求未指定此属性,则在请求成功时将为 Blob 清除此属性。
x-ms-blob-content-md5 可选。 Blob 内容的 MD5 哈希值。 不验证此哈希,因为上传每个块时,会验证各个块的哈希。

Get Blob 操作返回 Content-MD5 响应标头中此标头的值。

如果请求时未指定此属性,则在请求成功时将为 Blob 清除此属性。
x-ms-meta-name:value 可选。 与 Blob 关联的用户定义名称/值对。

从版本 2009-09-19 开始,元数据名称必须遵循 C# 标识符的命名规则。
x-ms-encryption-scope 可选。 指示用于加密 Blob 的加密范围。 此值必须与用于加密所提交的所有块的加密范围匹配。 版本 2019-02-02 或更高版本支持此标头。
x-ms-tags 可选。 设置 Blob 上的给定查询字符串编码标记。 有关其他信息,请参阅“备注”。 版本 2019-12-12 及更新版本受支持。
x-ms-lease-id:<ID> 如果 Blob 具有活动租约,则是必需的。 要在具有活动租约的 Blob 上执行此操作,请为此标头指定有效的租约 ID。
x-ms-client-request-id 可选。 提供客户端生成的不透明值,该值具有 1 KiB 字符限制,在启用存储分析日志记录时记录在分析日志中。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅关于存储分析日志记录Azure 日志记录:使用日志跟踪存储请求
x-ms-blob-content-disposition 可选。 设置 Blob 的 Content-Disposition 标头。 适用于版本 2013-08-15 和更高版本。

Content-Disposition 标头字段传达有关如何处理响应负载的其他信息,也可用于附加更多元数据。 例如,如果设置为 attachment,则表明用户代理不应显示响应,而应显示“另存为”对话框。

Get BlobGet Blob 属性操作的响应包括内容处置标头。
x-ms-access-tier 可选。 版本 2018-11-09 及更新版本。 指示在 Blob 上设置的层。 对于块 Blob,Blob 存储或常规用途 v2 帐户仅支持版本 2018-11-09 及更新版本。 块 Blob 层Hot//CoolArchive的有效值为 。 有关块 Blob 分层的详细信息 ,请参阅热存储层、冷层和存档存储层
x-ms-immutability-policy-until-date 版本 2020-06-12 及更新。 指定要在 Blob 上设置的“保留日期”。 这是可保护 Blob 的修改或删除日期。 遵循 RFC1123 格式。
x-ms-immutability-policy-mode 版本 2020-06-12 及更新。 指定要在 Blob 上设置的不可变策略模式。 有效值为 unlocked/locked. unlocked 指示用户可以通过增加或减少保留日期来更改策略。 locked 指示禁止这些操作。
x-ms-legal-hold 版本 2020-06-12 及更新。 指定要在 Blob 上设置的法律保留,有效值为 true/false

此操作还支持仅当满足指定条件时才使用条件标头来提交阻止列表。 有关详细信息,请参阅为 Blob 服务操作指定条件标头

请求标头 (客户提供的加密密钥)

从版本 2019-02-02 开始,可以在请求中指定以下标头,以使用客户提供的密钥加密 Blob。 使用客户提供的密钥 (加密,并且) 对应的标头集是可选的。

请求标头 说明
x-ms-encryption-key 必需。 Base64 编码的 AES-256 加密密钥。
x-ms-encryption-key-sha256 必需。 加密密钥的 Base64 编码 SHA256 哈希。
x-ms-encryption-algorithm: AES256 必需。 指定要用于加密的算法。 此标头的值必须为 AES256

请求正文

在请求正文中,可以指定 BLOB 服务应在哪个块列表中检查请求的块。 这样,可以通过插入、替换或删除单个块来更新现有 Blob,而不是重新加载整个 Blob。 上载已更改的块之后,可以通过将新块与要保留的现有块一起提交,提交 Blob 的新版本。

要更新 Blob,可以指定服务是应在提交的块列表、未提交的块列表还是先后在未提交的块列表和提交的块列表中查找块 ID。 要指示使用哪一方法,请在请求正文的适当 XML 元素中指定块 ID,如下所示:

  • Committed 元素中指定块 ID,以指示 BLOB 服务应仅在提交的块列表中搜索指定的块。 如果在提交的块列表中未找到该块,则它不会写为 Blob 的一部分,并且 BLOB 服务将返回状态代码 400(错误请求)。

  • Uncommitted 元素中指定块 ID,以指示 BLOB 服务应仅在未提交的块列表中搜索指定的块。 如果在未提交的块列表中未找到该块,则它不会写为 Blob 的一部分,并且 BLOB 服务将返回状态代码 400(错误请求)。

  • Latest 元素中指定块 ID,以指示 BLOB 服务应先搜索未提交的块列表。 如果在未提交的列表中未找到该块,则该块的版本是最新的,应写入 Blob 中。 如果在未提交的列表中未找到指定的块,则服务应在提交的块列表中搜索该块,并在找到后将它写入 Blob 中。

此版本Put Block List的请求正文使用以下 XML 格式:

<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Committed>first-base64-encoded-block-id</Committed>  
  <Uncommitted>second-base64-encoded-block-id</Uncommitted>  
  <Latest>third-base64-encoded-block-id</Latest>  
  ...  
</BlockList>  
  

示例请求

为说明Put Block List,假定你已上载三个要提交的块。 以下示例通过指示应使用各块的最新版本来提交新 Blob。 不必知道这些块是否已提交。

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1  
  
Request Headers:  
x-ms-date: Wed, 31 Aug 2011 00:17:43 GMT  
x-ms-version: 2011-08-18  
Content-Type: text/plain; charset=UTF-8  
Authorization: SharedKey myaccount:DJ5QZSVONZ64vAhnN/wxcU+Pt5HQSLAiLITlAU76Lx8=  
Content-Length: 133  
  
Request Body:  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Latest>AAAAAA==</Latest>  
  <Latest>AQAAAA==</Latest>  
  <Latest>AZAAAA==</Latest>  
</BlockList>  
  

接下来,假定要更新 Blob。 新 Blob 将包含以下更改:

  • ID 为 ANAAAA== 的新块。 必须先上传此块,并调用 Put Block,并将显示在未提交的阻止列表中,直到调用。Put Block List

  • ID 为 AZAAAA== 的块的已更新版本。 必须先上传此块,并调用 Put Block,并将显示在未提交的阻止列表中,直到调用。Put Block List

  • 删除 ID 为 AAAAAA== 的块。 如果此块未包含在对Put Block List的下一个调用中,则该块实际上将从 Blob 中删除。

以下示例说明如何调用Put Block List来更新 Blob:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1  
  
Request Headers:  
x-ms-date: Wed, 31 Aug 2009 00:17:43 GMT  
x-ms-version: 2011-08-18  
Content-Type: text/plain; charset=UTF-8  
Authorization: SharedKey myaccount:DJ5QZSVONZ64vAhnN/wxcU+Pt5HQSLAiLITlAU76Lx8=  
Content-Length: 133  
  
Request Body:  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Uncommitted>ANAAAA==</Uncommitted>  
  <Committed>AQAAAA==</Committed>  
  <Uncommitted>AZAAAA==</Uncommitted>  
</BlockList>  
  

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

此操作成功后返回状态代码 201(已创建)。

有关状态代码的信息,请参阅 “状态”和“错误代码”。

响应标头

此操作的响应包括以下标头。 该响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范

响应 说明
ETag 实体标记中包含一个值,客户端可以使用该值通过使用 GET/PUT 请求标头执行条件 If-Match 操作。 如果请求版本为 2011-08-18 和更高版本,ETag 值将用引号引起来。
Last-Modified 上次修改 Blob 的日期/时间。 日期格式遵循 RFC 1123。 有关详细信息,请参阅 标头中Date-Time值的表示形式

修改 Blob 的任何操作将会更改 Blob 的上次修改时间,包括更新 Blob 的元数据或属性。
Content-MD5 返回此标头是为了客户端可以检查消息内容完整性。 此标头指请求的内容,在此例中意味着块列表而不是 Blob 本身的内容。 对于版本 2019-02-02 或更高版本,仅当请求具有此标头时,才会返回此标头。
x-ms-content-crc64 对于版本 2019-02-02 及更高版本,将返回此标头,以便客户端可以检查消息内容完整性。 此标头指请求的内容,在此例中意味着块列表而不是 Blob 本身的内容。

当请求中不存在标头时 Content-md5 ,将返回此标头。
x-ms-request-id 此标头唯一地标识发出的请求,并且可用于解决请求问题。 有关详细信息,请参阅 API 操作疑难解答
x-ms-version 指示用于执行请求的 BLOB 服务的版本。 针对 2009-09-19 和更高版本发出的请求将返回此标头。
Date 服务生成的 UTC 日期/时间值指示启动响应的时间。
x-ms-request-server-encrypted: true/false 版本 2015-12-11 或更高版本。 如果请求的内容使用指定的算法成功加密,则false此标头的值设置为true否则为 。
x-ms-encryption-key-sha256 版本 2019-02-02 或更高版本。 如果请求使用客户提供的密钥进行加密,则返回此标头,因此客户端可以确保使用提供的密钥成功加密请求的内容。
x-ms-encryption-scope 版本 2019-02-02 或更高版本。 如果请求使用了加密范围,则返回此标头,因此客户端可以确保使用加密范围成功加密请求的内容。
x-ms-version-id: <DateTime> 版本 2019-12-12 及更新版本。 此标头返回唯一标识 blob 的不透明 DateTime 值。 此标头的值指示 Blob 的版本,并可用于后续请求来访问 Blob。
x-ms-client-request-id 此标头可用于对请求和相应的响应进行故障排除。 如果标头存在于请求中,则此标头的值等于标头的值 x-ms-client-request-id ,并且该值最多为 1024 个可见 ASCII 字符。 x-ms-client-request-id如果请求中不存在标头,则响应中将不会显示此标头。

示例响应

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 00:17:44 GMT  
ETag: “0x8CB172A360EC34B”  
Last-Modified: Sun, 25 Sep 2011 00:17:43 GMT  
x-ms-version: 2011-08-18  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-version-id: <DateTime>  

授权

此操作可由帐户所有者调用执行,也可由有权向此 Blob 或其容器写入数据并具有共享访问签名的任何人执行。

如果请求使用请求标头指定标记 x-ms-tags ,则调用方必须满足 “设置 Blob 标记 ”操作的授权要求。

备注

Put Block List操作强制应用创建 Blob 时合并块的顺序。

在块列表中可多次指定同一块 ID。 如果多次指定块 ID,则它将在最终提交 Blob 的块列表中的每个位置中表示字节范围。 如果块 ID 在列表中出现多次,则必须在同一块列表中指定块 ID 的两个实例。 换句话说,必须在 Committed 元素、Uncommitted 元素或 Latest 元素中指定两个实例。

利用Put Block List,可以通过插入、更新或删除各块来修改现有 Blob,而不用重新上载整个 Blob。 创建新 Blob 或更新现有 Blob 的内容时,可以从当前提交的块列表和未提交的块列表指定块 ID。 这样,可以通过从未提交的块列表中指定几个新块以及已提交块列表中的其余块(已是现有 Blob 的一部分)来更新 Blob。

如果在 Latest 元素中指定了块 ID,并且提交和未提交的块列表中存在同一块 ID,则Put Block List将从未提交的块列表提交该块。 如果块 ID 存在于提交的块列表,但不存在于未提交的块列表中,则Put Block List将从提交的块列表提交该块。

块 Blob 中的每个块的大小可能不同。 块 Blob 最多可以包含 50,000 个提交的块。 可能与 Blob 关联的未提交块的最大数目为 100,000。 下表描述了服务版本允许的最大块和 Blob 大小:

服务版本 最大块大小(通过放置块) 最大 blob 大小(通过放置块列表) 通过单个写入操作的最大 blob 大小(通过放置 Blob)
版本 2019-12-12 和更高版本 4000 MiB 大约 190.7 TiB(4000 MiB X 50,000 块) 5000 MiB(预览版)
版本 2016-05-31 到版本 2019-07-07 100 MiB 大约 4.75 TiB(100 MiB X 50,000 块) 256 MiB
2016-05-31 之前的版本 4 MiB 大约 195 GiB(4 MiB X 50,000 块) 64 MiB

调用Put Block List来更新现有 Blob 时,将覆盖 Blob 的现有属性和元数据。 但是,所有现有快照将随 Blob 保留。 可以使用条件请求标头指定仅在满足指定条件时才执行该操作。

如果Put Block List操作因缺少块而失败,则需要上载缺少的块。

如果在上次成功Put Block操作后的一周内 Blob 中没有成功调用Put Block ListPut Block,则将对所有未提交的块执行进行垃圾收集。 如果在 Blob 上调用 Put Blob ,则会垃圾回收任何未提交的块。

如果在标头中 x-ms-tags 提供了标记,则必须对标记进行查询字符串编码。 标记键和值必须符合“设置 Blob 标记”中指定的命名和长度要求。 此外, x-ms-tags 标头可能包含最大大小为 2 KiB 的标记。 如果需要更多标记,请使用 “设置 Blob 标记 ”操作。

如果 Blob 具有活动租约,则客户端必须在请求中指定有效租约 ID 才能提交块列表。 如果客户端不指定租约 ID,或指定无效的租约 ID,则 BLOB 服务将返回状态码 412(不满足前提条件)。 如果客户端指定了一个租约 ID,但 Blob 没有活动租约,则 BLOB 服务也将返回状态码 412(不满足前提条件)。 如果客户端对 Blob 指定的租约 ID 尚不存在,Blob 服务将对针对版本 2013-08-15 和更高版本提交的请求返回状态代码 412(不满足前提条件);对于以前的版本,Blob 服务将返回状态代码 201(已创建)。

如果 Blob 具有活动租约,并调用Put Block List来更新 Blob,则租约将保留在更新的 Blob 中。

Put Block List 仅适用于块 Blob。 在页 Blob 上调用Put Block List将导致返回状态代码 400(错误的请求)。

如果未提供 x-ms-access-tier 标头,覆盖存档的 Blob 将失败,并且覆盖 hot/cool blob 将从旧 Blob 继承该层。

另请参阅

了解块 Blob、追加 Blob 和页 Blob
授权请求Azure 存储
状态和错误代码
Blob 服务错误代码
为 Blob 服务操作设置超时