FORM API

可通過客戶端瀏覽器的表單(form),跳過中間服務器,直接將文件上傳到FSS云存儲,上傳效率更高效。特別地，文中請求參數放在 HTTP/HTTPS body 中傳遞，請確保您上傳表單格式符合 RFC 1867 協議規范。

請求方法


1
curl -X POST \
2
    http://fss-my.vhostgo.com/<bucket> \
3
    -F "Authorization: WESTYUN <Operator>:<Signature>" \
4
    -F "Date: <Wed, 29 Oct 2014 11:26:58 GMT>"\
5
    -F "Policy:<policy>"
6
    # 其他可選參數...

域名

fss-<區域>.vhostgo.com

bucket、path

<> 是參數內容，是需要用戶填寫的，填寫時，把 <> 去掉。

bucket，是創建的桶名；

Authorization

關于認證鑒權,policy，詳見認證鑒權。
鑒權所需參數均在form表單中提交

上傳文件

文件大小超過 100M 后，建議使用大文件上傳；移動端或者弱網環境上傳，推薦使用 REST API 上傳文件。

上傳參數

參數(不區分大小寫)	必選	類型	說明
save-key	`是`	string	文件保存路徑，可用占位符，見路徑設置
expiration	`是`	string	請求的過期時間，UNIX UTC 時間戳，單位秒。不能超過 30 分鐘
date	`是`	string	請求的日期時間，等效于簽名認證中的 Date 如 Wed, 22 Apr 2020 02:26:58 GMT 或者 2020-04-22 10:26:58
return-url	否	string	同步通知 URL，見通知規則
notify-url	否	string	異步通知 URL，見通知規則
Content-MD5	否	string	上傳文件的 MD5 值，如果請求中文件太大計算 MD5 不方便，可以為空
Content-Type	否	string	文件類型，默認使用文件擴展名作為文件類型
Content-Secret	否	string	文件密鑰，用于保護文件，防止文件被直接訪問，見Content-Secret 參數說明
allow-file-type	否	string	允許上傳的文件擴展名，以 , 分隔。如 jpg,jpeg,png
content-length-range	否	string	文件大小限制，格式：min,max，單位：字節。如 102400,1024000，表示允許上傳 100Kb～1Mb 的文件
x-gmkerl-thumb	否	string	圖片預處理參數，見圖片處理
x-west-meta-ttl	否	string	文件元信息, 指定文件的生存時間，單位天，最大支持180天
x-west-overwrite	否	string	上傳文件時覆蓋已存在文件，默認為false
b64encoded	否	string	對通過 Base64 編碼上傳的文件進行 Base64 解碼，值為 on
ext-param	否	string	額外參數，見 ext-param

注

每個上傳請求只能上傳一個文件
若請求中帶有預處理參數（x-gmkerl-thumb），圖片處理后再保存

響應信息

上傳成功：返回 200 或訪問指定的 URL（見通知規則）。
上傳失敗：返回相應的出錯信息，具體請參閱「API 錯誤碼表」。

通知規則

return-url 參數說明

如果沒有設置 return-url，文件上傳完成后，結果信息在響應體中返回。
如果設置了 return-url，文件上傳完成后，結果信息以 Query String 的形式追加到 return-url 指定的 URL 后，并訪問。例如，return-url 為 http://www.yourdomain.com/return/，訪問的 URL 是：http://yourdomain.com/return/?code=200&message=ok&url=%2F2011%2F12%2Ffd0.mp3&time=1332129461
結果信息的參數名及說明如下：

參數	說明
code	狀態碼，200 表示上傳成功
message	URL encoding 的描述信息，ok 表示上傳成功，其他的表示錯誤信息
url	URL encoding 的文件保存路徑
time	UNIX UTC 時間戳，單位秒
sign	簽名，詳見回調簽名
ext-param	額外參數，form表單上傳的ext-param參數

notify-url 參數說明

如果沒有設置 notify-url，不發起異步通知。
如果設置了 notify-url，文件上傳完成后，向 notify-url 發送 HTTP POST 請求，請求體是回調信息。回調信息是 URL encoding 的字符串，內容和 return-url 中的結果信息相同?；卣{通知簽名，見簽名認證，它提供給客戶端用于驗證回調通知的合法性。

路徑設置

save-key 支持的設置類型：

類型	格式	說明
絕對值	String	指定具體的路徑，如: /path/to/file.txt
時間類	{year} {mon} {day} {hour} {min} {sec}	日期、時間相關內容（UTC 時間）
md5類	{filemd5}	文件的 md5 值
隨機類	{random} {random32}	16 位或 32 位隨機字符和數字
文件名	{filename} {suffix} {.suffix}	上傳文件的文件名及擴展名

舉例說明

例 1：時間類 + 隨機類


xxxxxxxxxx
4
1
上傳文件名：west.jpg 
2
UTC 時間：2023-01-01 8:8:8
3
save-key：/{year}/{mon}/{day}/west_{random32}{.suffix}
4
保存路徑為：/2023/01/01/west_b92c9cc21ce6a88ea696705c88b57c3f.jpg

例 2：時間類 + 文件名


xxxxxxxxxx
4
1
上傳文件名：west.jpg
2
UTC 時間：2023-01-01 8:8:8
3
save-key：/{year}/{mon}/{day}/{hour}_{min}_{sec}_{filename}{.suffix}
4
保存路徑為：/2023/01/01/8_8_8_west.jpg

ext-param

當使用 return-url 或 notify-url 參數發送返回信息或回調信息時，結果信息（詳見通知規則）僅包含FSS云儲存指定的內容，無法回傳用戶自定義的內容。如果需要回傳自定義的內容，可以指定 ext-param 參數。

自定義的內容必須是 UTF-8 編碼，且長度不能超過 255 個字節。
notify-url 回調是異步進行的，如果回調信息需要區分自定義內容來自那個上傳請求，可以在 ext-param 參數中添加個 clientId_xxx 標識。

回調簽名

sign 算法

sign 是根據 code、url、time 拼接后進行 MD5 處理得到。拼接時需注意 URL 的編碼與解碼問題

例如，code：200

url：'westtest/2023/5/27/upload_6Wf5fyz9uEkveHoSEzf3A7265U1IV6yp.jpg'

time：1434539183

拼接后的字符串是 200westtest%2F2023%2F5%2F26%2Fupload_00vI6jK3i4i661g8bUwr3DYXrs1qJ7CB.jpg1434539183 sign 是 'c631a75699eb510ad116543cfee07a19'

FORM示例

請在使用前，將Action的URL改為自己的桶URL，且將Authorization設置為正確的權限認證代碼，建議將type為text的表單類型改為hidden


xxxxxxxxxx
11
1
<form action="http://fss-my.vhostgo.com/westtest" method="post" enctype="multipart/form-data">
2
  date:<input type="text" name="date" value="2023-05-30 09:16:52">
3
  Authorization:<input type="text" name="Authorization" value="WESTYUN westtest:xxxxxxx">
4
  policy:<input type="text" name="policy" value="eyJzYXZlLWtleSI6Ii97e9ey5zdWZmaXh9IiwiZXhwaXJhdGlvbiI6MTgwMH0=">
5
  save-key:<input type="text" name="save-key" value="{year}/{mon}/{day}/west_{random32}{.suffix}">
6
  expiration:<input type="text" name="expiration" value="1800">
7
  content-length-range:<input type="text" name="content-length-range" value="1024,1024000">
8
  return-url:<input type="text" name="return-url" value="http://35.com">
9
  <input type="file" name="photo">
10
  <button type="submit">提交</button>
11
</form>