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

追加块

Append Block 操作将新的数据块提交到现有追加 Blob 的末尾。

The Append Block operation is permitted only if the blob was created with x-ms-blob-type set to AppendBlob. Append Block 仅在版本 2015-02-21 或更高版本上受支持。

请求

可以按如下所示构造 Append Block 请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称。

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

针对模拟存储服务发出请求时,请指定仿真器主机名和Azure Blob 存储端口127.0.0.1:10000,后跟模拟的存储帐户名称。

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

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

URI 参数

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

请求标头

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

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息,请参阅授权请求Azure 存储
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权请求Azure 存储
x-ms-version 所有已授权请求都是必需的。 指定用于此请求的操作的版本。 有关详细信息,请参阅 Azure 存储服务的版本控制
Content-Length 必需。 块内容的长度(字节)。 块的大小必须小于或等于 4 MiB。

如果未提供长度,操作将失败并显示状态代码 411(需要长度)。
Content-MD5 可选。 块内容的 MD5 哈希值。 此哈希值用于在传输期间验证块的完整性。 指定此标头时,存储服务会对已到达内容的哈希值与此标头值进行比较。

请注意,此 MD5 哈希未随 Blob 一起存储。

如果两个哈希不匹配,操作将失败,错误代码为 400 (错误请求) 。
x-ms-content-crc64 可选。 追加块内容的 CRC64 哈希。 此哈希用于验证传输过程中追加块的完整性。 指定此标头时,存储服务会对已到达内容的哈希值与此标头值进行比较。

请注意,此 CRC64 哈希未随 Blob 一起存储。

如果两个哈希不匹配,操作将失败,错误代码为 400 (错误请求) 。

如果同时存在这两个 Content-MD5 标头 x-ms-content-crc64 ,则请求将失败,错误代码为 400。

版本 2019-02-02 或更高版本支持此标头。
x-ms-encryption-scope 可选。 指示用于加密请求内容的加密范围。 版本 2019-02-02 或更高版本支持此标头。
x-ms-lease-id:<ID> 如果 Blob 具有活动租约,则是必需的。 要在具有活动租约的 Blob 上执行此操作,请为此标头指定有效的租约 ID。
x-ms-client-request-id 可选。 提供客户端生成的不透明值,其中包含 1-kibibyte (KiB) 字符限制,该限制在配置日志记录时记录在 Azure Monitor 日志中。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅监视器Azure Blob 存储
x-ms-blob-condition-maxsize 可选条件标头。 指定追加 Blob 允许的最大长度(以字节为单位)。 Append Block如果操作导致 blob 超出该限制,或者 blob 大小已大于此标头中指定的值,则请求失败,错误代码为 412 (前置条件失败) 。
x-ms-blob-condition-appendpos 可选条件标头,仅用于 Append Block 操作。 一个数字指示要比较的字节偏移量。 Append Block 仅当追加位置等于此数字时,才成功。 如果不是,则请求失败,错误代码为 412 (前置条件失败) 。

此操作支持使用其他条件标头来确保仅当满足指定条件时 API 才成功。 有关详细信息,请参阅指定Azure 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

请求正文

请求正文包含块的内容。

示例请求

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
If-Match: "0x8CB172A360EC34B"  
  

响应

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

状态代码

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

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

响应头

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

响应标头 说明
ETag 包含 ETag 引号中的值。 客户端可以使用该值通过If-Match请求标头执行条件PUT操作。
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 此标头唯一标识已发出的请求,并可用于对请求进行故障排除。
x-ms-version 指示用于运行请求的 Blob 存储版本。 针对 2009-09-19 和更高版本发出的请求将返回此标头。
Date 一个 UTC 日期/时间值,该值指示启动响应的时间。 服务生成此值。
x-ms-blob-append-offset 仅针对追加操作返回此响应标头。 它返回块提交到的偏移量(以字节为单位)。
x-ms-blob-committed-block-count Blob 中存在的已提交块数。 可以使用此选项来控制可以执行更多追加操作。
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-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: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000  
  

授权

帐户所有者可以调用此操作。 具有写入此 Blob 或其容器权限的共享访问签名的任何人都可以调用此操作。

注解

Append Block 将块上传到现有追加 Blob 的末尾。 调用成功后,数据块立即可用。 块的大小最多可为 4 MiB。

Append Block 仅当 Blob 已存在时才成功。

使用 Append Block 上传的 Blob 不会公开块 ID。 无法针对追加 Blob 调用 “获取块列表 ”。 这样做会导致错误。

可以在请求中指定以下可选条件标头:

  • x-ms-blob-condition-appendpos:可以将此标头设置为客户端预期追加块的字节偏移量。 仅当当前偏移量与客户端指定的偏移量匹配时,请求才会成功。 否则,请求失败,错误代码为 412 (前置条件失败) 。

    使用单个编写器的客户端可以使用此标头来确定操作是否 Append Block 成功,尽管网络失败。

  • x-ms-blob-condition-maxsize:客户端可以使用此标头来确保追加操作不会增加 Blob 大小超出预期的最大大小(以字节为单位)。 如果条件失败,则请求失败,错误代码为 412 (前置条件失败) 。

每个块的大小可能不同,最大为 4 MiB。 每个追加 Blob 最多允许追加 50,000 个追加。 因此,追加 blob 的最大大小略高于 195 GiB (4 MiB X 50,000 块) 。

如果尝试上传大于 4 MiB 的块,该服务将返回错误代码 413 (请求实体太大) 。 服务还将在响应中返回有关错误的其他信息,包括允许的最大块大小(字节)。 如果尝试上传超过 50,000 个块,该服务将返回错误代码 409 (冲突) 。

如果 Blob 具有活动租约,则客户端必须在请求中指定有效租约 ID 才能向 Blob 中写入块。 如果客户端未指定租约 ID 或指定无效的租约 ID,则 Blob 存储返回错误代码 412 (前置条件失败) 。 如果客户端指定租约 ID,但 blob 没有活动租约,则 Blob 存储还会返回错误代码 412。

如果在现有块 blob 或页 Blob 上调用 Append Block ,服务将返回冲突错误。 如果调用 Append Block 不存在的 Blob,服务也会返回错误。

避免重复或延迟追加

在单个编写器方案中,客户端可以通过使用 *x-ms-blob-condition-appendpos 条件标头检查当前偏移量来避免重复追加或延迟写入。 客户端还可以通过使用条件检查 ETag 条件 If-Match来避免重复或延迟。

在多个编写器方案中,每个客户端都可以使用条件标头,但这可能不适合性能。 为了获得最高的并发追加吞吐量,应用程序应处理应用程序层中的冗余追加和延迟追加。 例如,应用程序可以在追加的数据中添加纪元或序列号。