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

对象标签权限

• 若您需要在上传某个对象的同时为其指定标签，那您还需要具有ks3:PutObjectTagging权限，用来添加/更新对象的标签，对象写权限与写对象标签权限相互独立。

说明

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

有关如何下载Object，请参见GET Object。

请求

请求语法

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

注意：

• endpoint与Region对应关系
• SignatureValue签名算法

请求参数

该请求不使用请求参数。

请求头部

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

名称	描述	是否必选
Cache-Control	告诉所有的缓存机制是否可以缓存及哪种类型。更多信息，请点击查看 类型：String 默认值：None 约束条件：无	否
Content-Disposition	指定对象的表达信息。更多信息，请点击查看 类型：String 默认值：None 约束条件：无	否
Content-Encoding	指定文件内容编码格式。更多信息，请点击查看 类型：String 默认值：None 约束条件：无	否
Content-Length	指明对象的大小，按字节。更多信息，请点击查看 类型：String 默认值：None 约束条件：无	是
Content-MD5	对消息内容（不包括头部）计算MD5值，获得128比特位数字，然后对该数字进行base64编码，用于对象完整性校验。 类型：String 默认值：None 约束条件：无	否
Content-Type	用于描述文件内容MIME格式。更多信息，请点击查看 类型：String 默认值：binary/octet-stream 有效值: MIME types 约束条件：无	否
Expect	当你使用 100-continue 时，直到收到确认时才会发送请求体。如果头部信息被拒绝，请求体不会被发送。 类型：String 默认值：None 有效值：100-continue 约束条件：无	否
Expires	对象存在于缓存的有效时间日期。更多信息，请点击查看 类型：String 默认值：None 约束条件：无	否
x-kss-meta-	用户元数据前缀标识。若某个头部前缀为 x-kss-meta-， 则为用户自定义元数据。 类型：String 默认值：None 约束条件：无	否
x-kss-storage-class	设置存储方式。 类型：String 默认值：None 有效值：STANDARD/STANDARD_IA/ARCHIVE 说明：如果不指定x-kss-storage-class，Object存储类型默认跟Bucket存储类型一致；如果指定x-kss-storage-class，则Object为指定存储类型。 约束条件：无	否
x-kss-content-maxlength	上传文件大小的最大值。上传文件的Content-Length不能大于该值。 类型：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”

加密相关请求头部

若使用KS3 托管密钥的服务器端加密，则需要使用以下请求头 。

名称	描述
x-kss-server-side-encryption	如果请求中包含此头，服务端将对数据进行加密处理，合法值：AES256

若使用客户提供的加密密钥的服务器端加密，则需要使用以下请求头 。

名称	描述
x-kss-server-side-encryption-customer-algorithm	客户端提供的加密算法，合法值：AES256
x-kss-server-side-encryption-customer-key	客户端提供的加密密钥
x-kss-server-side-encryption-customer-key-MD5	客户端提供的通过BASE64编码的通过128位MD5加密的密钥的MD5值

请求内容

该接口不使用请求内容。

响应

响应头部

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

名称	描述
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

错误码

错误码	HTTP状态码	描述
413 Request Entity Too Large	413 Request Entity Too Large	上传的文件大小超过5 GB。
EntityTooLarge	400 Bad Request	使用x-kss-content-maxlength请求头时，maxlength小于对应的Content-length。
InvalidDigest	400 Bad Request	Content-MD5的值是不合法的、无效的。
BadDigest	400 Bad Request	Content-MD5的值合法，但和上传对象的MD5值不一致。
BadRequest	400 Bad Request	设置Tagging的数量超过十个。
InvalidTaggingFormat	400 Bad Request	设置无效的Tagging。
AlgorithmInvalidForS3	400	x-kss-server-side-encryption请求头的值不是AES256。
Md5NotMatchForOldMd5	400	x-kss-copy-source-server-side-encryption-customer-key-MD5 不是 x-kss-copy-source-server-side-encryption-customer-key 的MD5值。
AlgorithmInvalidForCustomerKey	400	x-kss-server-side-encryption-customer-algorithm不是合法的AES256。