# File APIs

本组API用于处理文件的上传、下载等功能。

使用本组API前请先阅读概述，使用前的准备工作请参考此处，令牌的获取参考此处，构造请求请参考此处，返回数据请参考此处，除非特殊注明，所有开放式API有着通用的返回结构。
每个API的授权方式、授权范围和是否API SDK支持请查看以下每个API详细的表述。

# 安全策略

FileAPI是文件上传下载用API。用户通过获取scope为storage的OAuth2认证体系token可以上传文件。
上传的文件的安全等级分为安全和普通两类，限制文件下载权限。普通安全等级的文件，提供文件id即可下载，安全等级的文件需要提供token才可下载。
文件安全下载用的token有两类：

OAuth2认证体系token
用户通过OAuth2协议获取scope为storage的token，即可下载安全下载类文件
FileAPI自定义token 通过设置file的meta可以设置自定义token，用于文件安全下载。自定义token的有效性限制分为限次和限时。具体设置方法如下：

POST /file/{id}/meta HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type:application/json

{
   "meta": {
        "secure": {boolean},          //文件安全等级设置，true表示安全下载类，false表示普通类。缺省表示普通类
        "token": {String},            //用户自定义token
        "tokenDisposable": {boolean}, //限次类别设置，false表示多次下载，true表示一次性下载。默认false。
        "tokenExpire" : {long}        // token超时时间，Unix时间戳。值小于等于0或者未设置值，表示不限时   
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

# 上传文件

PUT https://api.sjtu.edu.cn/v1/file 客户端 storage SDK

# 功能介绍

上传一个文件，返回该文件的metadata。

# 请求参数

file 需要上传的文件
secure 是否安全上传，true：下载有权限限制； false：下载无权限限制
access_token 有storage权限的token

# 请求数据格式

设置Content-Type请求头为multipart/form-data

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

File 文件 Structure

{
    "mime":{string},                      // 文件类型，未知二进制类型为"application/octet-stream", MIME types参见附录
    "size":{integer},                     // 文件大小，单位byte
    "createTime":{long},                  // 创建日期
    "lastModified":{long},                // 最后修改日期
    "thumbsizes":["n1xm1","n2xm2",...],   // 获取或指定上传的文件需要生成以下规格的缩略图，最多允许5张，如果比例和原比例不同，则会拉伸。缩略图大小不会超过原图，同时不会超过1024x768
    "sha1Hash":{String}
    "tags":{string},                      // 逗号分隔的字符串
    "meta":{
       "secure":{boolean},
       "token" : {string},                // token内容
       "tokenExpire" : {long},            // token超时时间，Unix时间戳
       "tokenDisposable" : {boolean},     // 是否一次性，默认false
    },
    "id":{guid},
    "name":{string},                      // 文件名
    "kind":"canvas.file",                 // 常量
    "uri":{uri},                          // 文件下载地址
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 请求示例

示例上传一个文件

curl -v -F file=@test.png -X PUT "https://api.sjtu.edu.cn/v1/file?access_token=token"

PUT /v1/file?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: multipart/form-data;

1
2
3
4
5

# 响应示例

示例成功返回的数据

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno":0,
    "error":"Succeed",
    "total":1,
    "entities":[{
        "mime":"application/octet-stream",
        "size":2408947,
        "createTime":1616481372,
        "lastModified":1616481372,
        "meta":{
            "secure":true
        },
        "sha1Hash":"900150983cd24fb0d6963f7d28e17f725bc82409",
        "id":"78d84aab-0155-4afe-8abe-faf1c961b0e7",
        "name":"standard-preview.png",
        "kind":"canvas.file",
        "uri":"https://api.sjtu.edu.cn/v1/file/78d84aab-0155-4afe-8abe-faf1c961b0e7"
    }]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 下载文件

GET https://api.sjtu.edu.cn/v1/file/{id}?access_token={token}

# 功能介绍

下载文件，支持普通下载或者安全下载(带着token下载，token可以限次或者限时)。

# 请求参数

普通下载时须提供路径参数id，这是文件的唯一标识
安全下载时须提供请求参数token，这是用户自定义的token，如果文件需要安全下载但未提供该参数会被服务器403拒绝

# 响应参数

无参数，响应为文件二进制流

# 请求示例

示例安全下载文件

curl -v -X GET "https://api.sjtu.edu.cn/v1/file/bcd0f75b-eb07-404f-9465-94d7b97fe01d?access_token=token"

# 修改文件

POST https://api.sjtu.edu.cn/v1/file/{id} 客户端 storage SDK

# 功能介绍

重新上传文件，修改文件内容。

# 请求参数

同上传文件接口(PUT方法)

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

同上传文件接口(PUT方法)，参见以上的File 文件响应参数

# 请求示例

示例修改一个文件

curl -v -F file=@tool.png -X POST "https://api.sjtu.edu.cn/v1/file/bcd0f75b-eb07-404f-9465-94d7b97fe01d?access_token=token

# 响应示例

参见上传文件响应示例

# 获取文件信息

GET https://api.sjtu.edu.cn/v1/file/{id}/meta 客户端 storage SDK

# 功能介绍

获取该文件的metadata，默认包含文件名、创建日期、修改日期、文件大小等。

# 请求参数

路径参数id 文件的唯一标识

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

返回修改后的文件信息，数据结构同上传文件接口(PUT方法)，参见以上的File 文件响应参数

# 请求示例

GET /v1/file/bcd0f75b-eb07-404f-9465-94d7b97fe01d/meta?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn

1
2

# 响应示例

示例获取文件信息的返回数据

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno": 0,
    "error": "Succeed",
    "total": 0,
    "entities": [{
        "mime": "application/octet-stream",
        "size": 547,
        "createTime": 1616482800,
        "lastModified": 1616482800,
        "meta": {},
        "sha1Hash": "b258a5f87240f336b46710283db506729cb193ce",
        "id": "bcd0f75b-eb07-404f-9465-94d7b97fe01d",
        "name": "tools.png",
        "kind": "canvas.file",
        "uri": "https://api.sjtu.edu.cn/v1/file/bcd0f75b-eb07-404f-9465-94d7b97fe01d"
    }]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 修改文件信息

POST https://api.sjtu.edu.cn/v1/file/{id}/meta 客户端 storage SDK

# 功能介绍

修改该文件的metadata

# 请求参数

请求体中携带File信息，数据结构参见以上的File 文件响应参数
修改的metadata采用更新模式，即本次调用未设置的meta值不变。

# 响应参数

所有API的响应参数都具有相同的通用结构，本文档只描述通用结构中entities数组返回的数据对象。

返回修改后文件的metadata,数据结构参见以上的File 文件响应参数

# 请求示例

示例修改文件为安全下载

curl -v -d '{"meta":{"secure":true,"token":"testtoken"}}' -X POST 
"https://api.sjtu.edu.cn/v1/file/bcd0f75b-eb07-404f-9465-94d7b97fe01d/meta?access_token=token"

1
2

# 响应示例

示例修改文件信息后的返回数据

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno": 0,
    "error": "Succeed",
    "total": 1,
    "entities": [{
        "mime": "application/octet-stream",
        "size": 547,
        "createTime": 1616482800,
        "lastModified": 1616482800,
        "meta": {
            "tokenDisposable": false,
            "secure": true,
            "token": "testtoken"
        },
        "sha1Hash": "b258a5f87240f336b46710283db506729cb193ce",
        "id": "bcd0f75b-eb07-404f-9465-94d7b97fe01d",
        "name": "tools.png",
        "kind": "canvas.file",
        "uri": "https://api.sjtu.edu.cn/v1/file/bcd0f75b-eb07-404f-9465-94d7b97fe01d"
    }]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 下载缩略图

GET https://api.sjtu.edu.cn/v1/file/{id}/thumb/{N}x{M}

# 功能介绍

下载缩略图，size为n乘m。(如无该尺寸，就下载原图)。注意需要先通过调用[修改文件信息]接口，通过设置thumbsizes数组预产生缩略图后才能下载对应尺寸的缩略图，如果请求路径中的尺寸不存在，那么将下载原图。

# 请求参数

# 路径参数

id 文件唯一标识
N，M 缩略图的宽和高

# 响应参数

响应为文件二进制流，如果预先产生了指定的尺寸就下载对应的缩略图，如果没该尺寸就下载原图

# 产生缩略图

示例通过修改文件信息产生缩略图

# 注意事项

注意缩略图尺寸中间是小写字母x
缩略图尺寸最多5个
如果尺寸和原图比例不同，会产生拉伸
缩略图尺寸不会超过原图，且不会超过1024x768

POST /v1/file/d0bec45e-14c5-44b0-a441-3193ce2f864f/meta?access_token=token HTTP/1.1
Host: api.sjtu.edu.cn
Content-Type: application/json

{
    "thumbsizes":["50x200","200x800"]
}

1
2
3
4
5
6
7

本例的调用产生了50x200和200x800两个缩略图，此次POST请求的响应如下

示例产生缩略图的响应

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "errno": 0,
    "error": "Succeed",
    "total": 1,
    "entities": [{
        "mime": "application/octet-stream",
        "size": 2408947,
        "createTime": 1616551115,
        "lastModified": 1616551115,
        "thumbsizes": [
          "50x200",
          "200x800"
        ],
        "thumbSha1Hashs": [
          "dbd3037db3de1fd09defd71725094b5480455697",
          "f2d8ccdc10c16b77eec7957f2a08b9ebfbec206d"
        ],
        "meta": {
          "tokenDisposable": false
        },
        "sha1Hash": "18ea57d8ce81f236de603e9ef49452765bc82409",
        "id": "d0bec45e-14c5-44b0-a441-3193ce2f864f",
        "name": "standard-preview.png",
        "kind": "canvas.file",
        "uri": "https://api.sjtu.edu.cn/v1/file/d0bec45e-14c5-44b0-a441-3193ce2f864f"
    }]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 下载缩略图

缩略图产生后即可下载

示例下载缩略图

GET /v1/file/d0bec45e-14c5-44b0-a441-3193ce2f864f/thumb/50x200 HTTP/1.1
Host: api.sjtu.edu.cn

1
2

# 附录

# MIME Types Data

参考: MIME types on Wikipedia (opens new window)、RFC2046 MIME part 2 (opens new window)

file type	MIME type
ai	application/postscript
aif	audio/x-aiff
aifc	audio/x-aiff
aiff	audio/x-aiff
asc	text/plain
atom	application/atom+xml
au	audio/basic
avi	video/x-msvideo
bcpio	application/x-bcpio
bin	application/octet-stream
bmp	image/bmp
cdf	application/x-netcdf
cgm	image/cgm
class	application/octet-stream
cpio	application/x-cpio
cpt	application/mac-compactpro
csh	application/x-csh
css	text/css
dcr	application/x-director
dif	video/x-dv
dir	application/x-director
djv	image/vnd.djvu
djvu	image/vnd.djvu
dll	application/octet-stream
dmg	application/octet-stream
dms	application/octet-stream
doc	application/msword
dtd	application/xml-dtd
dv	video/x-dv
dvi	application/x-dvi
dxr	application/x-director
eps	application/postscript
etx	text/x-setext
exe	application/octet-stream
ez	application/andrew-inset
gif	image/gif
gram	application/srgs
grxml	application/srgs+xml
gtar	application/x-gtar
hdf	application/x-hdf
hqx	application/mac-binhex40
htm	text/html
html	text/html
ice	x-conference/x-cooltalk
ico	image/x-icon
ics	text/calendar
ief	image/ief
ifb	text/calendar
iges	model/iges
igs	model/iges
jnlp	application/x-java-jnlp-file
jp2	image/jp2
jpe	image/jpeg
jpeg	image/jpeg
jpg	image/jpeg
js	application/x-javascript
kar	audio/midi
latex	application/x-latex
lha	application/octet-stream
lzh	application/octet-stream
m3u	audio/x-mpegurl
m4a	audio/mp4a-latm
m4b	audio/mp4a-latm
m4p	audio/mp4a-latm
m4u	video/vnd.mpegurl
m4v	video/x-m4v
mac	image/x-macpaint
man	application/x-troff-man
mathml	application/mathml+xml
me	application/x-troff-me
mesh	model/mesh
mid	audio/midi
midi	audio/midi
mif	application/vnd.mif
mov	video/quicktime
movie	video/x-sgi-movie
mp2	audio/mpeg
mp3	audio/mpeg
mp4	video/mp4
mpe	video/mpeg
mpeg	video/mpeg
mpg	video/mpeg
mpga	audio/mpeg
ms	application/x-troff-ms
msh	model/mesh
mxu	video/vnd.mpegurl
nc	application/x-netcdf
oda	application/oda
ogg	application/ogg
pbm	image/x-portable-bitmap
pct	image/pict
pdb	chemical/x-pdb
pdf	application/pdf
pgm	image/x-portable-graymap
pgn	application/x-chess-pgn
pic	image/pict
pict	image/pict
png	image/png
pnm	image/x-portable-anymap
pnt	image/x-macpaint
pntg	image/x-macpaint
ppm	image/x-portable-pixmap
ppt	application/vnd.ms-powerpoint
ps	application/postscript
qt	video/quicktime
qti	image/x-quicktime
qtif	image/x-quicktime
ra	audio/x-pn-realaudio
ram	audio/x-pn-realaudio
ras	image/x-cmu-raster
rdf	application/rdf+xml
rgb	image/x-rgb
rm	application/vnd.rn-realmedia
roff	application/x-troff
rtf	text/rtf
rtx	text/richtext
sgm	text/sgml
sgml	text/sgml
sh	application/x-sh
shar	application/x-shar
silo	model/mesh
sit	application/x-stuffit
skd	application/x-koan
skm	application/x-koan
skp	application/x-koan
skt	application/x-koan
smi	application/smil
smil	application/smil
snd	audio/basic
so	application/octet-stream
spl	application/x-futuresplash
src	application/x-wais-source
sv4cpio	application/x-sv4cpio
sv4crc	application/x-sv4crc
svg	image/svg+xml
swf	application/x-shockwave-flash
t	application/x-troff
tar	application/x-tar
tcl	application/x-tcl
tex	application/x-tex
texi	application/x-texinfo
texinfo	application/x-texinfo
tif	image/tiff
tiff	image/tiff
tr	application/x-troff
tsv	text/tab-separated-values
txt	text/plain
ustar	application/x-ustar
vcd	application/x-cdlink
vrml	model/vrml
vxml	application/voicexml+xml
wav	audio/x-wav
wbmp	image/vnd.wap.wbmp
wbmxl	application/vnd.wap.wbxml
wml	text/vnd.wap.wml
wmlc	application/vnd.wap.wmlc
wmls	text/vnd.wap.wmlscript
wmlsc	application/vnd.wap.wmlscriptc
wrl	model/vrml
xbm	image/x-xbitmap
xht	application/xhtml+xml
xhtml	application/xhtml+xml
xls	application/vnd.ms-excel
xml	application/xml
xpm	image/x-xpixmap
xsl	application/xml
xslt	application/xslt+xml
xul	application/vnd.mozilla.xul+xml
xwd	image/x-xwindowdump
xyz	chemical/x-xyz
zip	application/zip

← Enterprise APIs Notification APIs →