PUT Object

最近更新时间:2019-08-13 11:47:13

功能描述

PUT Object 接口请求可以将本地的对象(Object)上传至指定存储桶中。该 API 的请求者需要对存储桶有写入权限。

说明:

  • 如果请求头的 Content-Length 值小于实际请求体(body)中传输的数据长度,COS 仍将成功创建文件,但对象大小只等于 Content-Length 中定义的大小,其他数据将被丢弃。
  • 如果试图添加已存在的同名对象且没有启用版本控制,则新上传的对象将覆盖原来的对象,成功时返回200 OK。

版本控制

  • 如果对存储桶启用版本控制,对象存储将自动为要添加的对象生成唯一的版本 ID。对象存储使用 x-cos-version-id 响应头部在响应中返回此标识。
  • 如果暂停存储桶的版本控制,则对象存储始终将 null 用作存储在存储桶中的对象的版本 ID,且不返回 x-cos-version-id 响应头部。

请求

请求示例

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

[Object Content]
说明:

Authorization: Auth String (详情请参见 请求签名 文档)。

请求参数

此接口无请求参数。

请求头

此接口除使用公共请求头部外,还支持以下请求头部,了解公共请求头部详情请参见 公共请求头部 文档。

名称 描述 类型 是否必选
Cache-Control RFC 2616 中定义的缓存指令,将作为对象元数据保存 string
Content-Disposition RFC 2616 中定义的文件名称,将作为对象元数据保存 string
Content-Encoding RFC 2616 中定义的编码格式,将作为对象元数据保存 string
Expires RFC 2616 中定义的缓存失效时间,将作为对象元数据保存 string
Transfer-Encoding 如果希望在上传时分块传输,则指定 Transfer-Encoding: chunked 请求头部,此时请求体遵循 RFC 2616 中定义的传输编码格式,且不能指定 Content-Length 请求头部 string
x-cos-meta-* 包括用户自定义元数据头部后缀和用户自定义元数据信息,将作为对象元数据保存,大小限制为2KB
注意:用户自定义元数据信息支持下划线(_),但用户自定义元数据头部后缀不支持下划线,仅支持减号(-)
string
x-cos-storage-class 对象存储类型。枚举值请参见 存储类型 文档,例如 STANDARD_IA,ARCHIVE。默认值:STANDARD Enum

访问控制列表(ACL)相关头部

在上传对象时可以通过指定下列请求头部来设置对象的访问权限:

名称 描述 类型 是否必选
x-cos-acl 定义对象的访问控制列表(ACL)属性。枚举值请参见 ACL 概述 文档中对象的预设 ACL 部分,如 default, private, public-read 等,默认为 default
注意:当前访问策略条目限制为1000条,如果您不需要进行对象 ACL 控制,请设置为 default 或者此项不进行设置,默认继承存储桶权限
Enum
x-cos-grant-read 赋予被授权者读取对象的权限,格式为 id="[OwnerUin]",如 id="100000000001",可使用半角逗号(,)分隔多组被授权者,如 id="100000000001",id="100000000002" string
x-cos-grant-read-acp 赋予被授权者读取对象的访问控制列表(ACL)的权限,格式为 id="[OwnerUin]",如 id="100000000001",可使用半角逗号(,)分隔多组被授权者,如 id="100000000001",id="100000000002" string
x-cos-grant-write-acp 赋予被授权者写入对象的访问控制列表(ACL)的权限,格式为 id="[OwnerUin]",如 id="100000000001",可使用半角逗号(,)分隔多组被授权者,如 id="100000000001",id="100000000002" string
x-cos-grant-full-control 赋予被授权者操作对象的所有权限,格式为 id="[OwnerUin]",如 id="100000000001",可使用半角逗号(,)分隔多组被授权者,如 id="100000000001",id="100000000002" string

服务端加密相关头部

在上传对象时可以使用服务端加密,请参见 服务端加密专用头部

请求体

此接口请求的请求体为对象(文件)内容。

响应

响应头

此接口仅返回公共响应头部,详情请参见 公共响应头部 文档。

版本控制相关头部

在启用(Enabled)版本控制的存储桶中上传对象,将返回下列响应头部:

名称 描述 类型
x-cos-version-id 对象的版本 ID string

服务端加密相关头部

如果在上传对象时使用了服务端加密,则此接口将返回服务端加密专用头部,请参见 服务端加密专用头部

响应体

此接口响应体为空。

错误码

此接口无特殊错误信息,全部错误信息请参见 错误码 文档。

实际案例

案例一:简单案例(未启用版本控制)

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 21 Jun 2019 09:24:28 GMT
Content-Type: image/jpeg
Content-Length: 13
Content-MD5: ti4QvKtVqIJAvZxDbP/c+Q==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1561109068;1561116268&q-key-time=1561109068;1561116268&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=998bfc8836fc205d09e455c14e3d7e623bd2****
Connection: close

[Object Content]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Fri, 21 Jun 2019 09:24:28 GMT
ETag: "b62e10bcab55a88240bd9c436cffdcf9"
Server: tencent-cos
x-cos-request-id: NWQwY2EyNGNfYThjMDBiMDlfMTA0ZmVfYTJm****

案例二:使用请求头部指定元数据和 ACL

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 21 Jun 2019 09:24:31 GMT
Content-Type: image/jpeg
Cache-Control: max-age=86400
Content-Disposition: attachment; filename=example.jpg
x-cos-meta-example-field: example-value
x-cos-acl: public-read
Content-Length: 13
Content-MD5: ti4QvKtVqIJAvZxDbP/c+Q==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1561109071;1561116271&q-key-time=1561109071;1561116271&q-header-list=cache-control;content-disposition;content-length;content-md5;content-type;date;host;x-cos-acl;x-cos-meta-example-field&q-url-param-list=&q-signature=da483c6b1c2506142a128aba8e6d35781dd1****
Connection: close

[Object Content]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Fri, 21 Jun 2019 09:24:32 GMT
ETag: "b62e10bcab55a88240bd9c436cffdcf9"
Server: tencent-cos
x-cos-request-id: NWQwY2EyNGZfN2ViMTJhMDlfYmYxN185MjA2****

案例三:使用服务端加密 SSE-COS

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 21 Jun 2019 09:24:35 GMT
Content-Type: image/jpeg
x-cos-server-side-encryption: AES256
Content-Length: 13
Content-MD5: ti4QvKtVqIJAvZxDbP/c+Q==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1561109075;1561116275&q-key-time=1561109075;1561116275&q-header-list=content-length;content-md5;content-type;date;host;x-cos-server-side-encryption&q-url-param-list=&q-signature=3e21f7fba71e04d5c7f3aee7ff39753b240a****
Connection: close

[Object Content]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Fri, 21 Jun 2019 09:24:35 GMT
ETag: "b62e10bcab55a88240bd9c436cffdcf9"
Server: tencent-cos
x-cos-request-id: NWQwY2EyNTNfN2JiMTJhMDlfNDM2ZF85OTA1****
x-cos-server-side-encryption: AES256

案例四:使用服务端加密 SSE-C

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 21 Jun 2019 09:24:38 GMT
Content-Type: image/jpeg
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
Content-Length: 13
Content-MD5: ti4QvKtVqIJAvZxDbP/c+Q==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1561109078;1561116278&q-key-time=1561109078;1561116278&q-header-list=content-length;content-md5;content-type;date;host;x-cos-server-side-encryption-customer-algorithm;x-cos-server-side-encryption-customer-key;x-cos-server-side-encryption-customer-key-md5&q-url-param-list=&q-signature=d04a5d70af5f08c7db4f89a91628a7eacf90****
Connection: close

[Object Content]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Fri, 21 Jun 2019 09:24:38 GMT
ETag: "492b458ec33eaf0a824e7dd1bdd403b3"
Server: tencent-cos
x-cos-request-id: NWQwY2EyNTZfZjBhODBiMDlfMTJiOTJfOWY0****
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==

案例五:启用(Enabled)版本控制

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 21 Jun 2019 09:24:45 GMT
Content-Type: image/jpeg
Content-Length: 13
Content-MD5: ti4QvKtVqIJAvZxDbP/c+Q==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1561109085;1561116285&q-key-time=1561109085;1561116285&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=20c8b3f8f887cab343124b2330e280486e1f****
Connection: close

[Object Content]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Fri, 21 Jun 2019 09:24:45 GMT
ETag: "b62e10bcab55a88240bd9c436cffdcf9"
Server: tencent-cos
x-cos-request-id: NWQwY2EyNWRfYThjMDBiMDlfMTA1MDlfYTQ1****
x-cos-version-id: MTg0NDUxODI5NjQ2MjM5OTMyNzM

案例六:暂停(Suspended)版本控制

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Wed, 24 Jul 2019 02:51:28 GMT
Content-Type: image/jpeg
Content-Length: 13
Content-MD5: ti4QvKtVqIJAvZxDbP/c+Q==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1563936688;1563943888&q-key-time=1563936688;1563943888&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=aab4bfeb62a7a86725da58d4ad06deb5cba1****
Connection: close

[Object Content]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Wed, 24 Jul 2019 02:51:28 GMT
ETag: "b62e10bcab55a88240bd9c436cffdcf9"
Server: tencent-cos
x-cos-request-id: NWQzN2M3YjBfN2ViMTJhMDlfYTkxMl9iY2Fj****

案例七:使用 chunked 传输编码分块传输

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 08 Aug 2019 09:15:29 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1565255729;1565262929&q-key-time=1565255729;1565262929&q-header-list=content-type;date;host;transfer-encoding&q-url-param-list=&q-signature=0b05b6bda75afbc159caa0da4e4051ec6939****
Connection: close

11
[Chunked Content]
b
[2nd chunk]
b
[3rd chunk]
b
[4th chunk]
0

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Thu, 08 Aug 2019 09:15:29 GMT
ETag: "aa488bb80185a6be87f4a7b936a80752"
Server: tencent-cos
x-cos-request-id: NWQ0YmU4MzFfNzFiNDBiMDlfMWJhYTlfMTY2Njll****