REST API

基于 RESTful 架構(gòu)的 API，您可以使用任何編程語(yǔ)言發(fā)送 HTTP/HTTPS 請(qǐng)求。所有請(qǐng)求參數(shù)均通過(guò) HTTP/HTTPS 請(qǐng)求頭以 Key: Value 的形式傳遞。
AWS S3兼容，查看S3 API

請(qǐng)求方法


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)容，是需要用戶填寫(xiě)的，填寫(xiě)時(shí)，把 <> 去掉。

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

并發(fā)請(qǐng)求限制

單個(gè)桶更新請(qǐng)求并發(fā)數(shù)不超過(guò)100個(gè),GET/HEAD請(qǐng)求不限

Authorization

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

上傳文件

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

PUT /<bucket>/<path_to_file>

上傳參數(shù)

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

注

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

響應(yīng)信息

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


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

上傳失?。悍祷叵鄳?yīng)的出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

Content-Secret 參數(shù)說(shuō)明

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

文件分塊上傳

請(qǐng)求信息

PUT /<bucket>/<save_as_file>

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

初始化

參數(shù)

參數(shù)	必選	類(lèi)型	說(shuō)明
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類(lèi)型
x-west-overwrite	否	string	上傳文件時(shí)覆蓋已存在文件，默認(rèn)為false
x-west-automkdir	否	string	上傳文件時(shí)目錄不存在自動(dòng)創(chuàng)建，默認(rèn)false
x-west-meta-x	否	string	文件元信息
x-west-meta-ttl	否	string	文件生存時(shí)間，單位天，最大支持180天

上傳塊

參數(shù)

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

完成上傳

參數(shù)

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

響應(yīng)信息

成功，返回 200 狀態(tài)碼
失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

舉例

初始化：


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ù)制文件。它只能操作文件，不能操作文件夾。

請(qǐng)求信息

PUT /<bucket>/<save_as_file>

參數(shù)

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

響應(yīng)信息

成功，返回 200 狀態(tài)碼。
失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

舉例


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

移動(dòng)文件

同 bucket 下移動(dòng)文件，可以進(jìn)行文件重命名、文件移動(dòng)。它只能操作文件，不能操作文件夾。

請(qǐng)求信息

PUT /<bucket>/<save_as_file>

參數(shù)

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

響應(yīng)信息

成功，返回 200 狀態(tài)碼。
失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

舉例


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

下載文件

請(qǐng)求信息

GET /<bucket>/<path_to_file>

參數(shù)

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

注

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

響應(yīng)信息

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

刪除文件

請(qǐng)求信息

DELETE /<bucket>/<path_to_file>

參數(shù)

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

響應(yīng)信息

下載成功：返回 200。
失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

注

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

創(chuàng)建目錄

請(qǐng)求信息

POST /<bucket>/<path_to_folder>

參數(shù)

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

響應(yīng)信息

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

刪除目錄

請(qǐng)求信息

DELETE /<bucket>/<path_to_folder>

響應(yīng)信息

刪除成功：返回 200。
失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

注

只允許刪除空的目錄，非空目錄需要先刪除里面的文件，否則刪除請(qǐng)求會(huì)被拒絕。

獲取文件信息

請(qǐng)求信息

HEAD /<bucket>/<path_to_file>

響應(yīng)信息

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

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

失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

獲取目錄文件列表

請(qǐng)求信息

GET /<bucket>/<path_to_folder>

分頁(yè)參數(shù)

如果目錄中文件數(shù)量過(guò)多，為了更友好的獲取文件信息，可以分頁(yè)獲?。?/span>

參數(shù)

參數(shù)	必選	類(lèi)型	說(shuō)明
x-list-iter	否	string	分頁(yè)開(kāi)始位置，通過(guò)`x-west-list-iter`響應(yīng)頭返回，所以第一次請(qǐng)求不需要填寫(xiě)
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
}

失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。
iter 返回下一次分頁(yè)開(kāi)始位置。它由一串 Base64 編碼的隨機(jī)數(shù)組成，當(dāng)它是 bmV4dCBpbmRleDpFT0Y= 時(shí)，表示最后一個(gè)分頁(yè)。

修改 Metadata

請(qǐng)求信息

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

option 的取值如下：

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

參數(shù)

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

響應(yīng)信息

修改成功：返回 200。
失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

舉例

例 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

中文字幕在线观看,亚洲а∨天堂久久精品9966,亚洲成a人片在线观看你懂的,亚洲av成人片无码网站,亚洲国产精品无码久久久五月天

REST API

請(qǐng)求方法

上傳文件

文件分塊上傳

初始化

上傳塊

完成上傳

復(fù)制文件

移動(dòng)文件

下載文件

刪除文件

創(chuàng)建目錄

刪除目錄

獲取文件信息

獲取目錄文件列表

修改 Metadata