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

放置块列表

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

可以通过调用 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

模拟存储服务请求

对模拟存储服务发出请求时,请将模拟器主机名和 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 (GiB) blob 大小。

有关详细信息,请参阅使用 Azurite 模拟器进行本地 Azure 存储开发

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 哈希值。 不会验证此哈希,因为在上传每个块时,已验证各个块的哈希。

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

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

自版本 2009-09-19 起,元数据名称必须遵守 C# 标识符的命名规则。
x-ms-encryption-scope 可选。 指示用于加密 Blob 的加密范围。 此值必须与用于加密所提交的所有块的加密范围匹配。 版本 2019-02-02 及更高版本中支持此标头。
x-ms-encryption-context 可选。 默认值为“Empty”。 如果设置了值,它将设置 Blob 系统元数据。 最大长度-1024。 仅当为帐户启用分层命名空间时有效。 2021-08-06 及更高版本中支持此标头。
x-ms-tags 可选。 在 Blob 上设置指定的查询字符串编码标记。 有关其他信息,请参阅 “备注 ”部分。 在版本 2019-12-12 及更高版本中受支持。
x-ms-lease-id:<ID> 如果 Blob 具有活动租约,则是必需的。 要在具有活动租约的 Blob 上执行此操作,请为此标头指定有效的租约 ID。
x-ms-client-request-id 可选。 提供客户端生成的不透明值,其大小为 1-kib (KiB) 配置存储分析日志记录时记录在分析日志中的字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。
x-ms-blob-content-disposition 可选。 设置 Blob 的 Content-Disposition 标头。 适用于版本 2013-08-15 及更高版本。

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

“获取 Blob”和“获取 Blob 属性”操作的响应包括 content-disposition 标头。
x-ms-access-tier 可选。 版本 2018-11-09 及更高版本。 指示在 Blob 上设置的层。 对于块 Blob,Blob 存储或常规用途 v2 帐户仅支持版本 2018-11-09 及更高版本的此标头。 块 Blob 层 Hot的有效值为 、 CoolColdArchive注意Cold 版本 2021-12-02 及更高版本支持层。 有关块 Blob 分层的详细信息,请参阅 热、冷和存档存储层
x-ms-immutability-policy-until-date 版本 2020-06-12 及更高版本。 指定要在 Blob 上设置的 保留日期 。 这是可以保护 Blob 不被修改或删除的日期。 遵循RFC1123格式。
x-ms-immutability-policy-mode 版本 2020-06-12 及更高版本。 指定要在 Blob 上设置的不可变性策略模式。 有效值为 unlockedlocked。 该值 unlocked 指示用户可以通过增加或减少 保留期(直到 日期)来更改策略。 值 locked 指示禁止这些操作。
x-ms-legal-hold 版本 2020-06-12 及更高版本。 指定要在 Blob 上设置的法定保留。 有效值是 truefalse
x-ms-expiry-option 可选。 版本 2023-08-03 及更高版本。 指定请求的到期日期选项,请参阅 ExpiryOption。 此标头对启用了分层命名空间的帐户有效。
x-ms-expiry-time 可选。 版本 2023-08-03 及更高版本。 指定 Blob 设置为过期的时间。 到期日期的格式因 x-ms-expiry-option而异。 有关详细信息,请参阅 ExpiryOption。 此标头对启用了分层命名空间的帐户有效。

expiryTime如果请求不包含 的新值,则不会清除 Blob 上已存在的expiryTime

此操作还支持仅当满足指定条件时才使用条件标头来提交阻止列表。 有关详细信息,请参阅 为 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  
x-ms-expiry-option: RelativeToNow
x-ms-expiry-time: 30000
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。 有关详细信息,请参阅 在标头中表示日期/时间值

修改 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 及更高版本。 如果使用指定的算法成功加密请求的内容,则此标头的值设置为 true 。 否则,该值将设置为 false
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 并且该值包含的可见 ASCII 字符不超过 1,024 个,则此标头的值等于标头的值。 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>  

授权

在 Azure 存储中调用任何数据访问操作时,都需要授权。 可以授权操作, Put Block List 如下所述。

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

Azure 存储支持使用 Microsoft Entra ID 来授权对 Blob 数据的请求。 使用 Microsoft Entra ID,可以使用 Azure 基于角色的访问控制 (Azure RBAC) 向安全主体授予权限。 安全主体可以是用户、组、应用程序服务主体或 Azure 托管标识。 安全主体由 Microsoft Entra ID 进行身份验证,以返回 OAuth 2.0 令牌。 然后可以使用令牌来授权对 Blob 服务发出请求。

若要详细了解如何使用 Microsoft Entra ID 授权,请参阅使用 Microsoft Entra ID 授权访问 blob

权限

下面列出了Microsoft Entra用户、组或服务主体调用Put Block List操作所需的 RBAC 操作,以及包含此操作的最小特权内置 Azure RBAC 角色:

若要详细了解如何使用 Azure RBAC 分配角色,请参阅 分配 Azure 角色以访问 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 大小:

服务版本 通过 Put Block) (的最大块大小 通过 Put Block List) (的最大 blob 大小 通过单个写入操作 (Put Blob 通过) 的最大 blob 大小
版本 2019-12-12 和更高版本 4,000 mb (MiB) 大约 190.7 tb (TiB) (4,000 MiB × 50,000 个块) 5,000 MiB
版本 2016-05-31 至 2019-07-07 100 MiB 大约 4.75 TiB (100 MiB × 50,000 块) 256 MiB
早于 2016-05-31 的版本 4 MiB 大约 195 GiB (4 MiB × 50,000 个块) 64 MiB

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

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

如果在上次成功Put Block操作后一周内没有成功调用 Put Block blob 或 Put Block List 对 Blob 调用,则任何未提交的块将被垃圾回收。 如果在 Blob 上调用 了“放置 Blob”,则会对任何未提交的块进行垃圾回收。

如果在标头中 x-ms-tags 提供了标记,则必须对其进行查询字符串编码。 标记键和值必须符合中指定的命名和长度要求 Set Blob Tags。 此外, 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(错误的请求)。

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

计费

定价请求可以源自使用 Blob 存储 API 的客户端,可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。 这些请求按事务产生费用。 事务类型会影响帐户的计费方式。 例如,读取事务应计为与写入事务不同的计费类别。 下表显示了基于存储帐户类型的请求的计费类别 Put Block List

操作 存储帐户类型 计费类别
放置块列表 高级块 blob
标准常规用途 v2
标准常规用途 v1
写入操作

若要了解指定计费类别的定价,请参阅Azure Blob 存储定价

另请参阅

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