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
上传失败：返回相应的出错信息，具体请参阅「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。可从初始化任务接口响应信息中获取

该请求操作的实现仅使用了所有操作的公共请求头。有关详细信息，请查阅公共请求头

响应信息

该请求操作的实现仅使用了所有操作的公共响应头。有关详细信息，请查阅公共响应头
上传成功：返回 200
上传失败：返回相应的出错信息，具体请参阅「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>