FileAPI - infoplus/docs GitHub Wiki

接口概述

  • FileAPI旨在存储、管理文件。上传到FileAPI的文件会产生持久化的链接（或也可以认为是文件的唯一id）
  • GraphQL版文档请访问：FileAPIv2

文件上传

PUT "/file" @returns Response<File>
  • 上传协议完全符合HTTP的multipart/form-data的上传方式，可使用如下命令直接测试：
curl -XPUT -F [email protected] "http://example.com/file?access_token={token}"
Parameter Type Description
secure boolean 指定下载文件时是否需要token控制，参考 [安全文件](#安全文件）
download boolean 浏览器访问时是否强制下载（通过 Content-Disposition:attachment 头）
meta JSON 额外meta信息，比如指定token等信息

文件下载

GET "/file/{id}" @returns <文件流>
  • 默认情况下可免token，此链接可直接提供给浏览器使用（用于下载、图片显示等）
  • 安全方式需要给出access_token，具体请参考后续“安全附件”章节。
Parameter Type Description
download boolean 浏览器访问时是否强制下载，优先于上传时download参数

文件修改

POST "/file/{id}" @returns Response<File>
  • 文件修改，相当于重传但保持id，格式与上传相同

文件删除

DELETE "/file/{id}"

文件meta信息查询、管理

GET/POST "/file/{id}/meta" @returns Response<File>
  • 获取或修改该文件的meta数据，包含文件名、创建日期、修改日期、文件大小等
  • 举例：
curl -XPOST -d '{"meta":{"secure":true,"token":"********"}}' "http://example.com/file?access_token={token}"
  • 可在meta中指定需要生成的缩略图尺寸
  • 可在meta中制定download参数修改“强制下载”的开关

缩略图

* GET "/file/{id}/thumb/{size}" @returns {文件流}
  • 下载缩略图，size格式为"NxM"。（如无该尺寸，则就近匹配？）

数据结构

// TYPE {file} 
{
    "mime":{string},                      // 文件类型，未知二进制类型为"application/octet-stream", 参见MIME types定义。
    "size":{integer},                     // 文件大小，单位byte
    "createTime":{long},                  // 创建日期
    "lastModified":{long},                // 最后修改日期
    "thumbsizes":["n1*m1","n2*m2",...],   // 获取或指定上传的文件需要生成以下规格的缩略图，最多允许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. http://en.wikipedia.org/wiki/Internet_media_type
  2. http://www.ietf.org/rfc/rfc2046.txt

安全文件

背景

  • FileAPI提供的下载链接默认是匿名的，任何人知道链接即可访问。 这在非HTTPS、链接被分享扩散情况下，存在一定的安全风险
  • 可对单独文件设置为“安全的”，其语义是：下载该文件必须先提供一个token
  • token可分为三种，可分别支持服务端/客户端获取、限时/限次、要求登录等功能
  • 201803新增

规范

  • 对于单个文件，可设定 meta.secure = true ，含义为下载时必须在 url 中给出 access_token。可通过如下方法设置：
  1. PUT /file?secure=true
  2. POST /file/{id}/meta
  • 其他 meta 参数：
{
  "secure" : {boolean},     // 是否验证token，默认false
  "token" : {string},       // token内容
  "tokenExpire" : {long},   // token超时时间，Unix时间戳，仅适用于自管token
  "tokenDisposable" : {boolean}, // 是否一次性，默认false，仅适用于自管token
}
  • 三种 token
  1. 应用授权的oauth的token
    应用场景是：应用负责变更最终交付给用户的下载链接。不允许浏览器直接下载。
    适用于应用本身有足够知识精确保护的情况，可提供最大的安全性
    此场景的限制是：需要服务端导流量、需高度定制化使用
  2. 用户授权的oauth的token
    应用场景是：与上面场景相似，但可做下载审计。不允许浏览器直接下载。
    此场景的限制是：需用户授权
  3. FileAPI自管token
    应用场景是：调用FileAPI生成token可用于前端直接使用
    可通过时间戳或次数保障链接分享不带来安全问题
    此场景的限制是：链接刷新后失效。
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️