最近更新时间:2024-07-25 16:55:29
该接口可以上传一个文件(Object)到某个存储空间(Bucket)。使用此接口的用户,必须是该Bucket的所有者或具有ks3:PutObject
权限。
注意:该接口上传的Object大小不能超过5GB,超过5GB的Object请使用分块上传 。
上传某个Object时,可以设置文件访问控制权限。使用请求头部,有两种设置方式。
方式一:使用x-kss-acl
请求头部,设置文件的ACL,对全体用户生效。
方式二:使用x-kss-grant-read
、x-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 | 告诉所有的缓存机制是否可以缓存及哪种类型。更多信息,请点击查看。
| 否 |
Content-Disposition | 指定对象的表达信息。更多信息,请点击查看
| 否 |
Content-Encoding | 指定文件内容编码格式。更多信息,请点击查看
| 否 |
Content-Length | 指明对象的大小,按字节。更多信息,请点击查看
| 是 |
Content-MD5 | 对消息内容(不包括头部)计算MD5值,获得128比特位数字,然后对该数字进行base64编码,用于对象完整性校验。
| 否 |
x-kss-checksum-crc64ecma | 对消息内容(不包括头部)计算CRC64值,用于对象完整性校验。关于CRC64的计算标准,请参见:ECMA-182标准。
| 否 |
Content-Type | 用于描述文件内容MIME格式。更多信息,请点击查看
| 否 |
Expect | 当使用
| 否 |
Expires | 对象存在于缓存的有效时间日期。更多信息,请点击查看
| 否 |
x-kss-meta- | 用户元数据前缀标识。若某个头部前缀为
| 否 |
x-kss-storage-class | 设置存储方式。如果不指定
| 否 |
x-kss-content-maxlength | 上传文件大小的最大值。上传文件的Content-Length不能大于该值。
| 否 |
x-kss-newfilename-in-body | 控制台设置文件名后,指定返回的文件名字是否出现body中。true表示在header和body中返回;false表示只在header中返回。
| 否 |
x-kss-tagging | 指定目标Object对象标签,可同时设置多个标签,例如:TagA=A&TagB=B。 | 否 |
用户可以通过以下的Header为Object设置ACL。
名称 | 描述 | 是否必选 |
---|---|---|
x-kss-acl | 针对所有用户设置对象的ACL。
| 否 |
如果用户期望为若干用户设置Object的ACL权限,可以通过以下Header设置。
名称 | 描述 | 是否必选 |
---|---|---|
x-kss-grant-read | 为若干用户授予READ权限。
| 否 |
x-kss-grant-full-control | 为若干用户授予FULL_CONTROL权限。
| 否 |
以上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 | 如果存储
|
x-kss-server-side-encryption-customer-algorithm | 如果服务端使用了用户提供的加密秘钥加密,在请求解密时,响应将会包含该头部来确认使用的解密算法。
|
x-kss-server-side-encryption-customer-key-MD5 | 如果服务端使用了用户提供的加密秘钥加密,在请求解密时,响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。
|
newfilename | 在控制台设置文件名后的新文件名。
|
x-kss-checksum-crc64ecma | 无论上传文件时是否带有
|
该接口不返回响应内容。
该接口不返回任何特殊错误。
请求示例
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-*。 |
纯净模式