接口概述

• 通过HTTP方式存取非结构化文件
• 多文件压缩打包
• 对图片进行尺寸转换和缩略图生成（尚未实现）
• REST版文档地址：FileAPI

技术标准

• 认证使用OAuth2，scope要求data
• 接口格式使用GraphQL
• 传输协议在使用Serve over HTTP，以及文件传输时使用Multipart Request，两者区别：
  • 两者使用同样地址、POST方法，但前者接收application/json请求，后者接收multipart/form-data请求
  • 前者参数名为query operationName 和 query，后者参数名为 operations 和 map

类型定义

type Query {
    # 查询文件元数据
    meta(id: String) : File
}

type Mutation {
    # 上传文件
    upload(file: Upload, secure: Boolean, download: Boolean) : File!    
    # 删除文件
    delete(id: String) : File
    # 压缩一组文件，或者查询进度
    archive(
        # ArchivePromise的id，如果给出，则忽略input参数
        id: String,
        # 压缩包定义
        input: ArchiveInput
    ): ArchivePromise!
}

type File {
    # 文件UUID
    id: ID
    # 文件名
    name: String
    # 文件字节数
    size: Int
    # 文件类型，参考RFC2046 https://datatracker.ietf.org/doc/html/rfc2046
    mime: String
    # 文件下载地址
    uri: String
    # 创建时间
    createTime: Int
    # 最后修改时间
    lastModified: Int
    # SHA1 签名
    sha1Hash: String
    # 标签
    tags: String
}

input ArchiveInput {
    # 压缩包名称，不含扩展名
    text: String!
    # 格式，目前仅支持zip
    format: String
    # 根文件夹
    root: ArchiveEntryInput!
}

# 一个文件或文件夹
input ArchiveEntryInput {
    # 文件/文件夹名
    # 对于文件，如果此字段不给出，使用默认文件名
    # 对于文件夹，如果此字段不给出，使用当前层文件夹，不创建子文件夹
    text: String
    # 文件ID，此字段给出则视为文件，忽略 entries 参数
    file: String
    # 子文件/文件夹列表
    entries: [ArchiveEntryInput!]
}

# 压缩任务返回值
type ArchivePromise {
    # Archive任务ID，用于后续查询
    id: ID
    # 下载地址
    uri: String
    # 当前处理进度(0, 100)，当执行完成时（100），成功会给出uri，否则给出error信息
    progress: Int
    # 任务执行出错后的错误信息
    error: String
}

scalar Upload