S3 API

基于 AWS 架構的 API，您可以使用任何編程語言發送 HTTP/HTTPS 請求。所有請求參數均通過 HTTP/HTTPS 請求頭以 Key: Value 的形式傳遞。特別的，FSS僅支持文件相關的API，不支持區域相關配置。 access key id是桶名，secret access key是桶密碼。

請求方法

路徑風格：fss-my.vhostgo.com/<bucket>/<path>
支持虛擬主機風格：<bucket>.fss-my.vhostgo.com/<path>
鑒權方法：同時兼容AWS Signature Version 2和AWS Signature Version 4。

bucket、path

<> 是參數內容，是需要用戶填寫的，填寫時，把 <> 去掉。

bucket，是創建的桶名；path，文件/文件夾的路徑。

注

文件上傳和客戶端管理使用路徑風格，網頁訪問get/head使用虛擬機風格。

兼容公共請求頭

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

兼容公共響應頭

參數	說明
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>

上傳參數

除了所有操作通用的請求頭之外，操作的此實現還可以使用以下請求頭

參數	必選	類型	說明
Content-Length	`是`	string	請求內容長度
Content-MD5	否	string	上傳文件的 MD5 值，如果請求中文件太大計算 MD5 不方便，可以為空
Content-Type	否	string	文件類型，默認使用文件擴展名作為文件類型
x-amz-meta-x	否	string	文件元數據，見 Metadata

注

該請求接受跟隨二進制數據
單線程文件上傳大小最大支持1G,超過1G的文件請使用文件分塊上傳,超過100M的文件也推薦使用文件分塊上傳
將大量文件同時存儲到同一個目錄下可能會影響性能,所以建議當文件過多時,存儲于不同子目錄。

響應信息

上傳成功：返回 200
上傳失敗：返回相應的出錯信息，具體請參閱「API 錯誤碼表」。

舉例


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

文件分塊上傳

分片限制

限制項	規格
單個Part大小	1M,除去最后一個分片外，其它均為1M大小的塊

初始化

初始化分塊上傳任務，并得到全局唯一任務 UploadId，后續分塊任務相關接口都需要 UploadId 作為請求參數。

請求信息


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

參數

參數	必選	類型	說明
x-west-multi-length	`是`	string	上傳文件的大小
Content-MD5	否	string	上傳文件的 MD5 值，如果請求中文件太大計算 MD5 不方便，可以為空。使用時請勿在使用請求體上傳文件
Content-Type	否	string	文件類型，默認使用文件擴展名作為文件類型
x-amz-meta-x	否	string	文件元數據

響應信息

該請求操作的實現僅使用了所有操作的公共響應頭。有關詳細信息，請查閱公共響應頭

響應內容

參數	類型	說明
InitiateMultipartUploadResult	Container	上傳文件的大小
Bucket	string	空間名稱
Key	string	資源名稱
UploadId	string	初始化任務生成的ID。上傳分片 UploadPart API調用時用作請求參數

上傳成功：返回 200
上傳失?。悍祷叵鄳某鲥e信息，具體請參閱「API 錯誤碼表」。

舉例


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>

上傳塊

分塊上傳數據，需指定的任務 UploadId

請求信息


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

參數

參數	必選	類型	說明
ObjectName	`是`	string	初始化分片任務的對象
PartNumber	`是`	string	上傳的分塊編號。介于1和10,000之間的正整數
UploadId	`是`	string	上傳任務ID?？蓮?/span>初始化任務接口響應信息中獲取

該請求操作的實現僅使用了所有操作的公共請求頭。有關詳細信息，請查閱公共請求頭

響應信息

該請求操作的實現僅使用了所有操作的公共響應頭。有關詳細信息，請查閱公共響應頭
上傳成功：返回 200
上傳失?。悍祷叵鄳某鲥e信息，具體請參閱「API 錯誤碼表」。

舉例


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

完成上傳

請求信息


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>

參數

參數	必選	類型	說明
ObjectName	`是`	string	資源名稱
UploadId	`是`	string	上傳任務ID。可從初始化任務接口響應信息中獲取

該請求操作的實現僅使用了所有操作的公共請求頭。有關詳細信息，請查閱公共請求頭

響應信息

該請求操作的實現僅使用了所有操作的公共響應頭。有關詳細信息，請查閱公共響應頭
成功，返回 200 狀態碼
失敗，返回出錯信息，具體請參閱「API 錯誤碼表」。

舉例


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>

復制文件

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

請求信息

PUT /<bucket>/<save_as_file>

參數

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

響應信息

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

舉例


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>

下載文件

用于獲取一個資源的元數據及對象數據，可以獲取全部數據或者使用 Range 指定獲取部分數據

請求信息

GET /<bucket>/<path_to_file>

參數

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

注

Range參數可以獲取文件中的某一塊數據，適用于斷點下載

響應信息

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

刪除文件

請求信息

DELETE /<bucket>/<path_to_file>

響應信息

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

獲取文件信息

請求信息

HEAD /<bucket>/<path_to_file>

響應信息

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

響應頭	說明
Last-Modified	最后修改時間
ETag	資源內容的哈希值，用于表示對象內容的變化，而不是元數據的變化。ETag 的值并不總是對象數據的 MD5 值，具體取決于請求的方式
x-amz-meta-x	文件元數據

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

獲取目錄文件列表

請求信息

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

分頁參數

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

參數

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

該請求操作的實現僅使用了所有操作的公共請求頭。有關詳細信息，請查閱公共請求頭

響應信息

該請求操作的實現僅使用了所有操作的公共響應頭。有關詳細信息，請查閱公共響應頭

獲取成功：返回 200，列表格式為json，如下：

響應內容

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

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

舉例


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>