FORM API

可通过客户端浏览器的表单(form),跳过中间服务器,直接将文件上传到FSS云存储,上传效率更高效。特别地，文中请求参数放在 HTTP/HTTPS body 中传递，请确保您上传表单格式符合 RFC 1867 协议规范。

请求方法

不支持options方法


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://west.cn">
9
  <input type="file" name="photo">
10
  <button type="submit">提交</button>
11
</form>