全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

PUT Object

最近更新时间:2024-07-25 16:55:29

描述

该接口可以上传一个文件(Object)到某个存储空间(Bucket)。使用此接口的用户,必须是该Bucket的所有者或具有ks3:PutObject权限。

注意:该接口上传的Object大小不能超过5GB,超过5GB的Object请使用分块上传

访问控制权限

上传某个Object时,可以设置文件访问控制权限。使用请求头部,有两种设置方式。

  • 方式一:使用x-kss-acl请求头部,设置文件的ACL,对全体用户生效。

  • 方式二:使用x-kss-grant-readx-kss-grant-full-control请求头部,针对指定的用户生效。

请勿同时在Header中设置x-kss-acl和x-kss-grant-*,否则将会报错提示。

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

说明

  • key的名称的长度必须为至少1个字符,且不能超过1024个字符;key的名称不能包含"@base@"和"@style@"。

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

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

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

  • 用户可以在请求头中添加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}

注意:

请求参数

该请求不使用请求参数。

请求头部

该接口除了使用所有公共请求头外,还可以使用以下请求头。

名称

描述

是否必选

Cache-Control

告诉所有的缓存机制是否可以缓存及哪种类型。更多信息,请点击查看

  • 类型:String

  • 默认值:None

  • 约束条件:无

Content-Disposition

指定对象的表达信息。更多信息,请点击查看

  • 类型:String

  • 默认值:None

  • 约束条件:无

Content-Encoding

指定文件内容编码格式。更多信息,请点击查看

  • 类型:String

  • 默认值:None

  • 约束条件:无

Content-Length

指明对象的大小,按字节。更多信息,请点击查看

  • 类型:String

  • 默认值:None

  • 约束条件:无

Content-MD5

对消息内容(不包括头部)计算MD5值,获得128比特位数字,然后对该数字进行base64编码,用于对象完整性校验。

  • 类型:String

  • 默认值:None

  • 约束条件:无

x-kss-checksum-crc64ecma

对消息内容(不包括头部)计算CRC64值,用于对象完整性校验。关于CRC64的计算标准,请参见:ECMA-182标准

  • 类型: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

设置存储方式。如果不指定x-kss-storage-class,Object存储类型默认跟Bucket存储类型一致;如果指定x-kss-storage-class,则Object为指定存储类型。

  • 类型:String

  • 默认值:None

  • 有效值:STANDARD/STANDARD_IA/ARCHIVE

  • 约束条件:无

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

针对所有用户设置对象的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。

  • 示例:为UID为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

x-kss-checksum-crc64ecma

无论上传文件时是否带有x-kss-checksum-crc64ecma请求头,响应时都会返回该响应头。

  • 类型: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 200 OK
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a398****"
x-kss-checksum-crc64ecma: 1408511733533619****
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。

InvalidRequest

400 Bad Request

CRC64值不合法。

BadDigest

400 Bad Request

CRC64值合法但错误。

InvalidRequest

400

同时在Header中设置了x-kss-acl和x-kss-grant-*。

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈