最近更新时间:2023-11-28 11:38:00
此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
请求头部,来明确指定具体的访问权限。有关如何下载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 约束条件:无 |
否 |
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为空字符串,详见对象标签。 |
否 |
用户可以通过以下的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:
若使用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。 |
文档内容是否对您有帮助?
评价建议不能为空
非常感谢您的反馈,我们会继续努力做到更好!