REST API

基于 RESTful 架构的 API，您可以使用任何编程语言发送 HTTP/HTTPS 请求。所有请求参数均通过 HTTP/HTTPS 请求头以 Key: Value 的形式传递。
AWS S3兼容，查看S3 API

请求方法


xxxxxxxxxx
5
1
curl -X GET \
2
    http://fss-my.vhostgo.com/<bucket>/<path> \
3
    -H "Authorization: WESTYUN <Operator>:<Signature>" \
4
    -H "Date: <Wed, 29 Oct 2014 11:26:58 GMT>"\
5
    # 其他可选参数...

域名

fss-<区域>.vhostgo.com

bucket、path

<> 是参数内容，是需要用户填写的，填写时，把 <> 去掉。

bucket，是创建的桶名；path，文件/文件夹的路径。

并发请求限制

单个桶更新请求并发数不超过100个,GET/HEAD请求不限

Authorization

关于认证鉴权，详见认证鉴权。

上传文件

在上传图片文件时，可以设置预处理参数，图片会处理后再保存。

PUT /<bucket>/<path_to_file>

上传参数

参数	必选	类型	说明
Content-Length	`是`	string	请求内容长度
Content-MD5	否	string	上传文件的 MD5 值，如果请求中文件太大计算 MD5 不方便，可以为空
Content-Type	否	string	文件类型，默认使用文件扩展名作为文件类型常见mine类型
Content-Secret	否	string	文件密钥，用于保护文件，防止文件被直接访问，见 Content-Secret 参数说明
x-west-meta-x	否	string	文件元信息，见 Metadata
x-west-meta-ttl	否	string	文件元信息, 指定文件的生存时间，单位天，最大支持180天，见 Metadata
x-west-overwrite	否	string	上传文件时覆盖已存在文件，默认为false
x-west-automkdir	否	string	上传文件时目录不存在自动创建，默认false
x-gmkerl-thumb	否	string	图片预处理参数，见图片处理
x-west-async	否	string	true表示异步处理

注

单线程文件上传大小最大支持1G,超过1G的文件请使用文件分块上传,超过100M的文件也推荐使用文件分块上传
将大量文件同时存储到同一个目录下可能会影响性能,所以建议当文件过多时,存储于不同子目录。

响应信息

上传成功：返回 200，当上传文件是图片且设置 x-gmkerl-xxx 时，包含图片基本信息（包括图片宽、高、格式、帧数），例如：


xxxxxxxxxx
1
1
  HTTP/1.1 200 OK x-west-width: 200 x-west-height: 150 x-west-file-type: JPEG

上传失败：返回相应的出错信息，具体请参阅「API 错误码表」。

Content-Secret 参数说明

文件设置 Content-Secret 后，文件将不能被直接访问，若需访问，需要在 URL 后加上「间隔标识符」和「文件密钥」。如：间隔符为 !，Content-Secret 为 test，图片访问方式为： http://fss-my.vhostgo.com/westtest/example/secret.jpg!test
间隔标识符用于分隔文件 URL 和文件密钥，有 3 种可选，分别是：!（感叹号/默认值）、-（中划线）和 _（下划线），可登录管理后台，在「对象存储」 > 「详情」中设置。
删除或修改 Content-Secret，见 Metadata。
如果原文件是一张图片，除了通过文件密码进行访问外，还可以通过图片处理进行访问。

文件分块上传

请求信息

PUT /<bucket>/<save_as_file>

文件大小最大为13T,除最后一块外，其余每块大小固定为1M字节，分块上传不区分串行和并行，在初始化完成后，可并行上传块，待所有块上传完毕后，执行完成块上传请求。

初始化

参数

参数	必选	类型	说明
x-west-multi-disorder	`是`	string	值为true，表示进行分块上传
x-west-multi-stage	`是`	string	initiate:初始化
x-west-multi-length	`是`	string	待上传文件的大小，单位 Byte
x-west-multi-type	否	string	文件mime类型
x-west-overwrite	否	string	上传文件时覆盖已存在文件，默认为false
x-west-automkdir	否	string	上传文件时目录不存在自动创建，默认false
x-west-meta-x	否	string	文件元信息
x-west-meta-ttl	否	string	文件生存时间，单位天，最大支持180天

上传块

参数

参数	必选	类型	说明
x-west-multi-disorder	`是`	string	值为true，表示进行分块上传
x-west-multi-stage	`是`	string	upload:块上传
x-west-part-id	`是`	string	分块序号，序号从0开始，支持断点续传
Content-Length	否	string	请求内容长度
Content-MD5	否	string	上传文件的MD5值

完成上传

参数

参数	必选	类型	说明
x-west-multi-disorder	`是`	string	值为true，表示进行分块上传
x-west-multi-stage	`是`	string	complete:完成上传

响应信息

成功，返回 200 状态码
失败，返回出错信息，具体请参阅「API 错误码表」。

举例

初始化：


xxxxxxxxxx
8
1
curl -X PUT \ 
2
    http://fss-my.vhostgo.com/bucket-7/2.jpg \
3
    -H "x-west-meta-abc:test1" \
4
    -H "x-west-multi-disorder:true" \
5
    -H "x-west-multi-stage:initiate" \
6
    -H "x-west-multi-length:2097162" \
7
    -H "x-west-multi-type:image/jpg" \
8
    -H "Authorization: Basic XXX" \

上传块：


xxxxxxxxxx
21
1
curl -X PUT \
2
    http://fss-my.vhostgo.com/bucket-7/2.jpg \
3
    -H "x-west-multi-disorder:true" \
4
    -H "x-west-multi-stage:upload" \
5
    -H "x-west-part-id:0"  \
6
    -H "Authorization: Basic XXX" \
7
    -T 1M.txt \
8
curl -X PUT \
9
    http://fss-my.vhostgo.com/bucket-7/2.jpg  \
10
    -H "x-west-multi-disorder:true" \
11
    -H "x-west-multi-stage:upload" \
12
    -H "x-west-part-id:1"  \
13
    -H "Authorization: Basic XXX"  \
14
    -T 1M.txt \
15
curl -X PUT 
16
    http://fss-my.vhostgo.com/bucket-7/2.jpg  \
17
    -H "x-west-multi-disorder:true" \
18
    -H "x-west-multi-stage:upload" \
19
    -H "x-west-part-id:2"  \
20
    -H "Authorization: Basic XXX" \
21
    -d xxxxxxxx \

完成上传：


x
1
curl -X PUT \
2
    http://fss-my.vhostgo.com/bucket-7/2.jpg  \
3
    -H "x-west-multi-disorder:true" \
4
    -H "x-west-multi-stage:complete"   \
5
    -H "Authorization: Basic XXX" \
6

复制文件

同 bucket 下复制文件。它只能操作文件，不能操作文件夹。

请求信息

PUT /<bucket>/<save_as_file>

参数

参数	必选	类型	说明
x-west-copy-source	`是`	string	源文件地址，格式 /<bucket>/<source-to-file>
x-west-automkdir	否	string	复制文件时目录不存在自动创建，默认false
x-west-metadata-directive	否	string	对x-west-metadata-x操作的方式，取值为：copy(默认),merge,replace,delete，具体每种取值含义详见：Metadata的`option`说明
x-west-metadata-x	否	string	设置文件元信息

响应信息

成功，返回 200 状态码。
失败，返回出错信息，具体请参阅「API 错误码表」。

举例


xxxxxxxxxx
7
1
curl -X PUT \
2
    http://fss-my.vhostgo.com/test/source.jpg \
3
    -H "Authorization: WESTYUN <Operator>:<Signature>" \
4
    -H 'X-west-copy-Source: /test/foo/source.jpg' \
5
6
< HTTP/1.1 200 OK
7
< Content-Type: application/octet-stream

移动文件

同 bucket 下移动文件，可以进行文件重命名、文件移动。它只能操作文件，不能操作文件夹。

请求信息

PUT /<bucket>/<save_as_file>

参数

参数	必选	类型	说明
x-west-move-source	`是`	string	源文件地址，格式 `/<bucket>/<source-to-file>`
x-west-automkdir	否	string	移动文件时目录不存在自动创建，默认false
x-west-metadata-directive	否	string	对x-west-metadata-x操作的方式，取值为：copy(默认),merge,replace,delete，具体每种取值含义详见：Metadata的`option`说明
x-west-metadata-x	否	string	设置文件元信息

响应信息

成功，返回 200 状态码。
失败，返回出错信息，具体请参阅「API 错误码表」。

举例


xxxxxxxxxx
7
1
curl -X PUT \
2
    http://fss-my.vhostgo.com/test/source.jpg \
3
    -H "Authorization: WESTYUN <Operator>:<Signature>" \
4
    -H 'X-west-move-Source: /test/foo/source.jpg' \
5
6
< HTTP/1.1 200 OK
7
< Content-Type: application/octet-stream

下载文件

请求信息

GET /<bucket>/<path_to_file>

参数

参数	必选	类型	说明
Range	否	string	Range: bytes=0-499表示第0-499字节范围的内容。Range: bytes=-500表示最后500字节的内容。Range: bytes=500-表示从第500字节开始到文件结束部分的内容。Range: bytes=0-表示从第一个字节到最后一个字节，即完整的文件内容。

注

Range参数可以获取文件中的某一块数据，适用于断点续传

响应信息

下载成功：返回 200，HTTP body 中返回文件内容。
失败，返回出错信息，具体请参阅「API 错误码表」。

删除文件

请求信息

DELETE /<bucket>/<path_to_file>

参数

参数	必选	类型	说明
x-west-async	否	string	true 表示进行异步删除，不设置表示同步删除（默认）

响应信息

下载成功：返回 200。
失败，返回出错信息，具体请参阅「API 错误码表」。

注

同步删除有频率限制，批量删除请在请求头里加上 x-west-async: true 进行异步删除（无频率限制）。
异步删除请求成功，返回 200，但删除操作会延期执行。

创建目录

请求信息

POST /<bucket>/<path_to_folder>

参数

参数	必选	类型	说明
folder	`是`	string	值为字符串`true`

响应信息

创建成功：返回 200。
失败，返回出错信息，具体请参阅「API 错误码表」。

删除目录

请求信息

DELETE /<bucket>/<path_to_folder>

响应信息

删除成功：返回 200。
失败，返回出错信息，具体请参阅「API 错误码表」。

注

只允许删除空的目录，非空目录需要先删除里面的文件，否则删除请求会被拒绝。

获取文件信息

请求信息

HEAD /<bucket>/<path_to_file>

响应信息

获取成功：返回 200，返回头信息如下所示：

响应头	说明
x-west-file-type	文件类型
x-west-file-size	文件大小
x-west-file-date	文件创建时间
x-west-meta-x	返回设置的元信息，返回数量与设置情况一致

失败，返回出错信息，具体请参阅「API 错误码表」。

获取目录文件列表

请求信息

GET /<bucket>/<path_to_folder>

分页参数

如果目录中文件数量过多，为了更友好的获取文件信息，可以分页获取：

参数

参数	必选	类型	说明
x-list-iter	否	string	分页开始位置，通过`x-west-list-iter`响应头返回，所以第一次请求不需要填写
x-list-limit	否	string	获取的文件数量，默认 100，最大 10000
x-list-order	否	string	asc 或 desc，按文件名升序或降序排列。默认 asc

响应信息

获取成功：返回 200，列表格式为json，如下：


xxxxxxxxxx
8
1
{
2
  "files":[
3
      {"ctime":1587092931,"name":".bowerrc","size":43,"type":"application/x-www-form-urlencoded"},
4
      {"ctime":1587092931,"name":".gitignore","size":435,"type":"application/x-www-form-urlencoded"},
5
      {"ctime":1587092950,"name":".gitkeep","size":1,"type":"application/x-www-form-urlencoded"}
6
  ],
7
  "iter":"bmV4dCBpbmRleDpFT0Y="
8
}

失败，返回出错信息，具体请参阅「API 错误码表」。
iter 返回下一次分页开始位置。它由一串 Base64 编码的随机数组成，当它是 bmV4dCBpbmRleDpFT0Y= 时，表示最后一个分页。

修改 Metadata

请求信息

PATCH /<bucket>/<path_to_file>?metadata=<option>

option 的取值如下：

option	说明
merge（默认）	合并文件元信息，如果是相同的元信息，将被新上传的值替换
replace	替换文件元信息为新上传的文件元信息
delete	删除文件元信息

参数

参数	必选	类型	说明
x-west-meta-x	`否`	string	设置文件元信息
content-secret	`否`	string	设置文件元信息
content-type	`否`	string	设置文件元信息

响应信息

修改成功：返回 200。
失败，返回出错信息，具体请参阅「API 错误码表」。

举例

例 1：合并元信息，metadata=merge


xxxxxxxxxx
7
1
curl -d 'abc' http://fss.vhost.go.com/<bucket>/test.txt \
2
    -H "Authorization: Basic XXXX" \
3
    -H "x-west-meta-a: test"
4
curl -X PATCH http://fss.vhost.go.com/<bucket>/test.txt?metadata=merge \
5
    -H "Authorization: Basic XXXX" \
6
    -H "x-west-meta-a: test1" \
7
    -H "x-west-meta-b: test2"

文件 test.txt 的元信息是：


xxxxxxxxxx
2
1
x-west-meta-a: test1
2
x-west-meta-b: test2

例 2：替换元信息，metadata=replace


xxxxxxxxxx
8
1
curl -d 'abc' http://fss-my.vhostgo.com/<bucket>/test.txt \
2
    -H "Authorization: Basic XXXX" \
3
    -H "x-west-meta-a: test1" \
4
    -H "x-west-meta-b: test2"
5
curl -X PATCH http://fss-my.vhostgo.com/<bucket>/test.txt?metadata=replace \
6
    -H "Authorization: Basic XXXX" \
7
    -H "x-west-meta-a: test3" \
8
    -H "x-west-meta-c: test4"

文件 test.txt 的元信息为：


xxxxxxxxxx
2
1
x-west-meta-a: test3
2
x-west-meta-c: test4

例 3：删除元信息，metadata=delete


xxxxxxxxxx
7
1
curl -d 'abc' http://fss-my.vhostgo.com/<bucket>/test.txt \
2
    -H "Authorization: Basic XXXX" \
3
    -H "x-west-meta-a: test1" \
4
    -H "x-west-meta-b: test2"
5
curl -X PATCH http://fss-my.vhostgo.com/<bucket>/test.txt?metadata=delete \
6
    -H "Authorization: Basic XXXX" \
7
    -H "x-west-meta-a: true"

文件 test.txt 的元信息为：


1
1
x-west-meta-b: test2