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--

请求参数

该请求不使用请求参数。

请求头部

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

表单域

加密相关请求头

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

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

响应

响应头部

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

特殊错误

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

接口细节分析

• 用户需要对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: "698d51a19d8a121ce581499d7b70****"
x-kss-checksum-crc64ecma: 503054087537662****
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"]
    ]
}