REST API

基于 RESTful 架構(gòu)的 API，您可以使用任何編程語言發(fā)送 HTTP/HTTPS 請求。所有請求參數(shù)均通過 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
    # 其他可選參數(shù)...

域名

fss-<區(qū)域>.vhostgo.com

bucket、path

<> 是參數(shù)內(nèi)容，是需要用戶填寫的，填寫時，把 <> 去掉。

bucket，是創(chuàng)建的桶名；path，文件/文件夾的路徑。

并發(fā)請求限制

單個桶更新請求并發(fā)數(shù)不超過100個,GET/HEAD請求不限

Authorization

關(guān)于認(rèn)證鑒權(quán)，詳見認(rèn)證鑒權(quán)。

上傳文件

在上傳圖片文件時，可以設(shè)置預(yù)處理參數(shù)，圖片會處理后再保存。

PUT /<bucket>/<path_to_file>

上傳參數(shù)

參數(shù)	必選	類型	說明
Content-Length	`是`	string	請求內(nèi)容長度
Content-MD5	否	string	上傳文件的 MD5 值，如果請求中文件太大計算 MD5 不方便，可以為空
Content-Type	否	string	文件類型，默認(rèn)使用文件擴(kuò)展名作為文件類型常見mine類型
Content-Secret	否	string	文件密鑰，用于保護(hù)文件，防止文件被直接訪問，見 Content-Secret 參數(shù)說明
x-west-meta-x	否	string	文件元信息，見 Metadata
x-west-meta-ttl	否	string	文件元信息, 指定文件的生存時間，單位天，最大支持180天，見 Metadata
x-west-overwrite	否	string	上傳文件時覆蓋已存在文件，默認(rèn)為false
x-west-automkdir	否	string	上傳文件時目錄不存在自動創(chuàng)建，默認(rèn)false
x-gmkerl-thumb	否	string	圖片預(yù)處理參數(shù)，見圖片處理
x-west-async	否	string	true表示異步處理

注

單線程文件上傳大小最大支持1G,超過1G的文件請使用文件分塊上傳,超過100M的文件也推薦使用文件分塊上傳
將大量文件同時存儲到同一個目錄下可能會影響性能,所以建議當(dāng)文件過多時,存儲于不同子目錄。

響應(yīng)信息

上傳成功：返回 200，當(dāng)上傳文件是圖片且設(shè)置 x-gmkerl-xxx 時，包含圖片基本信息（包括圖片寬、高、格式、幀數(shù)），例如：


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

上傳失敗：返回相應(yīng)的出錯信息，具體請參閱「API 錯誤碼表」。

Content-Secret 參數(shù)說明

文件設(shè)置 Content-Secret 后，文件將不能被直接訪問，若需訪問，需要在 URL 后加上「間隔標(biāo)識符」和「文件密鑰」。如：間隔符為 !，Content-Secret 為 test，圖片訪問方式為： http://fss-my.vhostgo.com/westtest/example/secret.jpg!test
間隔標(biāo)識符用于分隔文件 URL 和文件密鑰，有 3 種可選，分別是：!（感嘆號/默認(rèn)值）、-（中劃線）和 _（下劃線），可登錄管理后臺，在「對象存儲」 > 「詳情」中設(shè)置。
刪除或修改 Content-Secret，見 Metadata。
如果原文件是一張圖片，除了通過文件密碼進(jìn)行訪問外，還可以通過圖片處理進(jìn)行訪問。

文件分塊上傳

請求信息

PUT /<bucket>/<save_as_file>

文件大小最大為13T,除最后一塊外，其余每塊大小固定為1M字節(jié)，分塊上傳不區(qū)分串行和并行，在初始化完成后，可并行上傳塊，待所有塊上傳完畢后，執(zhí)行完成塊上傳請求。

初始化

參數(shù)

參數(shù)	必選	類型	說明
x-west-multi-disorder	`是`	string	值為true，表示進(jìn)行分塊上傳
x-west-multi-stage	`是`	string	initiate:初始化
x-west-multi-length	`是`	string	待上傳文件的大小，單位 Byte
x-west-multi-type	否	string	文件mime類型
x-west-overwrite	否	string	上傳文件時覆蓋已存在文件，默認(rèn)為false
x-west-automkdir	否	string	上傳文件時目錄不存在自動創(chuàng)建，默認(rèn)false
x-west-meta-x	否	string	文件元信息
x-west-meta-ttl	否	string	文件生存時間，單位天，最大支持180天

上傳塊

參數(shù)

參數(shù)	必選	類型	說明
x-west-multi-disorder	`是`	string	值為true，表示進(jìn)行分塊上傳
x-west-multi-stage	`是`	string	upload:塊上傳
x-west-part-id	`是`	string	分塊序號，序號從0開始，支持?jǐn)帱c(diǎn)續(xù)傳
Content-Length	否	string	請求內(nèi)容長度
Content-MD5	否	string	上傳文件的MD5值

完成上傳

參數(shù)

參數(shù)	必選	類型	說明
x-west-multi-disorder	`是`	string	值為true，表示進(jìn)行分塊上傳
x-west-multi-stage	`是`	string	complete:完成上傳

響應(yīng)信息

成功，返回 200 狀態(tài)碼
失敗，返回出錯信息，具體請參閱「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
?

復(fù)制文件

同 bucket 下復(fù)制文件。它只能操作文件，不能操作文件夾。

請求信息

PUT /<bucket>/<save_as_file>

參數(shù)

參數(shù)	必選	類型	說明
x-west-copy-source	`是`	string	源文件地址，格式 /<bucket>/<source-to-file>
x-west-automkdir	否	string	復(fù)制文件時目錄不存在自動創(chuàng)建，默認(rèn)false
x-west-metadata-directive	否	string	對x-west-metadata-x操作的方式，取值為：copy(默認(rèn)),merge,replace,delete，具體每種取值含義詳見：Metadata的`option`說明
x-west-metadata-x	否	string	設(shè)置文件元信息

響應(yīng)信息

成功，返回 200 狀態(tài)碼。
失敗，返回出錯信息，具體請參閱「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 下移動文件，可以進(jìn)行文件重命名、文件移動。它只能操作文件，不能操作文件夾。

請求信息

PUT /<bucket>/<save_as_file>

參數(shù)

參數(shù)	必選	類型	說明
x-west-move-source	`是`	string	源文件地址，格式 `/<bucket>/<source-to-file>`
x-west-automkdir	否	string	移動文件時目錄不存在自動創(chuàng)建，默認(rèn)false
x-west-metadata-directive	否	string	對x-west-metadata-x操作的方式，取值為：copy(默認(rèn)),merge,replace,delete，具體每種取值含義詳見：Metadata的`option`說明
x-west-metadata-x	否	string	設(shè)置文件元信息

響應(yīng)信息

成功，返回 200 狀態(tài)碼。
失敗，返回出錯信息，具體請參閱「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>

參數(shù)

參數(shù)	必選	類型	說明
Range	否	string	Range: bytes=0-499表示第0-499字節(jié)范圍的內(nèi)容。Range: bytes=-500表示最后500字節(jié)的內(nèi)容。Range: bytes=500-表示從第500字節(jié)開始到文件結(jié)束部分的內(nèi)容。Range: bytes=0-表示從第一個字節(jié)到最后一個字節(jié)，即完整的文件內(nèi)容。

注

Range參數(shù)可以獲取文件中的某一塊數(shù)據(jù)，適用于斷點(diǎn)續(xù)傳

響應(yīng)信息

下載成功：返回 200，HTTP body 中返回文件內(nèi)容。
失敗，返回出錯信息，具體請參閱「API 錯誤碼表」。

刪除文件

請求信息

DELETE /<bucket>/<path_to_file>

參數(shù)

參數(shù)	必選	類型	說明
x-west-async	否	string	true 表示進(jìn)行異步刪除，不設(shè)置表示同步刪除（默認(rèn)）

響應(yīng)信息

下載成功：返回 200。
失敗，返回出錯信息，具體請參閱「API 錯誤碼表」。

注

同步刪除有頻率限制，批量刪除請在請求頭里加上 x-west-async: true 進(jìn)行異步刪除（無頻率限制）。
異步刪除請求成功，返回 200，但刪除操作會延期執(zhí)行。

創(chuàng)建目錄

請求信息

POST /<bucket>/<path_to_folder>

參數(shù)

參數(shù)	必選	類型	說明
folder	`是`	string	值為字符串`true`

響應(yīng)信息

創(chuàng)建成功：返回 200。
失敗，返回出錯信息，具體請參閱「API 錯誤碼表」。

刪除目錄

請求信息

DELETE /<bucket>/<path_to_folder>

響應(yīng)信息

刪除成功：返回 200。
失敗，返回出錯信息，具體請參閱「API 錯誤碼表」。

注

只允許刪除空的目錄，非空目錄需要先刪除里面的文件，否則刪除請求會被拒絕。

獲取文件信息

請求信息

HEAD /<bucket>/<path_to_file>

響應(yīng)信息

獲取成功：返回 200，返回頭信息如下所示：

響應(yīng)頭	說明
x-west-file-type	文件類型
x-west-file-size	文件大小
x-west-file-date	文件創(chuàng)建時間
x-west-meta-x	返回設(shè)置的元信息，返回數(shù)量與設(shè)置情況一致

失敗，返回出錯信息，具體請參閱「API 錯誤碼表」。

獲取目錄文件列表

請求信息

GET /<bucket>/<path_to_folder>

分頁參數(shù)

如果目錄中文件數(shù)量過多，為了更友好的獲取文件信息，可以分頁獲取：

參數(shù)

參數(shù)	必選	類型	說明
x-list-iter	否	string	分頁開始位置，通過`x-west-list-iter`響應(yīng)頭返回，所以第一次請求不需要填寫
x-list-limit	否	string	獲取的文件數(shù)量，默認(rèn) 100，最大 10000
x-list-order	否	string	asc 或 desc，按文件名升序或降序排列。默認(rèn) asc

響應(yīng)信息

獲取成功：返回 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 編碼的隨機(jī)數(shù)組成，當(dāng)它是 bmV4dCBpbmRleDpFT0Y= 時，表示最后一個分頁。

修改 Metadata

請求信息

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

option 的取值如下：

option	說明
merge（默認(rèn)）	合并文件元信息，如果是相同的元信息，將被新上傳的值替換
replace	替換文件元信息為新上傳的文件元信息
delete	刪除文件元信息

參數(shù)

參數(shù)	必選	類型	說明
x-west-meta-x	`否`	string	設(shè)置文件元信息
content-secret	`否`	string	設(shè)置文件元信息
content-type	`否`	string	設(shè)置文件元信息

響應(yīng)信息

修改成功：返回 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

亚洲色图欧美日韩在线播放-户外操美女逼逼中国-免费久久99国产精品自在现-欧美激情五月综合啪啪-九九日本黄色精品视频-亚洲成年网址青青草原-欧美性爱精品在线免费观看-国产精品一区二区美女-日电影一区二区三区

REST API

請求方法

上傳文件

文件分塊上傳

初始化

上傳塊

完成上傳

復(fù)制文件

移動文件

下載文件

刪除文件

創(chuàng)建目錄

刪除目錄

獲取文件信息

獲取目錄文件列表

修改 Metadata