你当前正在访问 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 gb (GiB) blob 大小。
有关详细信息，请参阅使用 Azurite 模拟器进行本地 Azure 存储开发。
URI 参数
可以在请求 URI 上指定以下附加参数：
| 参数 | 说明 |
|---|---|
timeout |
可选。
timeout 参数以秒表示。 有关详细信息，请参阅 为 Blob 服务操作设置超时。 |
请求标头
下表描述了必需的和可选的请求标头：
| 请求标头 | 说明 |
|---|---|
Authorization |
必需。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅授权对 Azure 存储的请求。 |
Date 或 x-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 |
可选。 默认值为“空”。 如果设置了该值，它将设置 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 属性操作的响应包括内容处置标头。 |
x-ms-access-tier |
可选。 版本 2018-11-09 及更高版本。 指示在 Blob 上设置的层。 对于块 Blob，仅在版本 2018-11-09 及更高版本的 Blob 存储或常规用途 v2 帐户上支持此标头。 块 Blob 层 Hot的有效值为 、 Cool、 Cold和 Archive。
注意： 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 上设置的不可变性策略模式。 有效值为 unlocked 和 locked。 该值 unlocked 指示用户可以通过增加或减少 保留日期来 更改策略。 值 locked 指示禁止这些操作。 |
x-ms-legal-hold |
版本 2020-06-12 及更高版本。 指定要在 Blob 上设置的法定保留。 有效值是 true 和 false。 |
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 标记” 操作的授权要求。
重要
Microsoft 建议将 Microsoft Entra ID 与托管标识结合使用来授权对 Azure 存储的请求。 与共享密钥授权相比，Microsoft Entra ID提供更高的安全性和易用性。
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 操作：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- 最低特权内置角色：存储 Blob 数据参与者
若要详细了解如何使用 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 上调用 了 Put 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 标头，则覆盖 hot 或 cool blob 将从旧 Blob 继承该层。
计费
定价请求可能源自使用 Blob 存储 API 的客户端，可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。 这些请求按事务产生费用。 事务类型会影响帐户的收费方式。 例如，读取事务累算到与写入事务不同的计费类别。 下表显示了基于存储帐户类型的请求的计费类别 Put Block List ：
| 操作 | 存储帐户类型 | 计费类别 |
|---|---|---|
| 放置块列表 | 高级块 blob 标准常规用途 v2 标准常规用途 v1 |
写入操作 |
若要了解指定计费类别的定价，请参阅Azure Blob 存储定价。
另请参阅
了解块 Blob、追加 Blob 和页 Blob
授权对 Azure 存储的请求
状态和错误代码
Blob 服务错误代码
为 Blob 服务操作设置超时