：Post Object錯誤及排查

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常見錯誤見下表：

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

  • 表單網域名稱稱大小寫敏感，如policy、key、file、OSSAccessKeyId、OSSAccessKeyId、Content-Disposition。
    重要 表單域file必須為最後一個表單域。
  • 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。

  如果您還有疑問，請參考範例程式碼：

  • C#
  • Java
  • JS
• 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

  如果您還有疑問，請參考範例程式碼：

  • C#
  • Java
  • JS

常見問題

• 怎麼指定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 Object？

  臨時使用者密鑰的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-Encoding。file表單域樣本如下：

  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-ControlContent-Type、Content-Disposition、Content-EncodingExpires等HTTP Header需要在表單域中指定，這些HTTP Header的含義請參看RFC2616 。但是Content-MD5需要在Post Header中指定。

Post Object樣本

常用連結