PUT Object

最近更新时间:2022-11-24 11:06:52

查看PDF

描述

此PUT接口可以添加一个 object 到某个 bucket
如果要使用此接口,你需要具有对要添加对象的空间的 WRITE 权限。

KS3不会添加不完整对象,如果你收到成功的响应,那么KS3已经成功添加对象到相应空间中。

KS3是一个分布式系统。如果同时受到多个相同的对象的写请求,它会覆盖所有相同对象,只保留最后一个对象。KS3不提供在写对象时,为对象加锁服务,如果你确实需要,请在你的应用层实现它。

为了保证数据在传输过程中没有损坏,请使用 Content-MD5 头部。当使用此头部时,KS3会自动计算出MD5,并根据用户提供的MD5进行校验,如果不匹配,将会返回错误信息。另外,当用户上传一个对象到KS3时,可以根据返回的 ETag 计算出对象的MD5值。

注意:使用此接口只能上传5G以内的文件,超过5G的文件请使用分块上传

权限

当你上传某个对象时,你可以随意指定任意数量的组或个人,授予权限。使用请求头部,有两种途径能够赋予有效权限。

  • 使用 x-kss-acl 请求头部,指定一个预定义的 ACL
  • 使用 x-kss-grant-read,x-kss-grant-write,x-kss-grant-full-control 请求头部,来明确指定具体的访问权限。
对象标签权限
  • 若您需要在上传某个对象的同时为其指定标签,那您还需要具有ks3:PutObjectTagging权限,用来添加/更新对象的标签,对象写权限与写对象标签权限相互独立。

请求

请求语法

PUT /{ObjectKey} HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

注意:

请求参数

该请求不使用请求参数。

请求头部

该接口可以使用所有常用请求头部,此外,也可以使用下表所列请求头部。获取更多信息,请点击常用请求头部

名称 描述 是否必选
Cache-Control 告诉所有的缓存机制是否可以缓存及哪种类型。更多信息,请点击http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.9
类型:String
默认值:None
约束条件:无
Content-Disposition 指定对象的表达信息。更多信息,请点击http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html##sec19.5.1
类型:String
默认值:None
约束条件:无
Content-Encoding 指定文件内容编码格式。更多信息,请点击http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.11
类型:String
默认值:None
约束条件:无
Content-Length 指明对象的大小,按字节。更多信息,请点击http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.13
类型:String
默认值:None
约束条件:无
Content-MD5 对消息内容(不包括头部)计算MD5值,获得128比特位数字,然后对该数字进行base64编码,用于对象完整性校验。
类型:String
默认值:None
约束条件:无
Content-Type 用于描述文件内容MIME格式。更多信息,请点击http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.17
类型:String
默认值:binary/octet-stream
有效值: MIME types
约束条件:无
Expect 当你使用 100-continue 时,直到收到确认时才会发送请求体。如果头部信息被拒绝,请求体不会被发送。
类型:String
默认值:None
有效值:100-continue
约束条件:无
Expires 对象存在于缓存的有效时间日期。更多信息,请点击http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.21
类型:String
默认值:None
约束条件:无
x-kss-meta- 用户元数据前缀标识。若某个头部前缀为 x-kss-meta-, 则为用户自定义元数据。
类型:String
默认值:None
约束条件:无
x-kss-storage-class 设置存储方式。
类型:String
默认值:None
有效值:STANDARD/STANDARD_IA/ARCHIVE
说明:当不指定x-kss-storage-class时,如果Bucket是归档类型,Object自动为归档类型,如果Bucket是非归档类型,Object自动为标准类型;如果指定x-kss-storage-class,则为指定存储类型。
约束条件:无
x-kss-content-maxlength 当上传文件的Content-Length大于该值时,KS3将会返回403。
类型:String
默认值:None
约束条件:无
x-kss-newfilename-in-body 控制台设置文件名 后,指定返回的文件名字是否出现body中。true表示在header和body中返回;false表示只在header中返回。
类型:boolean
默认值:None
有效值:false\true
约束条件:无
x-kss-tagging 指定目标Object对象标签,可同时设置多个标签,例如:TagA=A&TagB=B。
说明: Key和Value需要先进行URL编码
如果某项没有”=“,则看作Value为空字符串,详见对象标签
ACL 特殊头部

用户可以通过以下的header为Object设置预设的ACL

名称 描述 是否必选
x-kss-acl 用于对象的预定义权限。
类型:String
默认值:private
有效值:private | public-read
约束条件:无

如果用户期望为Object设置详细的ACL,可以通过以下header设置

名称 描述 是否必选
x-kss-grant-read 为若干用户授予READ权限。
类型:String
默认值:无
约束条件:无
x-kss-grant-full-control 为若干用户授予FULL_CONTROL权限。
类型:String
默认值:无
约束条件:无

以上header值的值为以一个逗号","分割的授权列表。每个授权信息的格式为type=value,当前type支持id:

  • id:被授权者的用户id
    例如,要给id为1234578和3344211的两个用户授予READ权限:x-kss-grant-read:id=“1234578”,id=“3344211”

请求内容

该接口不使用请求内容。

响应

响应头部

该接口可以使用所有常用响应头部。获取更多信息,请点击常用响应头部

名称 描述
x-kss-server-side-encryption 如果存储 object 时使用了服务端加密,则响应会包含该头部,值为使用的加密算法。
类型:String
x-kss-server-side-encryption-customer-algorithm 如果服务端使用了用户提供的加密秘钥加密,在请求解密时,响应将会包含该头部来确认使用的解密算法。
类型:String
有效值:AES256
x-kss-server-side-encryption-customer-key-MD5 如果服务端使用了用户提供的加密秘钥加密,在请求解密时,响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。
类型:String
newfilename 在控制台设置文件名 后的新文件名。
类型:String

响应内容

该接口不返回响应内容。

特殊错误

该请求不返回任何特殊错误。

示例

请求示例

PUT /my-image.jpg HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
x-kss-tagging: TagA=A&TagB=B
Content-Length: 11434
Expect: 100-continue
[11434 bytes of object data]

响应示例

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: keep-alive
Server: KS3

接口细节分析

  • 用户可以在请求头中添加Content-MD5,要求KS3对文件的完整性做校验。
  • 当服务器上文件已存在时,若上传成功,将会导致覆盖。
  • 用户可以在上传的时候添加x-kss-meta-*的header,为Object添加用户元数据。
  • 支持在上传时指定对象tag,请求者(主账号,子用户,角色)需要具有ks3:PutObjectTagging操作授权。
  • Content-Length是必须的,且不能大于body中的实际数据大小。
  • 当访问者具有ks3:PutObject权限,但没有ks3:PutObjectTagging权限时,PutObject仅允许上传不带tagging的对象。
  • 关于如何下载上传上去的object,请详见GET Object

错误码

错误码 HTTP状态码 描述
413 Request Entity Too Large 413 Request Entity Too Large 上传的文件大小超过5 GB。

文档内容是否对您有帮助?

根本没帮助
文档较差
文档一般
文档不错
文档很好

在文档使用中是否遇到以下问题

内容不全,不深入
内容更新不及时
描述不清晰,比较混乱
系统或功能太复杂,缺乏足够的引导
内容冗长

更多建议

0/200

评价建议不能为空

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

问题反馈