S3 API

基于 AWS 架构的 API,您可以使用任何编程语言发送 HTTP/HTTPS 请求。所有请求参数均通过 HTTP/HTTPS 请求头以 Key: Value 的形式传递。 特别的,FSS仅支持文件相关的API,不支持区域相关配置。 access key id是用戶名,secret access key是用戶密码。

请求方法

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-Lengthstring请求内容长度
Content-MD5string上传文件的 MD5 值,如果请求中文件太大计算 MD5 不方便,可以为空
Content-Typestring文件类型,默认使用文件扩展名作为文件类型
x-amz-meta-xstring文件元数据,见 Metadata

响应信息

举例

文件分块上传

分片限制

限制项规格
单个Part大小1M,除去最后一个分片外,其它均为1M大小的块

初始化

初始化分块上传任务,并得到全局唯一任务 UploadId,后续分块任务相关接口都需要 UploadId 作为请求参数。

请求信息

参数

参数必选类型说明
x-west-multi-lengthstring上传文件的大小
Content-MD5string上传文件的 MD5 值,如果请求中文件太大计算 MD5 不方便,可以为空。使用时请勿在使用请求体上传文件
Content-Typestring文件类型,默认使用文件扩展名作为文件类型
x-amz-meta-xstring文件元数据

响应信息

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

响应内容

参数类型说明
InitiateMultipartUploadResultContainer上传文件的大小
Bucketstring空间名称
Keystring资源名称
UploadIdstring初始化任务生成的ID。 上传分片 UploadPart API调用时用作请求参数

举例

上传块

分块上传数据,需指定的任务 UploadId

请求信息

参数

参数必选类型说明
ObjectNamestring初始化分片任务的对象
PartNumberstring上传的分块编号。介于1和10,000之间的正整数
UploadIdstring上传任务ID。可从初始化任务接口响应信息中获取

响应信息

举例

完成上传

请求信息

参数

参数必选类型说明
ObjectNamestring资源名称
UploadIdstring上传任务ID。可从初始化任务接口响应信息中获取

响应信息

举例

复制文件

bucket 下复制文件。它只能操作文件,不能操作文件夹。

请求信息

PUT /<bucket>/<save_as_file>

参数

参数必选类型说明
x-amz-copy-sourcestring源文件地址,格式 /<bucket>/<source-to-file>

响应信息

举例

下载文件

用于获取一个资源的元数据及对象数据,可以获取全部数据或者使用 Range 指定获取部分数据

请求信息

GET /<bucket>/<path_to_file>

参数

参数必选类型说明
RangestringRange: byte=0-499表示第0-499字节范围的内容。Range: byte=-500表示最后500字节的内容。Range: byte=500-表示从第500字节开始到文件结束部分的内容。Range: byte=0-表示从第一个字节到最后一个字节,即完整的文件内容。

响应信息

删除文件

请求信息

DELETE /<bucket>/<path_to_file>

响应信息

获取文件信息

请求信息

HEAD /<bucket>/<path_to_file>

响应信息

响应头说明
Last-Modified最后修改时间
ETag资源内容的哈希值,用于表示对象内容的变化,而不是元数据的变化。ETag 的值并不总是对象数据的 MD5 值,具体取决于请求的方式
x-amz-meta-x文件元数据

获取目录文件列表

请求信息

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

分页参数

如果目录中文件数量过多,为了更友好的获取文件信息,可以分页获取:

参数

参数必选类型说明
list-typestringAPI 的第二版本要求使用该参数,并且值必须设置为 2
max-keysstring返回资源的最大数量。默认值为 1000
prefixstring指定前缀,只有资源名匹配该前缀的资源会被列出。默认值为空字符串
delimiterstring指定目录分隔符,列出所有公共前缀(模拟列出目录效果)。默认值为空字符串

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

响应信息

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

响应内容

参数类型说明
Delimiterstring指定目录分隔符
IsTruncatedBoolean返表示是否还有更多可返回的资源。当所有结果都已返回时,该参数设为false;当还有更多资源可返回时,该参数设为true。如果结果数量超过了MaxKeys指定的数量,可能不会返回所有结果
MaxKeysstring返回的资源的最大数量
Prefixstring以特定前缀开头的资源
ContinuationTokenstring如果请求中带有 Continuation-token,它将包含在响应中
NextContinuationTokenstring返如果响应被截断,S3 将返回此参数及其对应的续传令牌。您可以将该令牌作为 continuation-token 在下一个请求中指定,检索下一组资源
CommonPrefixesstring将合并为公共前缀的资源计为单个返回,并列出充当子目录的资源
ETagstring对象的 MD5 哈希值。ETag 仅反映对象内容的更改,而不包括其元数据的更改
Keystring资源名称
LastModifiedDATE对象的最后修改日期和时间
Sizestring对象的大小,以字节为单位

举例