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)于認證鑒權(quá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	文件類型，默認使用文件擴展名作為文件類型常見mine類型
Content-Secret	否	string	文件密鑰，用于保護文件，防止文件被直接訪問，見 Content-Secret 參數(shù)說明
x-west-meta-x	否	string	文件元信息，見 Metadata
x-west-meta-ttl	否	string	文件元信息, 指定文件的生存時間，單位天，最大支持180天，見 Metadata
x-west-overwrite	否	string	上傳文件時覆蓋已存在文件，默認為false
x-west-automkdir	否	string	上傳文件時目錄不存在自動創(chuàng)建，默認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 種可選，分別是：!（感嘆號/默認值）、-（中劃線）和 _（下劃線），可登錄管理后臺，在 「對象存儲」 > 「詳情」 中設(shè)置。
• 刪除或修改 Content-Secret，見 Metadata。
• 如果原文件是一張圖片，除了通過文件密碼進行訪問外，還可以通過圖片處理進行訪問。

文件分塊上傳

請求信息

PUT /<bucket>/<save_as_file>

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

初始化

參數(shù)

參數(shù)	必選	類型	說明
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	上傳文件時目錄不存在自動創(chuàng)建，默認false
x-west-meta-x	否	string	文件元信息
x-west-meta-ttl	否	string	文件生存時間，單位天，最大支持180天

上傳塊

參數(shù)

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

完成上傳

參數(shù)

參數(shù)	必選	類型	說明
x-west-multi-disorder	是	string	值為true，表示進行分塊上傳
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)建，默認false
x-west-metadata-directive	否	string	對x-west-metadata-x操作的方式，取值為：copy(默認),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 下移動文件，可以進行文件重命名、文件移動。它只能操作文件，不能操作文件夾。

請求信息

PUT /<bucket>/<save_as_file>

參數(shù)

參數(shù)	必選	類型	說明
x-west-move-source	是	string	源文件地址，格式 /<bucket>/<source-to-file>
x-west-automkdir	否	string	移動文件時目錄不存在自動創(chuàng)建，默認false
x-west-metadata-directive	否	string	對x-west-metadata-x操作的方式，取值為：copy(默認),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ù)，適用于斷點續(xù)傳

響應(yīng)信息

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

刪除文件

請求信息

DELETE /<bucket>/<path_to_file>

參數(shù)

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

響應(yīng)信息

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

注

• 同步刪除有頻率限制，批量刪除請在請求頭里加上 x-west-async: true 進行異步刪除（無頻率限制）。
• 異步刪除請求成功，返回 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ù)量，默認 100，最大 10000
x-list-order	否	string	asc 或 desc，按文件名升序或降序排列。默認 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 編碼的隨機數(shù)組成，當(dāng)它是 bmV4dCBpbmRleDpFT0Y= 時，表示最后一個分頁。

修改 Metadata

請求信息

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

option 的取值如下：

option	說明
merge（默認）	合并文件元信息，如果是相同的元信息，將被新上傳的值替換
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