S3 API

基于 AWS 架構(gòu)的 API，您可以使用任何編程語(yǔ)言發(fā)送 HTTP/HTTPS 請(qǐng)求。所有請(qǐng)求參數(shù)均通過 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)容，是需要用戶填寫的，填寫時(shí)，把 <> 去掉。

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

注

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

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

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

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

參數(shù)	說明
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ù)	必選	類型	說明
Content-Length	`是`	string	請(qǐng)求內(nèi)容長(zhǎng)度
Content-MD5	否	string	上傳文件的 MD5 值，如果請(qǐng)求中文件太大計(jì)算 MD5 不方便，可以為空
Content-Type	否	string	文件類型，默認(rèn)使用文件擴(kuò)展名作為文件類型
x-amz-meta-x	否	string	文件元數(shù)據(jù)，見 Metadata

注

該請(qǐng)求接受跟隨二進(jìn)制數(shù)據(jù)
單線程文件上傳大小最大支持1G,超過1G的文件請(qǐng)使用文件分塊上傳,超過100M的文件也推薦使用文件分塊上傳
將大量文件同時(shí)存儲(chǔ)到同一個(gè)目錄下可能會(huì)影響性能,所以建議當(dāng)文件過多時(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ù)	必選	類型	說明
x-west-multi-length	`是`	string	上傳文件的大小
Content-MD5	否	string	上傳文件的 MD5 值，如果請(qǐng)求中文件太大計(jì)算 MD5 不方便，可以為空。使用時(shí)請(qǐng)勿在使用請(qǐng)求體上傳文件
Content-Type	否	string	文件類型，默認(rèn)使用文件擴(kuò)展名作為文件類型
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ù)	類型	說明
InitiateMultipartUploadResult	Container	上傳文件的大小
Bucket	string	空間名稱
Key	string	資源名稱
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ù)	必選	類型	說明
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ù)	必選	類型	說明
ObjectName	`是`	string	資源名稱
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 狀態(tài)碼
失敗，返回出錯(cuò)信息，具體請(qǐng)參閱「API 錯(cuò)誤碼表」。

舉例


xxxxxxxxxx
35
1
POST /bucket-7/west.txt?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
Authorization: authorization string 
6
?
7
?
8
<CompleteMultipartUpload>
9
  <Part>
10
    <PartNumber>1</PartNumber>
11
    <ETag>"a54357aff0632cce46d942af68356b38"</ETag>
12
  </Part>
13
  <Part>
14
    <PartNumber>2</PartNumber>
15
    <ETag>"0c78aef83f66abc1fale8477f296d394"</ETag>
16
  </Part>
17
  <Part>
18
    <PartNumber>3</PartNumber>
19
    <ETag>"acbd18db4cc2f85cedef654fccc4a4d8"</ETag>
20
  </Part>
21
</CompleteMultipartUpload>
22
?
23
?
24
HTTP/1.1 200 OK 
25
x-amz-request-id: 3141cdab-1387-4872-b6e7-e83ec0f9fc97 
26
Date: Wed, 12 Oct 2023 17:50:00 GMT 
27
Connection: close 
28
?
29
<?xml version="1.” encoding="UTF-8"?>
30
<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
31
  <Location>http://fss-my.vhostgo.com/bucket-7/west.txt</Location>
32
  <Bucket>bucket-7</Bucket>
33
  <Key>west.txt</Key>
34
  <ETag>"3858f62230ac3c915f300c664312c11f-9"</ETag>
35
</CompleteMultipartUploadResult>

復(fù)制文件

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

請(qǐng)求信息

PUT /<bucket>/<save_as_file>

參數(shù)

參數(shù)	必選	類型	說明
x-amz-copy-source	`是`	string	源文件地址，格式 /<bucket>/<source-to-file>

響應(yīng)信息

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

舉例


xxxxxxxxxx
15
1
PUT /bucket-7/west.txt HTTP/1.1
2
Host: fss-my.vhostgo.com
3
Date: Wed, 12 Oct 2023 17:50:00 GMT
4
x-amz-copy-source: /bucket-7/test/west.copy
5
Authorization: authorization string
6
?
7
HTTP/1.1 200 OK
8
x-amz-request-id: 3141cdab-1337-4872-b6e7-e83ec0f9fc97
9
Date: Wed, 28 Oct 2009 22:32:00 GMT
10
Connection: close
11
?
12
<CopyObjectResult>
13
   <LastModified>2023-10-12T17:50:30.000Z</LastModified>
14
   <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
15
</CopyObjectResult>

下載文件

用于獲取一個(gè)資源的元數(shù)據(jù)及對(duì)象數(shù)據(jù)，可以獲取全部數(shù)據(jù)或者使用 Range 指定獲取部分?jǐn)?shù)據(jù)

請(qǐng)求信息

GET /<bucket>/<path_to_file>

參數(shù)

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

注

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

響應(yīng)信息

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

刪除文件

請(qǐng)求信息

DELETE /<bucket>/<path_to_file>

響應(yīng)信息

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

獲取文件信息

請(qǐng)求信息

HEAD /<bucket>/<path_to_file>

響應(yīng)信息

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

響應(yīng)頭	說明
Last-Modified	最后修改時(shí)間
ETag	資源內(nèi)容的哈希值，用于表示對(duì)象內(nèi)容的變化，而不是元數(shù)據(jù)的變化。ETag 的值并不總是對(duì)象數(shù)據(jù)的 MD5 值，具體取決于請(qǐng)求的方式
x-amz-meta-x	文件元數(shù)據(jù)

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

獲取目錄文件列表

請(qǐng)求信息

GET /<bucket>/<path_to_folder>/?list-type=2

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

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

參數(shù)

參數(shù)	必選	類型	說明
list-type	是	string	API 的第二版本要求使用該參數(shù)，并且值必須設(shè)置為 2
max-keys	否	string	返回資源的最大數(shù)量。默認(rèn)值為 1000
prefix	否	string	指定前綴，只有資源名匹配該前綴的資源會(huì)被列出。默認(rèn)值為空字符串
delimiter	否	string	指定目錄分隔符，列出所有公共前綴（模擬列出目錄效果）。默認(rèn)值為空字符串

該請(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，列表格式為json，如下：

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

參數(shù)	類型	說明
Delimiter	string	指定目錄分隔符
IsTruncated	Boolean	返表示是否還有更多可返回的資源。當(dāng)所有結(jié)果都已返回時(shí)，該參數(shù)設(shè)為false；當(dāng)還有更多資源可返回時(shí)，該參數(shù)設(shè)為true。如果結(jié)果數(shù)量超過了MaxKeys指定的數(shù)量，可能不會(huì)返回所有結(jié)果
MaxKeys	string	返回的資源的最大數(shù)量
Prefix	string	以特定前綴開頭的資源
ContinuationToken	string	如果請(qǐng)求中帶有 Continuation-token，它將包含在響應(yīng)中
NextContinuationToken	string	返如果響應(yīng)被截?cái)?，S3 將返回此參數(shù)及其對(duì)應(yīng)的續(xù)傳令牌。您可以將該令牌作為 continuation-token 在下一個(gè)請(qǐng)求中指定，檢索下一組資源
CommonPrefixes	string	將合并為公共前綴的資源計(jì)為單個(gè)返回，并列出充當(dāng)子目錄的資源
ETag	string	對(duì)象的 MD5 哈希值。ETag 僅反映對(duì)象內(nèi)容的更改，而不包括其元數(shù)據(jù)的更改
Key	string	資源名稱
LastModified	DATE	對(duì)象的最后修改日期和時(shí)間
Size	string	對(duì)象的大小，以字節(jié)為單位

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

舉例


26
1
GET /?list-type=2 HTTP/1.1 
2
Host: bucket-7.fss-my.vhostgo.com
3
X-Amz-Date: 20230628T063714Z
4
Authorization: authorization string
5
Content-Type: text/plain 
6
?
7
HTTP/1.1 200 OK 
8
<?xml version="1.0" encoding="UTF-8"?>
9
<ListBucketResult xmlns="http://fss-my.vhostgo.com/doc/2006-03-01/">
10
   <Name>bucket</Name>
11
   <Prefix/>
12
   <KeyCount>205</KeyCount>
13
   <MaxKeys>1000</MaxKeys>
14
   <IsTruncated>false</IsTruncated>
15
   <Contents>
16
      <Key>my-image.jpg</Key>
17
      <LastModified>2022-10-12T17:50:30.0Z</LastModified>
18
      <ETag>"fba9dede5f27731c9771645a39863328"</ETag>
19
      <Size>434234</Size>
20
      <StorageClass>STANDARD</StorageClass>
21
   </Contents>
22
   <Contents>
23
      ...
24
   </Contents>
25
   ...
26
</ListBucketResult>