对象存储 PutObject

PutObject 接口请求可以将本地的对象（Object）上传至指定存储桶（Bucket）中。
注意事项
文件大小限制
PutObject 接口最大支持上传 5GB 文件。如需上传大于 5GB 的文件，请使用 分块上传 系列 API 接口。
文件对象与目录对象
Rapid Bucket 区分文件对象与目录对象，以对象键是否以 / 结尾区分：对象键不以 / 结尾表示文件对象，以 / 结尾表示目录对象。两类对象在请求约束、可携带的头部以及响应内容上存在差异。
文件对象
对不以 / 结尾的对象键调用 PutObject 时：
例如 doc/picture.png 表示将 picture.png 上传到 doc 目录下。若 doc 目录不存在，服务会自动创建。
请求体即为对象的原始字节流。
响应会返回 ETag、Last-Modified 以及 x-cos-hash-crc64ecma。
目录对象
对以 / 结尾的对象键调用 PutObject 时：
例如 doc/ 表示创建名为 doc 的目录。
Content-Length 必须为 0，否则返回 DirectoryObjectContainsData。
不支持携带 x-cos-meta-*、Cache-Control、Content-Disposition、Content-Encoding、Content-Language、Content-Type、Expires 等元数据头部，否则返回 InvalidArgument。
若携带 Content-MD5 头部，其值必须为空内容的 MD5 Base64 值（1B2M2Y8AsgTpgAmY7PhCfg==），否则返回 BadDigest。
响应仅返回 ETag 和 Last-Modified，不返回 x-cos-hash-crc64ecma。
同名冲突与覆盖规则
文件对象与目录对象不支持同名共存，也不支持跨类型覆盖，具体规则如下：
1. 同名文件之间默认覆盖：上传同名文件对象时默认覆盖原有对象，返回 200 OK。如需禁止覆盖，可携带 x-cos-forbid-overwrite: true，此时目标对象已存在则返回 409 FileAlreadyExists。
2. 文件不能覆盖同名目录：上传 foo 时，若 foo/ 已作为目录对象存在，请求返回 409 DirAlreadyExists。该限制与 x-cos-forbid-overwrite 无关。
3. 目录不能覆盖同名文件：上传 foo/ 时，若 foo 已作为文件对象存在，请求返回 409 FileAlreadyExists。
4. 路径中间组件必须是目录：上传 a/b/c 时，若 a/b 已作为文件对象存在，请求返回 409 FileAlreadyExists。
请求
请求语法
PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Content-Type: <Content Type>
Content-Length: <Content Length>
Content-MD5: <MD5>
Authorization: <Auth String>
﻿
[Object Content]
说明：
Authorization 字段的具体格式见 公共请求头部。
请求参数
此接口无请求参数。
请求头部
除 公共请求头部 外，本接口还支持以下请求头部：
常规请求头部
Header 名称
描述
类型
是否必选
Cache-Control
RFC 2616 中定义的缓存指令，将作为对象元数据保存
string
否
Content-Disposition
RFC 2616 中定义的文件名称，将作为对象元数据保存
string
否
Content-Encoding
RFC 2616 中定义的编码格式，将作为对象元数据保存
string
否
Content-Language
RFC 2616 中定义的内容语言，将作为对象元数据保存
string
否
Content-Type
RFC 2616 中定义的 HTTP 请求内容类型（MIME），用于描述待上传对象的内容类型，将作为对象元数据保存。例如 application/xml 或 image/jpeg。文件对象不支持指定为 application/x-directory，否则返回 InvalidArgument
string
否
Expires
RFC 2616 中定义的缓存失效时间，是绝对日期和时间，将作为对象元数据保存
string
否
Transfer-Encoding
RFC 2616 中定义的传输编码格式。如果希望在上传时分块传输，则指定 Transfer-Encoding: chunked 请求头部，并不再指定 Content-Length 请求头部
string
否
专用请求头部
Header 名称
描述
类型
是否必选
x-cos-meta-[自定义后缀]
用户自定义元数据头部，例如 x-cos-meta-test: test metadata。自定义后缀仅支持减号（-）、数字、英文小写字母（a~z）
string
否
x-cos-storage-class
对象存储类型，当前仅支持 RAPID（默认值）。指定其他取值时返回 NotSupportedStorageClass
enum
否
x-cos-forbid-overwrite
是否禁止覆盖同名文件对象，取值为 true 时启用。行为契约详见「同名冲突与覆盖规则」
string
否
请求体
该请求的请求体（Body）为待上传对象的原始字节流。
响应
响应头部
除 公共响应头部 外，本接口还会返回以下响应头部：
Header 名称
描述
类型
是否必返
ETag
对象的 MD5 校验值，使用双引号包裹。客户端可据此验证上传完整性
string
是
Last-Modified
对象最近一次被修改的时间，格式为 RFC 1123 GMT，例如 Wed, 29 May 2019 04:10:12 GMT
string
是
x-cos-hash-crc64ecma
对象的 CRC64-ECMA 校验值，十进制字符串。仅文件对象返回，目录对象不返回
string
否
响应体
该接口的响应体为空。
错误码
本接口遵循统一的错误响应和错误码，详情请参见 错误码 文档。
实际案例
案例一：上传文件对象
请求
PUT /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Type: image/jpeg
Content-Length: 16
Content-MD5: 7o3pGNBWQBRbGPcPTDqmAg==
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
﻿
[Object Content]
响应
HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Wed, 29 May 2019 04:10:12 GMT
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
案例二：上传带用户自定义元数据的对象
请求
PUT /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Type: image/jpeg
Content-Length: 16
x-cos-meta-author: alice
x-cos-meta-tag: release
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;content-type;date;host;x-cos-meta-author;x-cos-meta-tag&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
﻿
[Object Content]
响应
HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Wed, 29 May 2019 04:10:12 GMT
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
案例三：使用 chunked 传输编码上传
本案例请求中使用 Transfer-Encoding: chunked 编码，案例描述的是 HTTP 请求中的原始数据，在使用过程中根据不同语言和库将有不同的调用方法，请开发者查阅语言和库的相关文档。
请求
PUT /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-type;date;host;transfer-encoding&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
﻿
11
[Chunked Content]
b
[2nd chunk]
0
响应
HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "aa488bb80185a6be87f4a7b936a80752"
Last-Modified: Wed, 29 May 2019 04:10:12 GMT
x-cos-hash-crc64ecma: 7188322482464764960
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
案例四：使用 x-cos-forbid-overwrite 防覆盖
本案例在上传对象请求中携带了 x-cos-forbid-overwrite: true，表示禁止覆盖同名对象。
请求
PUT /exampleobject HTTP/1.1
x-cos-forbid-overwrite: true
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Type: image/jpeg
Content-Length: 16
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;content-type;date;host;x-cos-forbid-overwrite&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
﻿
[Object Content]
响应
如果存储桶中不存在同名对象，则上传成功：
HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "aa488bb80185a6be87f4a7b936a80752"
Last-Modified: Wed, 29 May 2019 04:10:12 GMT
x-cos-hash-crc64ecma: 7188322482464764960
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
如果存储桶中存在同名对象，则返回报错：
HTTP/1.1 409 Conflict
Content-Type: application/xml
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
﻿
<?xml version='1.0' encoding='utf-8'?>
<Error>
    <Code>FileAlreadyExists</Code>
    <Message>File already exists.</Message>
    <Resource></Resource>
    <RequestId>NjUwMDAwMDAwMDAwMDAwMDAw</RequestId>
    <TraceId></TraceId>
</Error>
案例五：创建目录对象
请求
PUT /folder/ HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;date;host&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
响应
HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Last-Modified: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
﻿

Header 名称	描述	类型	是否必选
Cache-Control	RFC 2616 中定义的缓存指令，将作为对象元数据保存	string	否
Content-Disposition	RFC 2616 中定义的文件名称，将作为对象元数据保存	string	否
Content-Encoding	RFC 2616 中定义的编码格式，将作为对象元数据保存	string	否
Content-Language	RFC 2616 中定义的内容语言，将作为对象元数据保存	string	否
Content-Type	RFC 2616 中定义的 HTTP 请求内容类型（MIME），用于描述待上传对象的内容类型，将作为对象元数据保存。例如 `application/xml` 或 `image/jpeg`。文件对象不支持指定为 `application/x-directory`，否则返回 `InvalidArgument`	string	否
Expires	RFC 2616 中定义的缓存失效时间，是绝对日期和时间，将作为对象元数据保存	string	否
Transfer-Encoding	RFC 2616 中定义的传输编码格式。如果希望在上传时分块传输，则指定 `Transfer-Encoding: chunked` 请求头部，并不再指定 `Content-Length` 请求头部	string	否

PutObject

本页目录：

注意事项

文件大小限制

文件对象与目录对象

文件对象

目录对象

同名冲突与覆盖规则

请求

请求语法

请求参数

请求头部

常规请求头部

专用请求头部

请求体

响应

响应头部

响应体

错误码

实际案例

案例一：上传文件对象

请求

响应

案例二：上传带用户自定义元数据的对象

请求

响应

案例三：使用 chunked 传输编码上传

请求

响应

案例四：使用 x-cos-forbid-overwrite 防覆盖

请求

响应

案例五：创建目录对象

请求

响应