POST Object

描述

此POST操作将使用HTML表单为指定的空间添加一个对象。POST是PUT的另外一种选择，为了方便用户空间可以基于浏览器的上传对象。 参数通过POST以表单域的形式将数据编码封装到消息体传递，而不是PUT方式。用户需要拥有对空间的写权限才能添加新的对象。

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

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

请求

语法

POST / HTTP/1.1
Host: {BucketName}.{endpoint}
User-Agent: {browser_data}
Accept: {file_types}
Accept-Language: {Regions}
Accept-Charset: {character_set}
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: {length}

--9431149156168
Content-Disposition: form-data; name="key"

{ObjectKey}
--9431149156168
Content-Disposition: form-data; name="KSSAccessKeyId"

{AccessKey}
--9431149156168
Content-Disposition: form-data; name="Policy"

{Policy}
--9431149156168
Content-Disposition: form-data; name="Signature"

{Signature}
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg

file_content
--9431149156168
Content-Disposition: form-data; name="submit"

Upload to KS3
--9431149156168--

请求参数

该请求不使用请求参数。

请求头部

该请求只使用常用请求头部。获取更多信息，请点击常用请求头部

表单域

名称	描述	是否必选
acl	指定访问控制权限，如果指定的访问权限列表无效，则会返回错误。 类型: String 默认值: private 有效值: private public-read	否
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires	REST 特别头部. 更多信息，请查看PUT Object。 类型: String 默认值: 无	否
file	文件或文本内容。用户每次只能上传一个文件，且内容不能放到key元素的前面，否则返回400。 请注意：file必须是表单中的最后一个域 类型: 文件或文本内容 默认值: 无	是
key	ObjectKey。如果用户想要使用文件名作为Key，可以使用${filename} 变量。例如：如果用户想要上传文件local.jpg，需要指明specify /user/betty/${filename}，那么键值就会为/user/betty/local.jpg。 类型: String 默认值: 无	是
KSSAccessKeyId	KSSAccessKeyId。 类型：String 默认值:无 约束条件:当 bucket 非 public-read-write 或者提供了policy表单域时，必须提供该表单域。	视情况而定
policy	请求中用于描述获准行为的安全策略。没有安全策略的请求被认为是匿名请求，只能访问公共可写空间。 类型: String 默认值: 无 约束条件: 当 bucket 非 public-read-write.必须提供该表单域。 详见：Post Policy	视情况而定
signature	根据Access Key Secret和policy计算的签名信息，KS3验证该签名信息从而验证该Post请求的合法性。 类型: String 默认值: 无 约束条件： 当 bucket 非 public-read-write 或者提供了policy表单域时，必须提供该表单域。详见：Post Policy	视情况而定
success_action_redirect, redirect	成功上传后客户端的重定向URL。如果用户没有指定success_action_redirect，KS3将会返回空文件类型。 如果KS3无法解析URL地址，那么会无视此表单域。如果上传失败，KS3不会将客户端重定向。 类型: String 默认值: 无	否
success_action_status	返回的状态码，如果没有指定，则依赖于上传的成功状态。允许值为200，201，204(默认值)。如果是200或204，KS3将返回一个状态为200或204的空文件。如果状态码为201，那么KS3将会返回一个状态码为201的XML文档。如果值无效，或者没有设定，KS3将会返回一个状态码为204的空文档。 类型: String 默认值: 无	否
x-kss-meta-	用户元数据前缀标识。若某个头部前缀为 x-kss-meta-， 则为用户自定义元数据。 类型：String 默认值：无 约束条件：无	否
x-kss-storage-class	设置文件的存储类型。 类型：String 默认值：无 有效值：STANDARD/STANDARD_IA/ARCHIVE 说明：当不指定x-kss-storage-class时，如果Bucket是归档类型，Object自动为归档类型，如果Bucket是非归档类型，Object自动为标准类型；如果指定x-kss-storage-class，则为指定存储类型 约束条件：无	否
x-kss-newfilename-in-body	控制台设置文件名后，指定返回的文件名字是否出现body中。true表示在header和body中返回；false表示只在header中返回。 类型：boolean 默认值：None 有效值：false	true 约束条件：无
tagging	指定标签添加到对象 Default: None	否

加密相关请求头

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

名称	描述	是否必选
x-kss-server-side-encryption	如果存储 object 时使用了服务端加密，则需要配置该表单项，值为使用的加密算法，目前支持AES256。 类型：String	是

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

名称	描述	是否必选
x-kss-server-side-encryption-customer-key	由用户指定KS3加密时使用的 base64-encoded 加密秘钥。 类型：String 约束：需要和有效的 x-kss-server-side-encryption-customer-algorithm,x-kss-server-side-encryption-customer-key-MD5 同时使用。	是
x-kss-server-side-encryption-customer-algorithm	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来确认使用的解密算法。 类型：String 有效值：AES256 约束：需要和有效的 x-kss-server-side-encryption-customer-key,x-kss-server-side-encryption-customer-key-MD5 同时使用。	是
x-kss-server-side-encryption-customer-key-MD5	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。 类型：String 约束：需要和有效的 x-kss-server-side-encryption-customer-key,x-kss-server-side-encryption-customer-algorithm 同时使用。	是

响应

响应头部

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

名称	描述
success_action_redirect, redirect	成功上传后客户端的重定向URL。 类型:String 父节点：PostResponse
x-kss-server-side-encryption-customer-algorithm	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来确认使用的解密算法。 类型：String 有效值：AES256
x-kss-server-side-encryption-customer-key-MD5	如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。 类型：String
newfilename	在控制台设置文件名后的新文件名。 类型：String

特殊错误

该请求不返回任何特殊错误。

接口细节分析

• 用户需要对Bucket拥有写权限。
• 除非匿名用户对Bucket有写权限，否则需要在表单域中提供KSSAccessKeyId、policy和signature三项，具体构造方法见Post Policy。
• POST Object时，Content-Type必须为 multipart/form-data。
• policy中规定了表单需要满足的规则，表单必须满足policy中定义的规则，方可上传成功。policy中必须包含表单中除KSSAccessKeyId、policy、signature和file外的所有表单项。
• 支持在上传时指定对象tagging，请求者（主账号，子用户，角色）需要具有ks3:PutObjectTagging操作授权,若访问者仅具有ks3:PutObject权限，但没有ks3:PutObjectTagging权限时，PostObject仅允许上传不带tagging的对象。
• 用户可以在表单项中添加以x-kss-meta开头的表单项，视为添加用户元数据。注意，这些表单项也是需要在policy中定义的。
• 当KS3返回403时，应该首先检查表单是否满足policy。

请求示例

通过Post Object方法上传对象，并设置Content-Type, Content-Disposition, x-kss-meta自定义请求头等。

POST / HTTP/1.1
Content-Type: multipart/form-data; boundary=9431149156168
Host: ks3example.ks3-cn-shanghai.ksyuncs.com
Connection: keep-alive
Content-Length: 1174

--9431149156168
Content-Disposition: form-data; name="key"

1.txt
--9431149156168
Content-Disposition: form-data; name="Content-Type"

text/plain
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"

attachment
--9431149156168
Content-Disposition: form-data; name="x-kss-meta-user1"

value1
--9431149156168
Content-Disposition: form-data; name="KSSAccessKeyId"

AKLTI5NEgRq_T5igNlCPVI446w
--9431149156168
Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjogIjIwMjItMDEtMDFUMTI6MDA6MDAuMDAwWiIsImNvbmRpdGlvbnMiOiBbWyJlcSIsIiRidWNrZXQiLCAic2gtY201IiBdLFsic3RhcnRzLXdpdGgiLCAiJGtleSIsICIxIl0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwMF0sWyJlcSIsIiRDb250ZW50LVR5cGUiLCAidGV4dC9wbGFpbiJdLFsiZXEiLCIkQ29udGVudC1EaXNwb3NpdGlvbiIsICJhdHRhY2htZW50Il0sWyJlcSIsIiR4LWtzcy1tZXRhLXVzZXIxIiwgInZhbHVlMSJdXX0=
--9431149156168
Content-Disposition: form-data; name="Signature"

T+l5k0n3AbVnlCk/pqJgpdWzwmQ=
--9431149156168
Content-Disposition: form-data; name="file"; filename="1.txt"
Content-Type: text/plain

111
--9431149156168
Content-Disposition: form-data; name="submit"

Uploadto KS3
--9431149156168--

响应示例

HTTP/1.1 204 No Content
Server: KS3
Date: Thu, 25 Nov 2021 06:58:23 GMT
Connection: keep-alive
X-Application-Context: application
x-kss-request-id: fa8e4b055f344df89af6d10b4ade7ed1
x-kss-BucketOwner: MjAwMDEwMzQzMw==
ETag: "698d51a19d8a121ce581499d7b701668"
Content-Length: 0

Post Policy示例

在Post Object表单中指定的每个表单字段（KSSAccessKeyId、Signature、file、policy除外）以及bucket必须包含在条件列表中。上面请求示例对应的Policy如下：

{
    "expiration": "2022-01-01T12:00:00.000Z", 
    "conditions": [
        ["eq",  "$bucket", "ks3example"], 
        ["starts-with", "$key", "1"], 
        ["content-length-range",0,104857600], 
        ["eq","$Content-Type","text/plain"],
        ["eq","$Content-Disposition", "attachment"],
        ["eq","$x-kss-meta-user1", "value1"]
    ]
}

错误码	HTTP状态码	描述
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。