S3 API

基于 AWS 架構(gòu)的 API，您可以使用任何編程語(yǔ)言發(fā)送 HTTP/HTTPS 請(qǐng)求。所有請(qǐng)求參數(shù)均通過(guò) HTTP/HTTPS 請(qǐng)求頭以 Key: Value 的形式傳遞。 特別的，F(xiàn)SS僅支持文件相關(guān)的API，不支持區(qū)域相關(guān)配置。 access key id是桶名，secret access key是桶密碼。

請(qǐng)求方法

• 路徑風(fēng)格：fss-my.vhostgo.com/<bucket>/<path>
• 支持虛擬主機(jī)風(fēng)格：<bucket>.fss-my.vhostgo.com/<path>
• 鑒權(quán)方法：同時(shí)兼容AWS Signature Version 2和AWS Signature Version 4。

bucket、path

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

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

注

文件上傳和客戶(hù)端管理使用路徑風(fēng)格，網(wǎng)頁(yè)訪問(wèn)get/head使用虛擬機(jī)風(fēng)格。

兼容公共請(qǐng)求頭

參數(shù)	說(shuō)明
Authorization	兼容
Content-Length	兼容
Content-MD5	兼容
Content-Type	兼容
Date	兼容
Host	兼容
x-amz-content-sha256	兼容
x-amz-date	兼容
x-amz-security-token	不兼容

兼容公共響應(yīng)頭

參數(shù)	說(shuō)明
Content-Length	兼容
Content-Type	兼容
ETag	兼容
Date	兼容
x-amz-delete-marker	不支持
x-amz-request-id	兼容
x-amz-id-2	不支持
x-amz-version-id	不支持

上傳文件

PUT /<bucket>/<path_to_file>

上傳參數(shù)

除了所有操作通用的請(qǐng)求頭之外，操作的此實(shí)現(xiàn)還可以使用以下請(qǐng)求頭

參數(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)型
x-amz-meta-x	否	string	文件元數(shù)據(jù)，見(jiàn) Metadata

注

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

響應(yīng)信息

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

舉例

xxxxxxxxxx
6
1
PUT /bucket-7/1.txt HTTP/1.1
2
Host: fss-my.vhostgo.com
3
Date: Mon, 11 Jul 2023 03:20:29 GMT
4
Authorization: authorization string 
5
Content-Type: text/plain 
6
Content-Length: 1314

文件分塊上傳

分片限制

限制項(xiàng)	規(guī)格
單個(gè)Part大小	1M,除去最后一個(gè)分片外，其它均為1M大小的塊

初始化

初始化分塊上傳任務(wù)，并得到全局唯一任務(wù) UploadId，后續(xù)分塊任務(wù)相關(guān)接口都需要 UploadId 作為請(qǐng)求參數(shù)。

請(qǐng)求信息

xxxxxxxxxx
5
1
POST /bucket-7/1.txt?uploads HTTP/1.1 
2
Host: fss-my.vhostgo.com
3
Date: date 
4
Authorization: authorization string
5
x-west-multi-length:1134000

參數(shù)

參數(shù)	必選	類(lèi)型	說(shuō)明
x-west-multi-length	是	string	上傳文件的大小
Content-MD5	否	string	上傳文件的 MD5 值，如果請(qǐng)求中文件太大計(jì)算 MD5 不方便，可以為空。使用時(shí)請(qǐng)勿在使用請(qǐng)求體上傳文件
Content-Type	否	string	文件類(lèi)型，默認(rèn)使用文件擴(kuò)展名作為文件類(lèi)型
x-amz-meta-x	否	string	文件元數(shù)據(jù)

響應(yīng)信息

該請(qǐng)求操作的實(shí)現(xiàn)僅使用了所有操作的公共響應(yīng)頭。有關(guān)詳細(xì)信息，請(qǐng)查閱公共響應(yīng)頭

響應(yīng)內(nèi)容

參數(shù)	類(lèi)型	說(shuō)明
InitiateMultipartUploadResult	Container	上傳文件的大小
Bucket	string	空間名稱(chēng)
Key	string	資源名稱(chēng)
UploadId	string	初始化任務(wù)生成的ID。 上傳分片 UploadPart API調(diào)用時(shí)用作請(qǐng)求參數(shù)

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

舉例

xxxxxxxxxx
14
1
POST /bucket-7/west.txt?uploads HTTP/1.1 
2
Host: fss-my.vhostgo.com
3
X-Amz-Date: 20240301T022904Z
4
Content-Type: text/plain
5
Authorization: authorization string 
6
?
7
?
8
HTTP/1.1 200 OK 
9
<?xml version="1.0" encoding="UTF-8"?>
10
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
11
    <Bucket>bucket-7</Bucket>
12
    <Key>west.txt</Key>
13
    <UploadId>e3868700-018b-41a3-8a9a-e093b7a22fc4</UploadId>
14
</InitiateMultipartUploadResult>

上傳塊

分塊上傳數(shù)據(jù)，需指定的任務(wù) UploadId

請(qǐng)求信息

xxxxxxxxxx
5
1
PUT /bucket-7/west.txt?partNumber=PartNumber&uploadId=UploadId HTTP/1.1 
2
Host: fss-my.vhostgo.com
3
Date: date 
4
Content-Length: Size
5
Authorization: authorization string

參數(shù)

參數(shù)	必選	類(lèi)型	說(shuō)明
ObjectName	是	string	初始化分片任務(wù)的對(duì)象
PartNumber	是	string	上傳的分塊編號(hào)。介于1和10,000之間的正整數(shù)
UploadId	是	string	上傳任務(wù)ID?？蓮?/span>初始化任務(wù)接口響應(yīng)信息中獲取

• 該請(qǐng)求操作的實(shí)現(xiàn)僅使用了所有操作的公共請(qǐng)求頭。有關(guān)詳細(xì)信息，請(qǐng)查閱公共請(qǐng)求頭

響應(yīng)信息

• 該請(qǐng)求操作的實(shí)現(xiàn)僅使用了所有操作的公共響應(yīng)頭。有關(guān)詳細(xì)信息，請(qǐng)查閱公共響應(yīng)頭
• 上傳成功：返回 200
• 上傳失?。悍祷叵鄳?yīng)的出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

舉例

xxxxxxxxxx
15
1
PUT /bucket-7/west.txt?partNumber=1&uploadId=ZpbmcncyBteS1tb HTTP/1.1 
2
Host: fss-my.vhostgo.com
3
Date: Wed, 12 Oct 2023 17:50:00 GMT 
4
Content-Length: 10485760 
5
Content-MD5: pUNXr/BjKK5G2UKvaRRrOA== 
6
Authorization: authorization string 
7
?
8
data content
9
?
10
HTTP/1.1 200 OK 
11
x-amz-request-id: 3141cdab-1387-4872-b6e7-e83ec0f9fc97 
12
Date: Wed, 12 Oct 2023 17:51:00 GMT 
13
ETag: "b54357faf0632cce46e942fa68356b38" 
14
Content-Length: 0
15
Connection: keep-alive 

完成上傳

請(qǐng)求信息

xxxxxxxxxx
13
1
POST /bucket-7/west.txt?uploadId=UploadId HTTP/1.1
2
Host: fss-my.vhostgo.com
3
Date: date 
4
Content-Length: Size 
5
Authorization: authorization string
6
?
7
<CompleteMultipartUpload>
8
 <Part>
9
   <PartNumber>PartNumber</PartNumber>
10
   <ETag>ETag</ETag>
11
 </Part>
12
 ...
13
</CompleteMultipartUpload>

參數(shù)

參數(shù)	必選	類(lèi)型	說(shuō)明
ObjectName	是	string	資源名稱(chēng)
UploadId	是	string	上傳任務(wù)ID。可從初始化任務(wù)接口響應(yīng)信息中獲取

• 該請(qǐng)求操作的實(shí)現(xiàn)僅使用了所有操作的公共請(qǐng)求頭。有關(guān)詳細(xì)信息，請(qǐng)查閱公共請(qǐng)求頭