PostObject
調(diào)用PostObject用于通過(guò)HTML表單上傳的方式將文件（Object）上傳到指定存儲(chǔ)空間（Bucket）。
注意事項(xiàng)
要通過(guò)HTML表單上傳的方式上傳文件，您必須有
oss:PutObject權(quán)限。具體操作，請(qǐng)參見(jiàn)為RAM用戶(hù)授權(quán)自定義的權(quán)限策略。通過(guò)PostObject上傳的Object大小不能超過(guò)5 GB。
Post請(qǐng)求需要對(duì)Bucket擁有寫(xiě)權(quán)限。如果Bucket為public-read-write，可以不上傳簽名信息，否則要求對(duì)該操作進(jìn)行簽名驗(yàn)證。
與Put操作不同，Post操作使用AccessKey Secret對(duì)policy進(jìn)行簽名，計(jì)算出簽名字符串作為Signature表單域的值，OSS通過(guò)驗(yàn)證該值從而判斷簽名的合法性。
提交表單的URL為Bucket域名，不需要在URL中指定Object。即請(qǐng)求行是
POST / HTTP/1.1，不能寫(xiě)為POST /ObjectName HTTP/1.1。如果POST請(qǐng)求中包含Header簽名信息或URL簽名信息，OSS不會(huì)對(duì)此類(lèi)信息做檢查。
版本控制
在開(kāi)啟了版本控制的Bucket中發(fā)起PostObject請(qǐng)求時(shí)，OSS將為新添加的Object自動(dòng)生成唯一的版本ID，并在響應(yīng)Header中通過(guò)x-oss-version-id的形式返回。
在暫停了版本控制的Bucket中發(fā)起PostObject請(qǐng)求時(shí)，OSS將為新添加的Object自動(dòng)生成一個(gè)null的版本ID，并在響應(yīng)Header中通過(guò)x-oss-version-id的形式返回。同一個(gè)Object僅允許一個(gè)null的版本ID。
請(qǐng)求語(yǔ)法
POST / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
User-Agent: browser_data
Content-Length：ContentLength
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
key
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=oss_download.jpg
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
myuuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
mytag
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_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 OSS
--9431149156168--請(qǐng)求頭
PostObject的消息實(shí)體通過(guò)多重表單格式（multipart/form-data）編碼，在PutObject操作中參數(shù)通過(guò)HTTP請(qǐng)求頭傳遞，在PostObject操作中參數(shù)作為消息體中的表單域傳遞。
PostObject操作過(guò)程中不支持通過(guò)傳入x-oss-tagging請(qǐng)求頭的方式為Object添加標(biāo)簽。您可以在PostObject操作完成后調(diào)用PutObjectTagging接口為Object添加標(biāo)簽。
名稱(chēng) | 類(lèi)型 | 是否必選 | 描述 |
Content-Type | 字符串 | 否 | 指定文件的類(lèi)型和網(wǎng)頁(yè)的編碼，確定瀏覽器讀取文件的形式和編碼方式。 Post操作提交表單編碼必須為 boundary為邊界字符串，是由表單隨機(jī)生成的一個(gè)隨機(jī)值，無(wú)需指定。如果通過(guò)SDK拼接表單，則SDK也會(huì)生成一個(gè)隨機(jī)值。 |
此接口還需要包含Host、Date等公共請(qǐng)求頭。更多信息，請(qǐng)參見(jiàn)公共請(qǐng)求頭（Common Request Headers）。
表單元素
以下表格列舉了POST V1和V4簽名共有的表單元素。關(guān)于POST V4簽名獨(dú)有的表單元素，請(qǐng)參見(jiàn)V4簽名表單。關(guān)于POST V1簽名獨(dú)有的表單元素，請(qǐng)參見(jiàn)V1簽名表單。
file必須為最后一個(gè)表單域，除file以外的其他表單域無(wú)順序要求。
所有表單域的key大小不能超過(guò)8 KB，表單域的value不能超過(guò)2 MB。
名稱(chēng) | 類(lèi)型 | 是否必選 | 描述 |
Cache-Control | 字符串 | 否 | 指定該Object被下載時(shí)網(wǎng)頁(yè)的緩存行為。更多信息，請(qǐng)參見(jiàn)RFC 2616。 默認(rèn)值：無(wú) |
Content-Disposition | 字符串 | 否 | 指定該Object被下載時(shí)的名稱(chēng)。更多信息，請(qǐng)參見(jiàn)RFC 2616。 默認(rèn)值：無(wú) |
Content-Encoding | 字符串 | 否 | 指定該Object被下載時(shí)的內(nèi)容編碼格式。更多信息，請(qǐng)參見(jiàn)RFC 2616。 默認(rèn)值：無(wú) |
Expires | 字符串 | 否 | 過(guò)期時(shí)間。更多信息，請(qǐng)參見(jiàn)RFC 2616。 默認(rèn)值：無(wú) |
policy | 字符串 | 是，有條件 | policy規(guī)定了請(qǐng)求表單域的合法性。不包含policy表單域的請(qǐng)求被認(rèn)為是匿名請(qǐng)求，并只能訪(fǎng)問(wèn)public-read-write的Bucket。 默認(rèn)值：無(wú) 限制：當(dāng)Bucket為非public-read-write或者提供了OSSAccessKeyId（或Signature）表單域時(shí)，必須提供policy表單域。 重要 表單和policy必須使用UTF-8編碼，且policy表單域要經(jīng)過(guò)Base64編碼。 |
x-oss-server-side-data-encryption | 字符串 | 否 | 僅當(dāng)加密方式為KMS時(shí)，通過(guò)此選項(xiàng)將默認(rèn)加密算法AES256修改為SM4。 取值：SM4 |
x-oss-server-side-encryption-key-id | 字符串 | 否 | 表示KMS托管的用戶(hù)主密鑰。 此選項(xiàng)僅當(dāng)x-oss-server-side-encryption值為KMS時(shí)有效。 |
x-oss-content-type | 字符串 | 否 | 由于瀏覽器會(huì)自動(dòng)在文件表單域中增加Content-Type，為了解決此問(wèn)題，OSS支持用戶(hù)在Post請(qǐng)求體中增加x-oss-content-type，該項(xiàng)允許用戶(hù)指定Content-Type，且擁有最高優(yōu)先級(jí)。 優(yōu)先級(jí)順序：x-oss-content-type > file表單域的Content-Type 默認(rèn)值：無(wú) |
x-oss-forbid-overwrite | 字符串 | 否 | 指定PostObject操作時(shí)是否覆蓋同名Object。 當(dāng)目標(biāo)Bucket處于已開(kāi)啟或已暫停的版本控制狀態(tài)時(shí)，x-oss-forbid-overwrite請(qǐng)求Header設(shè)置無(wú)效，即允許覆蓋同名Object。
設(shè)置x-oss-forbid-overwrite請(qǐng)求Header會(huì)導(dǎo)致QPS處理性能下降，如果您有大量的操作需要使用x-oss-forbid-overwrite請(qǐng)求頭（QPS > 1000），請(qǐng)聯(lián)系技術(shù)支持，避免影響您的業(yè)務(wù)。 |
x-oss-object-acl | 字符串 | 否 | 在文件表單域中指定Object的訪(fǎng)問(wèn)權(quán)限。此項(xiàng)支持在文件表單域中指定。 取值：
關(guān)于訪(fǎng)問(wèn)權(quán)限的更多信息，請(qǐng)參見(jiàn)設(shè)置Object ACL。 |
x-oss-storage-class | 字符串 | 否 | 指定Object的存儲(chǔ)類(lèi)型。 對(duì)于任意存儲(chǔ)類(lèi)型的Bucket，如果上傳Object時(shí)指定此參數(shù)，則此次上傳的Object將存儲(chǔ)為指定的類(lèi)型。例如在IA類(lèi)型的Bucket中上傳Object時(shí)，如果指定x-oss-storage-class為Standard，則該Object直接存儲(chǔ)為Standard。 取值：
關(guān)于更多信息，請(qǐng)參見(jiàn)存儲(chǔ)類(lèi)型介紹。 |
key | 字符串 | 是 | 上傳Object的名稱(chēng)，無(wú)需編碼。如果名稱(chēng)包含路徑，例如 默認(rèn)值：無(wú) |
success_action_redirect | 字符串 | 否 | 上傳成功后客戶(hù)端跳轉(zhuǎn)到的URL。如果未指定該表單域，返回結(jié)果由success_action_status表單域指定。如果上傳失敗，OSS返回錯(cuò)誤碼，并不進(jìn)行跳轉(zhuǎn)。 默認(rèn)值：無(wú) |
success_action_status | 字符串 | 否 | 未指定success_action_redirect表單域時(shí)，該表單域指定了上傳成功后返回給客戶(hù)端的狀態(tài)碼。 有效值：200、201、204（默認(rèn)）。
|
x-oss-meta-* | 字符串 | 否 | 用戶(hù)指定的user meta值。 默認(rèn)值：無(wú) 如果請(qǐng)求中攜帶以x-oss-meta-為前綴的表單域，則視為user meta，例如 說(shuō)明 一個(gè)Object可以有多個(gè)類(lèi)似的參數(shù)，但所有的user meta總大小不能超過(guò)8 KB。 |
x-oss-security-token | 字符串 | 否 | 安全令牌。僅當(dāng)使用STS構(gòu)造URL簽名時(shí)，才需要設(shè)置此參數(shù)。您可以通過(guò)調(diào)用STS服務(wù)的AssumeRole接口獲取安全令牌。 默認(rèn)值：無(wú) |
file | 字符串 | 是 | 文件或文本內(nèi)容，無(wú)需編碼。瀏覽器會(huì)自動(dòng)根據(jù)文件類(lèi)型來(lái)設(shè)置Content-Type，并覆蓋用戶(hù)的設(shè)置。OSS一次只能上傳一個(gè)文件。 默認(rèn)值：無(wú) 重要 file必須為最后一個(gè)表單域。 |
響應(yīng)頭
名稱(chēng) | 類(lèi)型 | 示例值 | 描述 |
x-oss-server-side-encryption | 字符串 | KMS | 如果請(qǐng)求Header中指定了x-oss-server-side-encryption，則響應(yīng)Header中將包含該頭部，指明所使用的服務(wù)器端加密算法。 |
Content-MD5 | 字符串 | 1B2M2Y8AsgTpgAmY7PhC**** | 表示文件的MD5值。 重要 文件的MD5值指的是客戶(hù)端上傳完成后獲取到的文件MD5，并非響應(yīng)體的MD5。 |
x-oss-hash-crc64ecma | 字符串 | 316181249502703**** | 表示文件的CRC64值。 |
x-oss-version-id | 字符串 | CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** | 表示文件的版本ID。僅當(dāng)您將文件上傳至已開(kāi)啟版本控制狀態(tài)的Bucket時(shí)，會(huì)返回該響應(yīng)頭。 |
此接口還涉及其他公共響應(yīng)頭，例如Date、x-oss-request-id等。更多信息，請(qǐng)參見(jiàn)公共響應(yīng)頭（Common Response Headers）。
響應(yīng)元素
名稱(chēng) | 類(lèi)型 | 描述 |
PostResponse | 容器 | 保存Post請(qǐng)求結(jié)果的容器。 子節(jié)點(diǎn)：Bucket、ETag、Key、Location |
Bucket | 字符串 | Bucket名稱(chēng)。 父節(jié)點(diǎn)：PostResponse |
ETag | 字符串 | ETag (Entity Tag) 在每個(gè)Object生成的時(shí)候被創(chuàng)建。Post請(qǐng)求創(chuàng)建的Object，ETag值是基于一定計(jì)算規(guī)則生成的唯一值，但不是其內(nèi)容的MD5值。ETag值可以用于檢查該Object內(nèi)容是否發(fā)生變化。 父節(jié)點(diǎn)：PostResponse |
Location | 字符串 | 新創(chuàng)建Object的URL。 父節(jié)點(diǎn)：PostResponse |
示例
請(qǐng)求示例：
POST / HTTP/1.1 Host: oss-example.oss-cn-hangzhou.aliyuncs.com Content-Length: 344606 Content-Type: multipart/form-data; boundary=9431149156168 --9431149156168 Content-Disposition: form-data; name="key" /user/a/objectName.txt --9431149156168 Content-Disposition: form-data; name="success_action_status" 200 --9431149156168 Content-Disposition: form-data; name="Content-Disposition" content_disposition --9431149156168 Content-Disposition: form-data; name="x-oss-meta-uuid" uuid --9431149156168 Content-Disposition: form-data; name="x-oss-meta-tag" metadata --9431149156168 Content-Disposition: form-data; name="OSSAccessKeyId" 44CF9590006BF252**** --9431149156168 Content-Disposition: form-data; name="policy" eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ== --9431149156168 Content-Disposition: form-data; name="Signature" kZoYNv66bsmc10+dcGKw5x2P**** --9431149156168 Content-Disposition: form-data; name="file"; filename="MyFilename.txt" Content-Type: text/plain abcdefg --9431149156168 Content-Disposition: form-data; name="submit" Upload to OSS --9431149156168--返回示例：
HTTP/1.1 200 OK x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e Date: Fri, 24 Feb 2014 06:03:28 GMT ETag: "5B3C1A2E053D763E1B002CC607C5****" Connection: keep-alive Content-Length: 0 x-oss-hash-crc64ecma: 316181249502703**** Content-MD5: 1B2M2Y8AsgTpgAmY7PhC**** Server: AliyunOSS
錯(cuò)誤碼
錯(cuò)誤碼 | HTTP狀態(tài)碼 | 描述 |
FieldItemTooLong | 400 | 表單域key的大小不允許超過(guò)8 KB，表單域value的大小不允許超過(guò)2 MB。 |
InvalidArgument | 400 | 無(wú)論Bucket是否為public-read-write，一旦上傳OSSAccessKeyId、policy、Signature表單域中的任意一個(gè)，則另兩個(gè)表單域?yàn)楸剡x項(xiàng)。如果缺失，將返回此錯(cuò)誤。 |
InvalidDigest | 400 | 用戶(hù)上傳了Content-MD5請(qǐng)求Header，OSS會(huì)計(jì)算body的Content-MD5并檢查一致性，如果不一致，將返回此錯(cuò)誤。 |
EntityTooLarge | 400 | 請(qǐng)求的body總長(zhǎng)度不允許超過(guò)5 GB。如果文件長(zhǎng)度過(guò)大，將返回此錯(cuò)誤。 |
InvalidEncryptionAlgorithmError | 400 | 如果上傳時(shí)指定了x-oss-server-side-encryption Header請(qǐng)求域，則必須設(shè)置其值為AES256、KMS或SM4。如果設(shè)置為其他值，將返回此錯(cuò)誤。 |
IncorrectNumberOfFilesInPOSTRequest | 400 | Post請(qǐng)求中文件個(gè)數(shù)無(wú)效。Post請(qǐng)求中只能有一個(gè)file表單域。 |
FileAlreadyExists | 409 | 請(qǐng)求的Header中攜帶x-oss-forbid-overwrite=true時(shí)，表示禁止覆蓋同名文件。如果文件已存在，將返回此錯(cuò)誤。 |
KmsServiceNotEnabled | 403 | 將x-oss-server-side-encryption指定為KMS，但沒(méi)有預(yù)先購(gòu)買(mǎi)KMS套件。 |
FileImmutable | 409 | Bucket內(nèi)的數(shù)據(jù)處于被保護(hù)狀態(tài)時(shí)，如果您嘗試刪除或修改這些數(shù)據(jù)，將返回此錯(cuò)誤碼。 |
POST policy
policy表單域是一種安全策略，用于定義通過(guò)HTML表單上傳文件到OSS時(shí)的權(quán)限限制和約束條件。policy表單域通過(guò)JSON格式定義，通過(guò)多項(xiàng)參數(shù)限制上傳操作，例如允許上傳的Bucket名稱(chēng)、Object前綴、有效期、允許的HTTP方法、上傳內(nèi)容的大小限制、內(nèi)容類(lèi)型限制等。
關(guān)于POST請(qǐng)求V4簽名的policy詳細(xì)介紹，請(qǐng)參見(jiàn)POST請(qǐng)求V4簽名的policy
關(guān)于POST請(qǐng)求V1簽名的policy詳細(xì)介紹，請(qǐng)參見(jiàn)POST請(qǐng)求V1簽名的policy。
POST signature
POST signature是指在使用PostObject上傳方式時(shí)，為保證上傳請(qǐng)求的安全性，OSS要求每個(gè)上傳請(qǐng)求都攜帶一個(gè)簽名（Signature），用于確保上傳請(qǐng)求的合法性和安全性。
關(guān)于POST請(qǐng)求V4簽名的詳細(xì)介紹，請(qǐng)參見(jiàn)POST請(qǐng)求V4簽名。
關(guān)于POST請(qǐng)求V1簽名的詳細(xì)介紹，請(qǐng)參見(jiàn)POST請(qǐng)求V1簽名。
常見(jiàn)問(wèn)題
報(bào)錯(cuò)Your proposed upload exceeds the maximum allowed size.如何處理？
問(wèn)題原因：上傳文件的大小超出content-length-range指定的文件大小范圍。
解決方法：content-length-range用于指定上傳文件的最小和最大允許大小，單位為字節(jié)。例如，您需要上傳的文件大小為1 GB，則content-length-range可以設(shè)置為["content-length-range", 1, 1073741824]。
更多參考
關(guān)于Web端表單直傳OSS的示例，請(qǐng)參見(jiàn)JavaScript客戶(hù)端簽名直傳。
關(guān)于調(diào)用PostObject接口的常見(jiàn)錯(cuò)誤及解決方法，請(qǐng)參見(jiàn)PostObject常見(jiàn)錯(cuò)誤及排查。