基于 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是桶密碼。
<bucket>/<path><bucket>.fss-my.vhostgo.com/<path>bucket、path
<> 是參數(shù)內(nèi)容，是需要用戶(hù)填寫(xiě)的，填寫(xiě)時(shí)，把 <> 去掉。
bucket，是創(chuàng)建的桶名；path，文件/文件夾的路徑。
注
文件上傳和客戶(hù)端管理使用路徑風(fēng)格，網(wǎng)頁(yè)訪(fǎng)問(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 |
注
響應(yīng)信息
200舉例
xxxxxxxxxx61PUT /bucket-7/1.txt HTTP/1.12Host: fss-my.vhostgo.com3Date: Mon, 11 Jul 2023 03:20:29 GMT4Authorization: authorization string 5Content-Type: text/plain 6Content-Length: 1314分片限制
| 限制項(xiàng) | 規(guī)格 |
|---|---|
| 單個(gè)Part大小 | 1M,除去最后一個(gè)分片外，其它均為1M大小的塊 |
初始化分塊上傳任務(wù)，并得到全局唯一任務(wù) UploadId，后續(xù)分塊任務(wù)相關(guān)接口都需要 UploadId 作為請(qǐng)求參數(shù)。
請(qǐng)求信息
xxxxxxxxxx51POST /bucket-7/1.txt?uploads HTTP/1.1 2Host: fss-my.vhostgo.com3Date: date 4Authorization: authorization string5x-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舉例
xxxxxxxxxx141POST /bucket-7/west.txt?uploads HTTP/1.1 2Host: fss-my.vhostgo.com3X-Amz-Date: 20240301T022904Z4Content-Type: text/plain5Authorization: authorization string 6?7?8HTTP/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)求信息
xxxxxxxxxx51PUT /bucket-7/west.txt?partNumber=PartNumber&uploadId=UploadId HTTP/1.1 2Host: fss-my.vhostgo.com3Date: date 4Content-Length: Size5Authorization: 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)信息中獲取 |
響應(yīng)信息
200舉例
xxxxxxxxxx151PUT /bucket-7/west.txt?partNumber=1&uploadId=ZpbmcncyBteS1tb HTTP/1.1 2Host: fss-my.vhostgo.com3Date: Wed, 12 Oct 2023 17:50:00 GMT 4Content-Length: 10485760 5Content-MD5: pUNXr/BjKK5G2UKvaRRrOA== 6Authorization: authorization string 7?8data content9?10HTTP/1.1 200 OK 11x-amz-request-id: 3141cdab-1387-4872-b6e7-e83ec0f9fc97 12Date: Wed, 12 Oct 2023 17:51:00 GMT 13ETag: "b54357faf0632cce46e942fa68356b38" 14Content-Length: 015Connection: keep-alive 請(qǐng)求信息
xxxxxxxxxx131POST /bucket-7/west.txt?uploadId=UploadId HTTP/1.12Host: fss-my.vhostgo.com3Date: date 4Content-Length: Size 5Authorization: authorization string6?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?？蓮?/span>初始化任務(wù)接口響應(yīng)信息中獲取 |
響應(yīng)信息
200 狀態(tài)碼舉例
xxxxxxxxxx351POST /bucket-7/west.txt?uploadId=ZpbmcncyBteS1tb HTTP/1.1 2Host: fss-my.vhostgo.com3Date: Wed, 12 Oct 2023 17:50:00 GMT 4Content-Length: 10485760 5Authorization: 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?24HTTP/1.1 200 OK 25x-amz-request-id: 3141cdab-1387-4872-b6e7-e83ec0f9fc97 26Date: Wed, 12 Oct 2023 17:50:00 GMT 27Connection: 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 下復(fù)制文件。它只能操作文件，不能操作文件夾。
請(qǐng)求信息
PUT /<bucket>/<save_as_file>
參數(shù)
| 參數(shù) | 必選 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|---|
| x-amz-copy-source | 是 | string | 源文件地址，格式 /<bucket>/<source-to-file> |
響應(yīng)信息
200 狀態(tài)碼。舉例
xxxxxxxxxx151PUT /bucket-7/west.txt HTTP/1.12Host: fss-my.vhostgo.com3Date: Wed, 12 Oct 2023 17:50:00 GMT4x-amz-copy-source: /bucket-7/test/west.copy5Authorization: authorization string6?7HTTP/1.1 200 OK8x-amz-request-id: 3141cdab-1337-4872-b6e7-e83ec0f9fc979Date: Wed, 28 Oct 2009 22:32:00 GMT10Connection: close11?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ù) | 必選 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|---|
| Range | 否 | string | Range: byte=0-499表示第0-499字節(jié)范圍的內(nèi)容。Range: byte=-500表示最后500字節(jié)的內(nèi)容。Range: byte=500-表示從第500字節(jié)開(kāi)始到文件結(jié)束部分的內(nèi)容。Range: byte=0-表示從第一個(gè)字節(jié)到最后一個(gè)字節(jié)，即完整的文件內(nèi)容。 |
注
響應(yīng)信息
200，HTTP body 中返回文件內(nèi)容。請(qǐng)求信息
DELETE /<bucket>/<path_to_file>
響應(yīng)信息
200。請(qǐng)求信息
HEAD /<bucket>/<path_to_file>
響應(yīng)信息
200，返回頭信息如下所示： | 響應(yīng)頭 | 說(shuō)明 |
|---|---|
| Last-Modified | 最后修改時(shí)間 |
| ETag | 資源內(nèi)容的哈希值，用于表示對(duì)象內(nèi)容的變化，而不是元數(shù)據(jù)的變化。ETag 的值并不總是對(duì)象數(shù)據(jù)的 MD5 值，具體取決于請(qǐng)求的方式 |
| x-amz-meta-x | 文件元數(shù)據(jù) |
請(qǐng)求信息
GET /<bucket>/<path_to_folder>/?list-type=2
分頁(yè)參數(shù)
如果目錄中文件數(shù)量過(guò)多，為了更友好的獲取文件信息，可以分頁(yè)獲?。?/span>
參數(shù)
| 參數(shù) | 必選 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|---|
| 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ù) | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| Delimiter | string | 指定目錄分隔符 |
| IsTruncated | Boolean | 返表示是否還有更多可返回的資源。當(dāng)所有結(jié)果都已返回時(shí)，該參數(shù)設(shè)為false；當(dāng)還有更多資源可返回時(shí)，該參數(shù)設(shè)為true。如果結(jié)果數(shù)量超過(guò)了MaxKeys指定的數(shù)量，可能不會(huì)返回所有結(jié)果 |
| MaxKeys | string | 返回的資源的最大數(shù)量 |
| Prefix | string | 以特定前綴開(kāi)頭的資源 |
| ContinuationToken | string | 如果請(qǐng)求中帶有 Continuation-token，它將包含在響應(yīng)中 |
| NextContinuationToken | string | 返如果響應(yīng)被截?cái)啵琒3 將返回此參數(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 | 資源名稱(chēng) |
| LastModified | DATE | 對(duì)象的最后修改日期和時(shí)間 |
| Size | string | 對(duì)象的大小，以字節(jié)為單位 |
舉例
261GET /?list-type=2 HTTP/1.1 2Host: bucket-7.fss-my.vhostgo.com3X-Amz-Date: 20230628T063714Z4Authorization: authorization string5Content-Type: text/plain 6?7HTTP/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>