PUT Object

最近更新时间:2019-01-14 10:10:58

PUT Object


描述

此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 请求头部,来明确指定具体的访问权限。

请求

语法

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-storageClassARCHIVE时,Bucket必须为归档类型,否则返回400;如果x-kss-storageClass不为ARCHIVE时,Bucket不能为归档类型,否则返回400。
约束条件:无
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
约束条件:无
ACL 特殊头部

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

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

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

名称 描述 必须
x-kss-grant-read 为若干用户授予READ权限。
类型:String
默认值:无
约束条件:无
x-kss-grant-write 为若干用户授予WRITE权限。
类型: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.ksyun.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
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: close
Server: Tengine

接口细节分析

  • 用户可以在请求头中添加Content-MD5,要求KS3对文件的完整性做校验
  • 当服务器上文件已存在时,若上传成功,将会导致覆盖。
  • 用户可以在上传的时候添加x-kss-meta-*的header,为Object添加用户元数据
  • Content-Length是必须的,且不能大于body中的实际数据大小
  • 关于如何下载上传上去的object,请详见GET Object

金山云,开启您的云计算之旅

立即注册