PutObject
更新时间：2026-09-18
接口描述
此接口用于向指定的 Bucket 上传一个文件，请求者必须具有 Write 权限。请求需要携带 Authorization 鉴权信息。在 PutObject 前需要确保对应的 Bucket 已经存在，BOS 支持 Object 文件的长度范围是 0 Byte～5 GB。如果需要上传大于 5 GB 的文件，请参考 分块上传指南。
请求
请求结构
Http
1PUT /{ObjectName} HTTP/1.1
2Host: {BucketName}.bj.bcebos.com
3Date: {Date}
4Authorization: {AuthorizationString}
5Content-Type: text/plain
6Content-Length: {ContentLength}
7x-bce-storage-class: {StorageClass}请求 Body 为待上传的 Object 数据，Body 长度必须与 Content-Length 一致。
请求参数
| 参数名 | 类型 | 位置 | 是否必需 | 描述 |
|---|---|---|---|---|
ObjectName |
String | Path | 是 | Object 名称。可以包含 /，例如 work/test/123.txt，用于模拟目录结构。 |
ObjectData |
Binary | Body | 是 | 待上传的 Object 数据，长度必须与 Content-Length 一致，支持 0 Byte～5 GB。 |
无特殊 Query 参数。
请求头域
| 名称 | 类型 | 描述 | 是否必需 |
|---|---|---|---|
Host |
String | BOS 访问域名，格式为 {BucketName}.bj.bcebos.com。 |
是 |
Date |
String | 请求时间，使用 HTTP 日期格式。 | 是 |
Authorization |
String | 请求签名字符串，用于鉴权。 | 是 |
Content-Type |
String | 上传 Object 的内容类型。如不指定，BOS 会自动识别；若无法识别则默认为 application/octet-stream。 |
否 |
Content-Length |
Integer | 请求 Body 长度，单位为 Byte。 | 是 |
Cache-Control |
String | 下载 Object 的 Cache 设置，常见可取值为 private、no-cache、max-age、must-revalidate。 |
否 |
Content-Disposition |
String | 设置浏览器是否下载，可取值为 inline、attachment; filename="download.txt"。 |
否 |
Content-MD5 |
String | RFC 2616 定义的 HTTP 请求内容的 MD5 摘要，可以通过携带该字段来验证保存在 BOS 侧的文件和用户预期的文件是否一致。 | 否 |
Expires |
String | 用于设置下载 Object 时的缓存失效时间，如果不做时间设置，BOS 会默认设置缓存失效时间为三天。 | 否 |
If-Match |
String | 只有 BOS 侧的 Object 的 ETag 与 If-Match 提供的值一致时，本次请求才会成功，否则返回 412 Precondition Failed 错误。 |
否 |
If-None-Match |
String | 只有 BOS 侧的 Object 的 ETag 与 If-None-Match 提供的值不一致时，本次请求才会成功，否则返回 412 Precondition Failed 错误。注：If-None-Match 支持值为 *，此时仅当 BOS 不存在该对象名的 Object 时，本次请求才会成功。 |
否 |
If-Unmodified-Since |
String | 只有 BOS 侧的 Object 于 If-Unmodified-Since 提供的时间之后未被修改过，本次请求才会成功，否则返回 412 Precondition Failed 错误。注：当 If-Match 和 If-Unmodified-Since 同时存在时，忽略 If-Unmodified-Since。 |
否 |
x-bce-meta-* |
String | 用户自定义的 Meta 信息。 | 否 |
x-bce-content-sha256 |
String | 通过携带该字段来验证保存在 BOS 侧的文件和用户预期的文件是否一致，SHA256 的校验准确性更高。所传数据的 SHA256 值必须与此匹配，否则 PutObject 失败。 | 否 |
x-bce-content-crc32 |
String | 上传 Object 的 CRC32 值，使用 IEEE 算法。 | 否 |
x-bce-content-crc32c |
String | 上传 Object 的 CRC32C 值，使用 Castagnoli 算法。 | 否 |
x-bce-content-crc32c-flag |
String | 是否计算 CRC32C，仅取值为 true 时有效。 |
否 |
x-bce-storage-class |
String | 指定 Object 的存储类型，STANDARD_IA 代表低频存储，COLD 代表冷存储，ARCHIVE 代表归档存储，不指定时默认是 STANDARD 标准存储类型；如果是多 AZ 类型 Bucket，MAZ_STANDARD_IA 代表多 AZ 低频存储，不指定时默认是 MAZ_STANDARD 多 AZ 标准存储类型，不能是其他取值。 |
否 |
x-bce-acl |
String | Canned ACL 支持的 Header，用户设置 Object 的权限，取值为 private 和 public-read。 |
否 |
x-bce-grant-read |
String | Canned ACL 支持的 Header，用户设置 Object 的读权限。支持多个 ID，以逗号分隔。 | 否 |
x-bce-grant-full-control |
String | Canned ACL 支持的 Header，用户设置 Object 的 FULL_CONTROL 权限。支持多个 ID，以逗号分隔。 |
否 |
x-bce-server-side-encryption |
String | 服务端加密算法，当前支持 AES256 和 SM4 加密。 |
否 |
x-bce-forbid-overwrite |
Boolean | 是否禁止被覆盖，默认为 false。当该值为 true 时，下次上传同名文件时将返回 409 错误。 |
否 |
x-bce-object-expires |
String | 设置对象的过期时间，过期后，BOS 将自动删除对象。单位为天，支持设置为正整数，表示对象将在指定时间过期，从对象的 Last-Modified 时间开始计算。例如设置 x-bce-object-expires 参数的值为 3，对象的 Last-Modified 时间为 2024-09-26 12:00，则该对象将于 2024-09-29 12:00 过期。在这个时间后，Object 将会被删除。说明：对象过期时间优先级高于生命周期的删除规则，例如设置对象过期时间为 5 天，生命周期规则指定该对象 3 天后删除，最终将按照对象过期时间执行，即对象将于 5 天后被删除。 注意：目前对象过期时间功能通过白名单开放，如需开启，请提交工单。 |
否 |
响应
响应头域
| 名称 | 类型 | 描述 |
|---|---|---|
ETag |
String | Object 的 HTTP 协议实体标签。 |
x-bce-version-id |
String | Object 的版本 ID。 |
x-bce-request-id |
String | BOS 服务端生成的请求 ID。 |
注意事项
Content-Length是必须参数，如果请求者指定的Content-Length比实际请求体（Object 的实际数据）长度小，BOS 只保存Content-Length指定长度的数据，多的这部分数据直接废弃；相反，如果Content-Length的长度大，BOS 将一直等待请求者上传数据，直到超时。- 上传的 Object，如不指定
Content-Type，BOS 会自动识别设置合适的Content-Type，若无法识别则默认为application/octet-stream。- 由于 BOS 本身是一个（
<Key>,<Value>）的存储系统，所以原则上并不会存在“文件夹”的概念。若需要按照文件夹来划分，可以把/符号作为分隔符模拟文件夹。例如上传 Object 为work/test/123.txt，控制台显示时会根据/自动切分，创建 work 文件夹下面的 test 文件夹和 test 文件夹下的 123.txt 文件。- 如果请求头中同时包含多个条件 Header（
If-Match、If-None-Match、If-Modified-Since、If-Unmodified-Since），BOS 的判断顺序遵循 RFC 7232 第六章规定，详情请见 RFC 7232。
响应参数
无响应 Body 参数。
示例
请求示例
Http
1PUT /ObjectName 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: 11434
7x-bce-storage-class: STANDARD_IA
8
9[11434 bytes of object data]响应示例
Http
1HTTP/1.1 200 OK
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4ETag: "1b2cf535f27731c974343645a3985328"
5x-bce-version-id: AJyQ0XRhboY=
6Content-Length: 0
7Connection: close
8Server: BceBos评价此篇文章