文件存储 API

@cz 最后修改于 2020-07-13 10:43:08 rev.5230 - 最近修改

文件存储 API

概述

收集平台各种小型文件，图片音频等。提供文件列表查询、删除、下载等接口。

版本

V2.1

作者

ChengZhen

修改记录

2018/9/10

重新整理文档

文件管理

属性列表

NAME	SORTABLE	TYPE	DESCRIPTION
id	-	ObjectId	文件 ID
created	true	Date	创建时间, 单位为毫秒
etag	true	String	文件 Etag, 唯一标识同一内容的文件
maintype	true	String	MIME 主类型
name	true	String	文件名, 1 到 255 个字符
ownerId	true	ObjectId	用户的 ID
size	true	Number	文件大小, 单位为字节
subtype	true	String	MIME 次类型
updated	true	Date	修改时间, 单位为毫秒

主类型:

image, video, audio

次类型:

jpeg, png, mp3, mp4

etag:

默认为文件内容 MD5 Hash 值字符串

上传文件

可以用new FormData 把上传的文件数据序列化，例如new FormData().append(key,value),key必须为“files”,value为文件数据，多文件上传就append多个数据；通过Ajax传输这个序列，设置Ajax参数contentType为false。

POST /file/upload (or PUT /file/)

请求格式

Content-Type: multipart/form-data; boundary=${boundary}

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
files	true	buffer	文件内容

响应结果:

返回上传的文件的信息

{
    "files": [{
        "created": Number,      // 文件创建时间
        "id": String,           // 文件 ID
        "maintype": String,     // 文件主类型
        "name": String,         // 文件名称
        "etag": String,         // 文件 etag
        "owner": String,        // 文件拥有者
        "size": Number,         // 文件大小
        "subtype": String,      // 文件次类型
        "updated": Number       // 文件最后修改时间
    }]
}

查询文件列表

GET /file/list (or GET /file/)

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	1	分页索引值
limit	Number	10	每页最大结果数
orderBy	String	created	要排序的字段
order	String	asc	排序方式 (asc:升序,desc:降序)
q	String	-	查询条件
maintype	String	-	文件主类型
subtype	String	-	文件次类型
owner	String	-	文件拥有者
etag	String	-	文件 etag
name	String	-	文件名

示例

/file/list?offset=0&maxResult10&orderBy=name&q=maintype==image

响应结果:

返回包含文件信息的列表

{
    "files": [{
        "created": Number,      // 文件创建时间
        "id": String,           // 文件 ID
        "maintype": String,     // 文件主类型
        "name": String,         // 文件名称
        "etag": String,         // 文件 etag
        "owner": String,        // 文件拥有者
        "size": Number,         // 文件大小
        "subtype": String,      // 文件次类型
        "updated": Number       // 文件最后修改时间
    }],
    "total": Number
}

删除文件

POST /file/del (or DELETE /file/:id)

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	要删除的文件的 ID

说明:

如果文件不存在, 则返回 404 Not Found

响应结果:

返回删除的文件的信息

{
    "created": Number,      // 文件创建时间
    "id": String,           // 文件 ID
    "maintype": String,     // 文件主类型
    "name": String,         // 文件名称
    "etag": String,         // 文件 etag
    "owner": String,        // 文件拥有者
    "size": Number,         // 文件大小
    "subtype": String,      // 文件次类型
    "updated": Number       // 文件最后修改时间
}

修改文件属性

POST /file/update (or POST /file/:id)

请求参数:

NAME	REQUIRED	TYPE	DEFAULT	DESCRIPTION
id	true	ObjectId	-	要修改的文件的 ID
name	-	String	-	修改后的文件名称

响应结果:

返回修改后的文件的信息

{
    "created": Number,      // 文件创建时间
    "id": String,           // 文件 ID
    "maintype": String,     // 文件主类型
    "name": String,         // 文件名称
    "etag": String,         // 文件 etag
    "owner": String,        // 文件拥有者
    "size": Number,         // 文件大小
    "subtype": String,      // 文件次类型
    "updated": Number       // 文件最后修改时间
}

访问文件

下载文件

GET /file/:id/

GET /:maintype/:name

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	文件的 ID
maintype	true	String	文件的主类型, 如 audio, image, video
subtype	true	String	文件的子类型, 如 jpeg, mp3, mp4
name	true	String	文件的名称, 如 'test.jpg'

说明:

如果文件不存在, 则返回 404 Not Found
目前只支持 audio, image, video 主类型

示例:

/file/31b84669d4ec6ddbf0db54d8b551f8ea.jpeg
/file/e42876e1c9fa61c1e5c44a58705a78f9.mp3

/image/raw.jpeg
/audio/raw.mp3

响应头:

Content-Type: ${file.mimetype}
Content-Length: ${file.size}
Last-Modified: ${format(file.created)}
Etag: ${file.id}

响应结果:

如果 If-None-Match 和 If-Modified-Since 和文件的 ID 和修改时间匹配, 则返回不包含文件内容的状态码为 304 的 HTTP 应答.

否则返回文件内容.

下载缩略图

缩略图和原图的宽高保持原比例, 缩略图总是 jpeg 格式.

GET /file/thumbnail/:id.jpeg (or GET /file/:id/thumbnail.jpeg)

请求参数:

NAME	REQUIRED	TYPE	DEFAULT	DESCRIPTION
id	true	ObjectId	-	要取缩略图图片对应的 id 值
size	-	Number	750	设置压缩图片的宽高压缩上限

说明:

如果文件不存在, 则返回 404 Not Found

示例:

短边不超过 172, 长边按比缩小, 比如压缩后 200x172, 172x200
/file/thumbnail/e42876e1c9fa61c1e5c44a58705a78f9?size=172
/file/e42876e1c9fa61c1e5c44a58705a78f9/thumbnail.jpeg?size=172

宽和高都是 172, 多余的部分将被裁减, 比如压缩后 172x172
/file/e42876e1c9fa61c1e5c44a58705a78f9/thumbnail.jpeg?size=172,172

长边不超过 172, 短边按比缩小, 比如压缩后 100x172, 172x100
/file/e42876e1c9fa61c1e5c44a58705a78f9/thumbnail.jpeg?size=0,172
/file/e42876e1c9fa61c1e5c44a58705a78f9/thumbnail.jpeg?size=172,0

响应头:

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: ${thumbnail.size}
Last-Modified: ${Date(file.created)}
Etag: ${file.etag}
...

响应结果:

如果 If-None-Match 和 If-Modified-Since 和文件的 ID 和修改时间匹配, 则返回不包含文件内容的状态码为 304 的 HTTP 应答.

否则返回文件内容.

统计信息

全局统计信息

GET /file/stat

响应结果:

{
    "count": {
        "total": Number,   // 总文件数
        "images": Number,  // 图片文件数
        "audio": Number,   // 音频文件数
        "video": Number    // 视频文件数
    },
    "size": {
        "total": Number,   // 总文件大小, 单位为字节
        "images": Number,  // 图片文件大小
        "audio": Number,   // 音频文件大小
        "video": Number    // 视频文件大小
    }
}

用户统计信息

GET /file/stat/self

响应结果:

{
    "count": {
        "total": Number,   // 总文件数
        "images": Number,  // 图片文件数
        "audio": Number,   // 音频文件数
        "video": Number    // 视频文件数
    },
    "size": {
        "total": Number,   // 总文件大小, 单位为字节
        "images": Number,  // 图片文件大小
        "audio": Number,   // 音频文件大小
        "video": Number    // 视频文件大小
    }
}