AppendObject
更新时间：2026-09-20
接口描述
AppendObject 以追加写的方式上传文件。通过 AppendObject 操作创建的 Object 类型为 Appendable Object，可以对该 Object 追加数据；而通过 PutObject 上传的 Object 是 Normal Object，不可进行数据追加写。
说明：
- Appendable Object 大小限制为 0~48.8 T。
- AppendObject 接口在进行追加写时要求对该 Object 有写权限。
- 归档类型对象暂时不支持 AppendObject。
- 软链接不是可追加类型，会返回 HTTP 403 和
ObjectUnappendable错误。 - 当前版本下，多版本的 Bucket 不可进行 AppendObject 写入；对于历史写入的 AppendObject 可以读取。
请求
请求结构
首次上传 AppendObject 时，使用如下方法：
Http
1POST /<ObjectName>?append HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Date: <GMT Date>
4Authorization: <AuthorizationString>
5Content-Type: text/plain
6Content-Length: <ContentLength>
7x-bce-storage-class: <StorageClass>说明：
- 如该 Object 不存在，则创建一个 Appendable 的 Object。
- 如已存在同名的 Object，则上传的数据会覆盖原有的 Object，无论原有 Object 是否为 Appendable，均创建新的 Appendable Object。
- 允许创建或者覆盖一个长度为 0 的 Object。
如已上传部分 AppendObject，需要进行断点续传时，使用如下方法：
Http
1POST /<ObjectName>?append&offset=<OffsetSize> HTTP/1.1
2Host: <BucketName>.bj.bcebos.com
3Date: <GMT Date>
4Authorization: <AuthorizationString>
5Content-Type: text/plain
6Content-Length: <ContentLength>说明：
- 如要续传的 Object 不存在时，会返回错误码
404 NoSuchKey。- 如要续传的 Object 并不是 Appendable 的，则会返回
403 ObjectUnappendable。- 如值错误，则返回
409 OffsetIncorrect。- 如果不指定
offset会直接覆盖而不是默认追加在末尾。
请求头域
| 名称 | 类型 | 描述 | 是否必须 |
|---|---|---|---|
Date |
String | GMT 时间。 | 是 |
Authorization |
String | 请求签名信息。 | 是 |
Content-Type |
String | 请求 Body 的内容类型。 | 是 |
Content-Length |
Long Int | 请求 Body 的字节长度。 | 是 |
Cache-Control |
String | 浏览器 cache 机制设置。 | 否 |
Content-Disposition |
String | 指示浏览器如何显示附加的文件。 | 否 |
Content-MD5 |
String | RFC 2616 定义的 HTTP 请求内容的 MD5 摘要，可以通过携带该字段来验证保存在 BOS 侧的文件和用户预期的文件是否一致。 | 否 |
Expires |
String | GMT 时间，缓存失效时间。 | 否 |
x-bce-meta-* |
String | 用户自定义的 meta 信息。 | 否 |
x-bce-content-sha256 |
String | 本次所传数据的 SHA256 值；如果携带该字段，必须与实际内容匹配，否则 AppendObject 失败。 | 否 |
x-bce-content-crc32 |
String | 本次上传 Object 增量数据的 CRC32 值。 | 否 |
x-bce-storage-class |
String | 指定 Object 的存储类型，STANDARD_IA 代表低频存储，COLD 代表冷存储，ARCHIVE 代表归档存储，不指定时默认是标准存储类型；如果是多 AZ 类型 Bucket，MAZ_STANDARD_IA 代表多 AZ 低频存储，不指定时默认是 MAZ_STANDARD 多 AZ 标准存储类型，不能是其他取值。 |
否 |
x-bce-acl |
String | CannedACL 支持的 Header，用户设置 Object 的权限，取值为 private 和 public-read。 |
否 |
x-bce-grant-read |
String | CannedACL 支持的 Header，用户设置 Object 的读权限。支持多个 ID，以英文逗号分隔。 | 否 |
x-bce-grant-full-control |
String | CannedACL 支持的 Header，用户设置 Object 的 FULL_CONTROL 权限。支持多个 ID，以英文逗号分隔。 |
否 |
x-bce-server-side-encryption |
String | 服务端加密算法，当前支持 AES256 和 SM4 加密。 |
否 |
请求参数
| 名称 | 类型 | 参数位置 | 描述 | 是否必须 |
|---|---|---|---|---|
append |
String | Query 参数 | 代表对 Appendable Object 进行追加操作。取值可为空，例如 ?append。 |
是 |
offset |
Long Int | Query 参数 | 代表数据断点，即从该偏移量位置继续追加，取值为已实际上传的数据大小。 | 否 |
响应
响应头域
| 名称 | 类型 | 描述 | 是否必须 |
|---|---|---|---|
Content-MD5 |
String | 当前已成功上传的整个 Object 的 MD5 值。 | 是 |
x-bce-next-append-offset |
Long Int | 指明下次 AppendObject 请求时传入的 OffsetSize 值。该值为本次成功写入后 Object 的字节长度。 |
是 |
x-bce-content-crc32 |
String | 整个 Object 数据的 CRC32 值。 | 否 |
x-bce-content-crc32c |
String | 整个 Object 数据的 CRC32C 值。 | 否 |
ETag |
String | Append 后整个 Object 的 ETag 值。 | 是 |
响应参数
无。
使用细节说明
对于 Appendable 的 Object：
- 支持 AppendObject。
- 支持 RenameObject。
- 对一个已存在的 Appendable 的 Object 执行 PutObject，则 Appendable 的 Object 会被覆盖变成普通 Object。
- 对一个已存在的 Appendable 的 Object，在
<OffsetSize>值正确的情况下，追加一个长度为 0 的内容，不会改变 Object 的任何状态。 - 不建议并发操作同一个 Object，如一个线程执行 AppendObject，另一线程执行 PutObject、CopyObject、DeleteObject 等操作，可能会导致操作结果错误或操作失败。
- 如果对同一个 Object 做多线程或者多进程的并发追加，有可能因为并发过程的不确定性，返回
409 OffsetIncorrect失败。
对其他接口的影响
对于 GetObjectMeta 接口，当一个 Object 是 Appendable 时，返回的结果中会多如下两个字段：
| 名称 | 类型 | 描述 | 是否必须 |
|---|---|---|---|
x-bce-next-append-offset |
String | 当 Object 是由 AppendObject 接口创建的，会返回该字段，指明下次 AppendObject 时请求传入的 OffsetSize 的值。如果此时 Object 的大小是 5 G，offset 依然返回 5 G。 |
是 |
x-bce-object-type |
String | Object 的类型值。当 Object 是由 AppendObject 创建的，返回的值为 Appendable，其他情况暂不返回。 |
是 |
关于用户自定义的 x-bce-meta-*
- 在首次创建 Appendable Object（即 HTTP 请求起始行不带
offset参数）时，携带的x-bce-meta-*Header 会被存储，后续追加 AppendObject（即 HTTP 请求起始行携带offset参数）时的x-bce-meta-*Header 则默认被忽略。 - 由于 Appendable Object 支持 CopyObject，因此可以使用 CopyObject 自我拷贝以覆盖的形式来修改
x-bce-meta-*Header 的值。
数据校验
- 每次调用 AppendObject 的时候，如您上传 MD5 或者 SHA256 值，BOS 会对该次调用上传的数据进行校验。
- 每次数据追加结束，会返回已上传的整个 Object 的 MD5 值。
示例
请求示例
标准存储首次上传请求示例
Http
1POST /ObjectName?append HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Content-Type: text/plain
6Content-Length: 1134
7
8[1134 bytes of object data]低频/冷存储首次上传请求示例
Http
1POST /ObjectName?append HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Content-Type: text/plain
6Content-Length: 1134
7x-bce-storage-class: STANDARD_IA
8
9[1134 bytes of object data]标准存储续传请求示例
Http
1POST /ObjectName?append&offset=1134 HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Content-Type: text/plain
6Content-Length: 1900
7
8[1900 bytes of object data]低频/冷存储续传请求示例
Http
1POST /my-object?append&offset=1134 HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Content-Type: text/plain
6Content-Length: 1900
7x-bce-storage-class: STANDARD_IA
8
9[1900 bytes of object data]响应示例
首次上传响应示例
Http
1HTTP/1.1 200 OK
2x-bce-request-id: c31b374e-048a-41f0-9a9a-31bc4bc57509
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4ETag: "7c935a3947e3a684333480bd6b58b7c2"
5Content-Length: 0
6Content-MD5: RJBidEhsrgCKeDjvQjrF8A==
7x-bce-next-append-offset: 1134
8Connection: close
9Server: BceBos续传响应示例
Http
1HTTP/1.1 200 OK
2x-bce-request-id: 28a99102-d0a5-4252-a4ed-fa6dc801806b
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4ETag: "11257f81dce31a95f67f6e75018b77e3"
5Content-Length: 0
6Content-MD5: fJNaOUfjpoQzNIC9a1i3wg==
7x-bce-next-append-offset: 3034
8Connection: close
9Server: BceBos评价此篇文章