REST API

基于 RESTful 架构的 API,您可以使用任何编程语言发送 HTTP/HTTPS 请求。所有请求参数均通过 HTTP/HTTPS 请求头以 Key: Value 的形式传递。

请求方法

域名

bucket、path

<> 是参数内容,是需要用户填写的,填写时,把 <> 去掉。

bucket,是创建的桶名;path,文件/文件夹的路径。

并发请求限制

单个桶更新请求并发数不超过100个,GET/HEAD请求不限

Authorization

关于认证鉴权,详见认证鉴权

上传文件

在上传图片文件时,可以设置预处理参数,图片会处理后再保存。

PUT /<bucket>/<path_to_file>

上传参数

参数 必选 类型 说明
Content-Length string 请求内容长度
Content-MD5 string 上传文件的 MD5 值,如果请求中文件太大计算 MD5 不方便,可以为空
Content-Type string 文件类型,默认使用文件扩展名作为文件类型
Content-Secret string 文件密钥,用于保护文件,防止文件被直接访问,见 Content-Secret 参数说明
x-west-meta-x string 文件元信息,见 Metadata
x-west-meta-ttl string 文件元信息, 指定文件的生存时间,单位天,最大支持180天,见 Metadata
x-west-overwrite string 上传文件时覆盖已存在文件,默认为false
x-west-automkdir string 上传文件时目录不存在自动创建,默认false
x-gmkerl-thumb string 图片预处理参数,见图片处理
x-west-async string true表示异步处理

响应信息

Content-Secret 参数说明

文件分块上传

请求信息

PUT /<bucket>/<save_as_file>

文件大小最大为13T,除最后一块外,其余每块大小固定为1M字节,分块上传不区分串行和并行,在初始化完成后,可并行上传块,待所有块上传完毕后,执行完成块上传请求。

初始化

参数

参数 必选 类型 说明
x-west-multi-disorder string 值为true,表示进行分块上传
x-west-multi-stage string initiate:初始化
x-west-multi-length string 待上传文件的大小,单位 Byte
x-west-multi-type string 文件mime类型
x-west-overwrite string 上传文件时覆盖已存在文件,默认为false
x-west-automkdir string 上传文件时目录不存在自动创建,默认false
x-west-meta-x string 文件元信息
x-west-meta-ttl string 文件生存时间,单位天,最大支持180天

上传块

参数

参数 必选 类型 说明
x-west-multi-disorder string 值为true,表示进行分块上传
x-west-multi-stage string upload:块上传
x-west-part-id string 分块序号,序号从0开始,支持断点续传
Content-Length string 请求内容长度
Content-MD5 string 上传文件的MD5值

完成上传

参数

参数 必选 类型 说明
x-west-multi-disorder string 值为true,表示进行分块上传
x-west-multi-stage string complete:完成上传

响应信息

举例

初始化:

上传块:

完成上传:

复制文件

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

请求信息

PUT /<bucket>/<save_as_file>

参数

参数 必选 类型 说明
x-west-copy-source string 源文件地址,格式 /<bucket>/<source-to-file>
x-west-automkdir string 复制文件时目录不存在自动创建,默认false
x-west-metadata-directive string 对x-west-metadata-x操作的方式,取值为:copy(默认),merge,replace,delete,具体每种取值含义详见:Metadataoption说明
x-west-metadata-x string 设置文件元信息

响应信息

举例

移动文件

bucket 下移动文件,可以进行文件重命名、文件移动。它只能操作文件,不能操作文件夹。

请求信息

PUT /<bucket>/<save_as_file>

参数

参数 必选 类型 说明
x-west-move-source string 源文件地址,格式 /<bucket>/<source-to-file>
x-west-automkdir string 移动文件时目录不存在自动创建,默认false
x-west-metadata-directive string 对x-west-metadata-x操作的方式,取值为:copy(默认),merge,replace,delete,具体每种取值含义详见:Metadataoption说明
x-west-metadata-x string 设置文件元信息

响应信息

举例

下载文件

请求信息

GET /<bucket>/<path_to_file>

参数

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

响应信息

删除文件

请求信息

DELETE /<bucket>/<path_to_file>

参数

参数 必选 类型 说明
x-west-async string true 表示进行异步删除,不设置表示同步删除(默认)

响应信息

创建目录

请求信息

POST /<bucket>/<path_to_folder>

参数

参数 必选 类型 说明
folder string 要创建的目录的名称,放在url中

响应信息

删除目录

请求信息

DELETE /<bucket>/<path_to_folder>

响应信息

获取文件信息

请求信息

HEAD /<bucket>/<path_to_file>

响应信息

响应头 说明
x-west-file-type 文件类型
x-west-file-size 文件大小
x-west-file-date 文件创建时间
x-west-meta-x 返回设置的元信息,返回数量与设置情况一致

获取目录文件列表

请求信息

GET /<bucket>/<path_to_folder>

分页参数

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

参数

参数 必选 类型 说明
x-list-iter string 分页开始位置,通过x-west-list-iter响应头返回,所以第一次请求不需要填写
x-list-limit string 获取的文件数量,默认 100,最大 10000
x-list-order string asc 或 desc,按文件名升序或降序排列。默认 asc

响应信息

修改 Metadata

请求信息

PATCH /<bucket>/<path_to_file>?metadata=<option>

option 的取值如下:

option 说明
merge(默认) 合并文件元信息,如果是相同的元信息,将被新上传的值替换
replace 替换文件元信息为新上传的文件元信息
delete 删除文件元信息

参数

参数 必选 类型 说明
x-west-meta-x string 设置文件元信息

响应信息

举例

例 1:合并元信息,metadata=merge

文件 test.txt 的元信息是:

例 2:替换元信息,metadata=replace

文件 test.txt 的元信息为:

例 3:删除元信息,metadata=delete

文件 test.txt 的元信息为: