Post Object簡介

Post Object使用表單上傳檔案到OSS。Post Object的消息實體通過 多重表單格式multipart/form-data 編碼,詳細說明請參看RFC 2388。PutObject中參數通過HTTP要求標頭傳遞,Post Object參數則作為消息體的表單域傳遞。

Post Object消息包括消息頭(Header)和消息體(Body)。Header和Body之間,由\r\n--{boundary}分割。Body由一系列的表單域構成,表單域格式如下:

Content-Disposition: form-data; name="{key}"\r\n\r\n{value}\r\n--{boundary}

常見的Header有Host、User-Agent、Content-Length、Content-Type、Content-MD5等,表單域欄位有key、OSSAccessKeyId、Signature、Content-Disposition、object meta(x-oss-meta-*)、x-oss-security-token、其它HTTP Header(Cache-Control/Content-Type/Cache-Control/Content-Type/Content-Disposition/Content-Encoding/Expires/Content-Encoding/Expires)、file等。表單域中file必須是最後一個。

更多詳細的介紹請參看Post Object

Post Object常見錯誤

Post Object常見錯誤見下表:

序號 錯誤 原因 解法
1 ErrorCode: MalformedPOSTRequest ErrorMessage: The body of your POST request is not well-formed multipart/form-data 表單域格式不符合要求 表單域格式請參看錶後的 Post Object表單域格式
2 ErrorCode: InvalidAccessKeyId ErrorMessage: The OSS Access Key Id you provided does not exist in our records. AccessKeyID禁用或不存在,或者過期的臨時用戶AccessKeyID,或者臨時用戶沒有提供STS Token 排查方法請參看InvalidAccessKeyId錯誤排查
3 ErrorCode: AccessDenied ErrorMessage: Invalid according to Policy: Policy expired. 表單域policy中的expiration過期 請調整policy中的expiration,注意expiration的格式 ISO8601 GMT
4 ErrorCode: AccessDenied ErrorMessage: SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. Check your key and signing method. 簽名錯誤 簽名方法請參看下面的Post Object的簽名
5 ErrorCode: InvalidPolicyDocument ErrorMessage: Invalid Policy: Invalid Simple-Condition: Simple-Conditions must have exactly one property specified. 請求中policy至少包含一個condition 請參看錶後的Post Object的Policy格式
6 ErrorCode: InvalidPolicyDocument ErrorMessage: Invalid Policy: Invalid JSON: unknown char e 請求中的policy格式不正確 請檢查policy格式,"是否加缺失,逸出字元是否加\
7 ErrorCode: InvalidPolicyDocument ErrorMessage: Invalid Policy: Invalid JSON: , or ] expected 請求中的policy格式不正確 請檢查policy中是否缺少,]
8 ErrorCode: AccessDenied ErrorMessage: Invalid according to Policy: Policy Condition failed: [“starts-with”, “$key”, “user/eric/“] 請求指定的keypolicy限定的不符 請檢查請求中表單域key的值
9 ErrorCode: AccessDenied ErrorMessage: Invalid according to Policy: Policy Condition failed: [“eq”, “$bucket”, “mingdi-bjx”] 請求指定bucketpolicy限定的不符 請檢查endpoint中的bucket的值
10 ErrorCode: AccessDenied ErrorMessage: Invalid according to Policy: Policy Condition failed: [“starts-with”, “$x-oss-meta-prop”, “prop-“] 請求指定的檔案元數據x-oss-meta-prop與policy限定的不符 請檢查請求中的x-oss-meta-prop的值
11 ErrorCode: AccessDenied ErrorMessage: Invalid according to Policy: Policy Condition failed: [“eq”, “${field}”, “${value}”] 表單域中指定的{field}與policy中限定的值不符,或者在請求中沒有指定 請檢查請求中的{field}的值
12 ErrorCode: AccessDenied ErrorMessage: You have no right to access this object because of bucket acl. 目前使用者無許可權 請參看OSS許可權問題及排查
13 ErrorCode: InvalidArgument ErrorMessage: The bucket POST must contain the specified ‘key’. If it is specified, please check the order of the fields 表單域沒有指定key,或者放在了表單域file 請添加表單域key或調整順序
  • Post Object表單域格式

    Post Object請求格式,有以下注意點:

    • Header一定要有Content-Type: multipart/form-data; boundary={boundary}
    • Header和body之間由\r\n--{boundary} 分割。
    • 表單域格式
      Content-Disposition: form-data;
              name="{key}"\r\n\r\n{value}\r\n--{boundary}
    • 表單域file必須為最後一個表單域。
    • 表單網域名稱稱大小寫敏感,如policy、key、file、OSSAccessKeyId、OSSAccessKeyId、Content-Disposition。
    • Bucket為public-read-write時,可以不指定表單域OSSAccessKeyId、policy、Signature;一旦指定OSSAccessKeyId、policy、 Signature中的任意一個,無論bucket是否為public-read-write,則另兩個必須指定。

    下面是Post Object請求的樣本:

    POST / HTTP/1.1
    User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-CN; rv:1.9.2.6)
    Content-Type: multipart/form-data; boundary=9431149156168
    Host: mingdi-hz.oss-cn-hangzhou.aliyuncs.com
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Connection: keep-alive
    Content-Length: 5052
    --9431149156168
    Content-Disposition: form-data; name="key"
    test-key
    --9431149156168
    Content-Disposition: form-data; name="Content-Disposition"
    attachment;filename=D:\img\1.png
    --9431149156168
    Content-Disposition: form-data; name="OSSAccessKeyId"
    2NeL********j2Eb
    说明
    • 上面樣本請求中\r\n顯示為新行,即換行,後面的樣本請求類似。
    • 上面的樣本為請求的部分內容,完整的請求請參看Post Object

    如果您還有疑問,請參考範例程式碼: 

  • Post Object的Policy格式

    Post Object請求的policy表單域用於驗證請求的合法性,聲明了Post Object請求必須滿足的條件。限定條件為:

    • UTF-8格式的Json文本,經過base64編碼後放在表單域policy中。
    • Policy中必須包含expiration和condtions,其中condtions至少有一項。

    下面是base64編碼前的policy樣本:

    {
        "expiration": "2018-01-01T12:00:00.000Z",
        "conditions": [
            ["content-length-range", 0, 104857600]
        ]
    }

    expiration項指定了請求的過期時間, ISO8601 GMT 時間格式;如 2018-01-01T12:00:00.000Z指定請求必鬚髮生在2018年1月1日12點前。

    Post Policy支援的限定條件(Conditions)如下:

    名稱 描述 樣本
    bucket 上傳檔案的Bucket名稱。支援精確匹配方式。 {“bucket”: “johnsmith” } 或 [“eq”, “$bucket”, “johnsmith”]
    key 上傳檔案的名稱。支援精確匹配和首碼匹配方式。 [“starts-with”, “$key”, “user/etc/“]
    content-length-range 上傳檔案允許的最小、最大長度。 [“content-length-range”, 0, 104857600]
    x-oss-meta-* 指定的object meta。支援精確匹配和首碼匹配方式。 [“starts-with”, “$x-oss-meta-prop”, “prop-“]
    success_action_redirect 上傳成功後的跳轉URL地址。支援精確匹配和首碼匹配方式。 [“starts-with”, “$success_action_redirect”, “http://www.aliyun.com“]
    success_action_status 未指定success_action_redirect時,上傳成功後的返回狀態碼。支援精確匹配和首碼匹配方式。 [“eq”, “$success_action_status”, “204”]
    Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires等 HTTP要求標頭,作為表單域傳遞。支援精確匹配和首碼匹配方式。 [“eq”, “$Content-Encoding”, “ZLIB”]

    Post Policy有以下逸出字元,使用 \ 轉義。

    逸出字元 描述
    / 斜杠
    \ 反斜線
    雙引號
    $ 美元符
    \b 空格
    \f 換頁
    \n 換行
    \r 回車
    \t 水平定位字元
    \uxxxx Unicode字元

    Post Policy更詳細的說明,請參考 Post Policy

  • Post Object的簽名

    對於驗證的Post請求,請求中必須包含AccessKeyID、policy、Signature表單域。計算簽名的流程如下:

    1. 建立一個UTF-8編碼的policy。
    2. 將policy進行base64編碼,其值即為policy表單域該填入的值,將該值作為將要簽名的字元串。
    3. 使用AccessKeySecret對要簽名的字元串進行簽名,先用hmac-sha1雜湊,再base64編碼;簽名方法與Header簽名的方法相同。
    即:
    Signature = base64(hmac-sha1(AccessKeySecret, base64(policy)))

    計算出的簽名在表單域Signature中指定,如下所示:

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

    如果您還有疑問,請參考範例程式碼: 

常見問題

  • 怎麼指定key?

    key即object name,在表單域key中指定,樣本如下:

    Content-Disposition: form-data; name="key"
    {key}
    --9431149156168
  • 怎麼指定object內容?

    Object內容通過表單域file中指定,樣本如下:

    Content-Disposition: form-data; name="file"; filename="images.png"
    Content-Type: image/png
    {file-content}
    --9431149156168
    说明
    • 表單域file必須是表單中的最後一個域,即表單域file必須放在所有表單域後。
    • filename是上傳的本地檔案名稱,而不是object name。
  • 怎麼指定object類型content-type?

    Object類型在表單域file中指定Content-Type,而不是Header中的Content-Type,樣本如下:

    Content-Disposition: form-data; name="file"; filename="images.png"
    Content-Type: image/png
    {file-content}
    --9431149156168
  • 怎麼指定object內容md5校驗content-md5?

    在Post Object要求標頭中指定Content-MD5,注意MD5值是整個body的MD5,即所有表單域的MD5。請求Header樣本如下:

    POST / HTTP/1.1
    User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-CN; rv:1.9.2.6)
    Content-Type: multipart/form-data; boundary=9431149156168
    Content-MD5: tdqHe4hT/TuKb7Y4by+nJg==
    Host: mingdi-hz.oss-cn-hangzhou.aliyuncs.com
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Connection: keep-alive
    Content-Length: 5246
    --9431149156168
  • 怎麼指定簽名Signature?

    簽名的計算方法請參看PostObject中的簽名 , 簽名通過表單域Signature攜帶。

  • 怎麼使用臨時用戶STS Token執行Post Oject?

    臨時用戶密鑰的AccessKeyID、AccessKeySecret用法跟主用戶、子用戶相同,Token放在表單域x-oss-security-token中攜帶。樣本如下:

    Content-Disposition: form-data; name="Signature"
    5L0+KaeugxYygfqWLJLoy0ehOmA=
    --9431149156168
    Content-Disposition: form-data; name="x-oss-security-token"
    {Token}
    --9431149156168
    说明
    如果您想更多了解更多存取控制的資訊,請參看阿里雲存取控制
  • 怎麼指定上傳回調(callback)?

    上傳回調(callback)通過表單域callback攜帶。樣本如下:

    Content-Disposition: form-data; name="callback"
    eyJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCIsICJjYWxsYmFja0JvZHkiOiAiZmlsZW5hbWU9JHtvYmplY3R9JnNpemU9JHtzaXplfSZtaW1lVHlwZT0ke21pbWVUeXBlfSIsICJjYWxsYmFja1VybCI6ICJodHRwOi8vb3NzLWRlbW8uYWxpeXVuY3MuY29tOjIzNDUwIn0=
    --9431149156168

    Callback的自訂參數也是通過表單域攜帶。樣本如下:

    Content-Disposition: form-data; name="x:var1"
    {var1-value}
    --9431149156168
    说明
    如果您想了解callback更多內容,請參看上傳回調
  • 怎麼指定Content-Transfer-Encoding?

    在表單域file中指定Content-Transfer-Encodingfile表單域樣本如下:

    Content-Disposition: form-data; name="file"; filename="images.png"
    Content-Type: image/png
    Content-Transfer-Encoding: base64
    {file-content}
    --9431149156168
  • 怎麼指定用戶自訂元資訊Object User Meta?

    用戶自訂元資訊,可以表單域指定,樣本如下:

    Content-Disposition: form-data; name="x-oss-meta-uuid"
    {uuid}
    --9431149156168
    Content-Disposition: form-data; name="x-oss-meta-tag"
    {tag}
    --9431149156168
    说明
    檔案元資訊更詳細的說明,請參看檔案元資訊Object Meta
  • 怎麼指定限定條件expiration、Key、Bucket、size、header等?

    OSS的Post Object支援豐富的條件限制,可以滿足高安全性要求。限定條件Conditions可以通過表單域policy 指定,詳細的說明請參看上面的Post Object的Policy格式。下面是一個policy的樣本:

    {
        "expiration": "2018-01-01T12:00:00.000Z",
        "conditions": [
            ["eq", "$bucket", "md-hz"],
            ["starts-with", "$key", "md/conf/"],
            ["content-length-range", 0, 104857600]
        ]
    }

    上面的policy,用戶的Post Object操作的限定條件如下:

    • bucket必須是md-hz
    • key必須以md/conf/開頭。
    • 是上傳的檔案長度必須在100M以下。
    • 請求時間在2018-01-01T12:00:00.000Z之前。
  • 怎麼指定Cache-Control、Content-Type、Content-Disposition、 Content-Encoding、Expires等HTTP Header?

    Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires等HTTP Header需要在表單域中指定,這些HTTP Header的含義請參看RFC2616 。但是Content-MD5需要在Post Header中指定。

Post Object樣本

常用連結