全部文档
当前文档
最近更新时间：2025-03-06 10:34:56
此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 | 指定访问控制权限，如果指定的访问权限列表无效，则会返回错误。 | 否 |
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires |
| 否 |
file | 文件或文本内容。用户每次只能上传一个文件，且内容不能放到key元素的前面，否则返回400。 | 是 |
key | ObjectKey。如果用户想要使用文件名作为Key，可以使用 | 是 |
KSSAccessKeyId | KSSAccessKeyId。 | 视情况而定 |
policy | 请求中用于描述获准行为的安全策略。没有安全策略的请求被认为是匿名请求，只能访问公共可写空间。 | 视情况而定 |
signature | 根据Access Key Secret和policy计算的签名信息，KS3验证该签名信息从而验证该Post请求的合法性。 | 视情况而定 |
success_action_redirect, redirect | 成功上传后客户端的重定向URL。如果用户没有指定 | 否 |
success_action_status | 返回的状态码，如果没有指定，则依赖于上传的成功状态。允许值为200，201，204(默认值)。如果是200或204，KS3将返回一个状态为200或204的空文件。如果状态码为201，那么KS3将会返回一个状态码为201的XML文档。如果值无效，或者没有设定，KS3将会返回一个状态码为204的空文档。 | 否 |
x-kss-meta- | 用户元数据前缀标识。若某个头部前缀为 | 否 |
x-kss-storage-class | 设置文件的存储类型。 | 否 |
x-kss-newfilename-in-body | 控制台设置文件名后，指定返回的文件名字是否出现body中。true表示在header和body中返回；false表示只在header中返回。 | true |
tagging | 指定标签添加到对象 Default: None | 否 |
x-kss-forbid-overwrite | 同名文件是否覆盖上传，取值如下：
| 否 |
若使用KS3 托管密钥的服务器端加密，则需要以下请求头。
名称 | 描述 | 是否必选 |
|---|---|---|
x-kss-server-side-encryption | 如果存储 | 是 |
若使用客户提供的加密密钥的服务器端加密，则需要使用以下请求头 。
名称 | 描述 | 是否必选 |
|---|---|---|
x-kss-server-side-encryption-customer-key | 由用户指定KS3加密时使用的 | 是 |
x-kss-server-side-encryption-customer-algorithm | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来确认使用的解密算法。 | 是 |
x-kss-server-side-encryption-customer-key-MD5 | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。 | 是 |
该接口可以使用所有常用响应头部。获取更多信息，请点击常用响应头部。
名称 | 描述 |
|---|---|
success_action_redirect, redirect | 成功上传后客户端的重定向URL。
|
x-kss-server-side-encryption-customer-algorithm | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来确认使用的解密算法。
|
x-kss-server-side-encryption-customer-key-MD5 | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。
|
newfilename | 在控制台设置文件名后的新文件名。
|
x-kss-checksum-crc64ecma | 对象的CRC64值，用来做数据完整性校验。关于CRC64的计算标准，请参见文档：ECMA-182标准。
|
该请求不返回任何特殊错误。
用户需要对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 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。 |
FileAlreadyExists | 409 | 设置了x-kss-forbid-overwrite的值为true（表示禁止覆盖同名文件），遇到同名文件时。 |
纯净模式