跳转至

文件（FileController）

提供 KMS 知识管理模块文件域的核心能力：文件详情查询、目录列表、回收站、文件移动/重命名/删除、内/外部分享、收藏、预览（含水印）、标签（贴/取/删）、批量操作、模板与归档文件创建等。本控制器是 kms 模块端点最多的控制器，所有端点均返回 JSON 资源。

  • 接口类型：REST 资源（@RestController，类级与所有方法级 produces = MediaType.APPLICATION_JSON_VALUE）
  • 基址：${myapps.context-path.kms:}/api/kms 与 ${myapps.context-path.kms:}/kms（类级 @RequestMapping 同时声明两个前缀，同一端点可经任一前缀访问；下文示例统一采用 /api/kms）
  • Tag：kms文件模块

公共说明

  • 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*），本控制器路径 /api/kms/**、/kms/** 均不在 KmsSecurityFilter.isExcludeURI 的豁免名单内（豁免仅覆盖 /login.*、/admin、/domain.*、/tray/service、/authtime、service/OfficeServer、.*outsideshare/.*/preview、静态资源后缀 .jpg/.gif/.png/.ico/.js/.css/.map/.woff/.html/.properties、actuator/health 等）。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401。因此所有端点均需 accessToken，可通过以下任一方式传递（据 Security.getUserIdFromToken）：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。
  • 特殊入参 mode=app（据源码）：当请求带 query 参数 mode=app（手机 App「嗨办公」场景）时，KmsSecurityFilter 会以 query 参数 userId 直接生成并下发 accessToken Cookie，跳过常规 token 校验；非 App 场景请勿使用。
  • 执行用户：控制器内 getUser()（继承自 AbstractBaseController）调用 Security.getUserIdFromToken(request) 还原当前用户 id，再经 Feign（UserAPI.getUserById）装载 KmsUser。无 userCode 参数。
  • 响应结构：统一 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。注意：KMS 的 Resource 为 AbstractBaseController 内部类，其构造器对 data 执行 ESAPI.encode(data) 做 XSS 编码，故 data 中的 HTML 特殊字符会被转义。
  • HTTP 状态码与错误码（据源码 AbstractBaseController 全局异常处理）：成功默认 HTTP 200；InvalidRequestException → HTTP 400 / errcode=400；UnauthorizedException → HTTP 403 / errcode=403；ForbiddenException（权限不足）→ HTTP 403 / errcode=403；ResourceNotFoundException → HTTP 404 / errcode=404；其他 Exception → HTTP 500 / errcode=500。个别端点（如 #43 deleteFileCategory）在 catch 块内显式返回 errcode=500。
  • @RequestParam 默认必填：未标 required=false 且无 defaultValue 的 query 参数按 Spring 约定为必填。
  • 路径变量：diskId、folderId、fileId、fileChecksum 等均为 KMS 内部主键（明文 id），非 DES 加密密文（与 runtime 模块不同）。

1. 获取文件详情

根据文件 Id 获取单个文件对象的详情。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/disks/folders/files/{fileId}（完整：{kms-context}/api/kms/disks/folders/files/{fileId}）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileId path string 是 文件Id

请求示例

GET /api/kms/disks/folders/files/__FILEID__?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：文件详情对象（由 dataBuilder.buildFileEntityReturnData 构造，包含文件实体与当前用户对该文件拥有的操作权限集合）。

成功示例： 

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "id": "__FILEID__", "name": "方案.docx", "type": "docx", "operations": [1, 2, 4] },
  "errors": null
}

2. 查询贡献者的上传文件数量

按当前用户所在企业域，统计贡献者（上传人）的上传文件数量，返回前 N 名。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/contributor/fileCount（完整：{kms-context}/api/kms/contributor/fileCount）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
topCount query int 否 返回前 N 名（源码标注 required=false，但为基本类型，建议显式传入）

请求示例

GET /api/kms/contributor/fileCount?topCount=10&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：ContributionFileCount 列表，每项含贡献者信息及其上传文件数。

3. 判断文件是否加密

根据文件相对路径判断该文件是否已加密。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/file/isencrypt（完整：{kms-context}/api/kms/file/isencrypt）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileUrl query string 是 文件相对路径（相对 kms/ 存储根目录）

请求示例

GET /api/kms/file/isencrypt?fileUrl=2024/01/abc.docx&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，true 表示文件已加密。

4. 目录下的文件列表

分页查询指定网盘下指定文件夹内的文件列表（含排序）。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/disks/{diskId}/folders/{folderId}/files（完整：{kms-context}/api/kms/disks/{diskId}/folders/{folderId}/files）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
folderId path string 是 文件夹Id
fileName query string 否 文件名过滤关键字
orderByfield query string 是 排序字段（如 NAME/SIZE/LAST_MODIFY_DATE 等）
orderMode query string 是 排序模式（ASC/DESC）
pageNo query int 是 页码，从 1 开始
linesPerPage query int 是 每页条数

请求示例

GET /api/kms/disks/__DISKID__/folders/__FOLDERID__/files?pageNo=1&linesPerPage=20&orderByfield=LAST_MODIFY_DATE&orderMode=DESC&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileObject>（由 dataBuilder.buildFileObjectReturnData 构造，包含当前页数据与分页信息）。

5. 获取回收站文件列表

分页查询当前用户企业域下、已软删除（is_delete=true 且 is_recycle_delete=false）的回收站文件。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/recycle/files（完整：{kms-context}/api/kms/recycle/files）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
pageNo query int 否 页码，默认 1
linesPerPage query int 否 每页条数，默认 10

请求示例

GET /api/kms/recycle/files?pageNo=1&linesPerPage=10&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>，回收站文件分页数据。

6. 恢复回收站

从回收站恢复文件/文件夹。若请求体 fileIds 与 folderIds 均为 null，则恢复当前用户回收站内的全部内容；否则按指定 Id 列表恢复（含递归恢复子文件夹）。

  • 接口类型：REST 资源
  • 请求方式：POST
  • 请求路径：/recycle/restore（完整：{kms-context}/api/kms/recycle/restore）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
body body object 是 JSON 对象，见下方请求体

请求体

{
  "fileIds": ["__FILEID1__", "__FILEID2__"],
  "folderIds": ["__FOLDERID1__"]
}

当 fileIds 与 folderIds 均不传（或为 null）时表示恢复全部。

请求示例

POST /api/kms/recycle/restore?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "fileIds": ["__FILEID1__"], "folderIds": ["__FOLDERID1__"] }

响应

结构：统一 Resource。 data：null（操作完成后返回 success("ok", null)）。

7. 删除回收站

将回收站中的文件/文件夹标记为彻底删除（置 is_recycle_delete=true）。若请求体 fileIds 与 folderIds 均为 null，则对当前用户回收站全部内容生效。

  • 接口类型：REST 资源
  • 请求方式：DELETE
  • 请求路径：/recycle（完整：{kms-context}/api/kms/recycle）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
body body object 是 JSON 对象，含 fileIds、folderIds 数组（结构同 #6）

请求示例

DELETE /api/kms/recycle?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "fileIds": ["__FILEID1__"], "folderIds": [] }

响应

结构：统一 Resource。 data：null。

8. 目录下的文件列表（移动端个人 km）

移动端专属：分页查询指定网盘下指定文件夹内的文件列表（与 #4 同语义，路径前缀含 /phone/，供移动端个人 km 使用）。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/disks/{diskId}/folders/{folderId}/phone/files（完整：{kms-context}/api/kms/disks/{diskId}/folders/{folderId}/phone/files）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
folderId path string 是 文件夹Id
fileName query string 否 文件名过滤关键字
orderByfield query string 是 排序字段
orderMode query string 是 排序模式（ASC/DESC）
pageNo query int 是 页码
linesPerPage query int 是 每页条数

请求示例

GET /api/kms/disks/__DISKID__/folders/__FOLDERID__/phone/files?pageNo=1&linesPerPage=20&orderByfield=LAST_MODIFY_DATE&orderMode=DESC&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileObject>（由 dataBuilder.buildFileObjectReturnData 构造）。

9. 目录下的文件列表（路径不含 diskId/folderId）

分页查询指定文件夹内的文件列表，folderId 通过 query 参数 ownerId 传入（路径中不出现 diskId/folderId）。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/disks/folders/files（完整：{kms-context}/api/kms/disks/folders/files）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
ownerId query string 否 文件夹Id（源码形参名 folderId，绑定到 query 参数 ownerId；建议传入）
fileName query string 否 文件名过滤关键字
orderByfield query string 否 排序字段
orderMode query string 否 排序模式
pageNo query int 是 页码
linesPerPage query int 是 每页条数

请求示例

GET /api/kms/disks/folders/files?ownerId=__FOLDERID__&pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileObject>（由 dataBuilder.buildFileObjectReturnData 构造）。

10. 查询文件

按文件名等条件分页查询文件（当前实现中核心服务调用被注释，data 当前始终为 null，保留接口占位）。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/files/data（完整：{kms-context}/api/kms/files/data）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileName query string 否 文件名过滤关键字
orderByfield query string 是 排序字段
orderMode query string 是 排序模式
pageNo query int 是 页码
linesPerPage query int 是 每页条数

请求示例

GET /api/kms/files/data?fileName=报告&pageNo=1&linesPerPage=20&orderByfield=LAST_MODIFY_DATE&orderMode=DESC&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（据源码当前实现返回 null，待服务层启用后返回真实分页数据）。

11. 文件重命名

修改指定文件的名称。文件不存在或新名称为空时抛 InvalidRequestException（HTTP 400）。

  • 接口类型：REST 资源
  • 请求方式：PATCH
  • 请求路径：/disks/{diskId}/files/{fileId}/rename（完整：{kms-context}/api/kms/disks/{diskId}/files/{fileId}/rename）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
fileId path string 是 文件Id
body body string(JSON) 是 JSON 字符串，含字段 name

请求体

{ "name": "新文件名.docx" }

请求示例

PATCH /api/kms/disks/__DISKID__/files/__FILEID__/rename?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "name": "新文件名.docx" }

响应

结构：统一 Resource。 data：重命名后的 FileEntity。

失败示例（参数有误）： 

{ "errcode": 400, "errmsg": "请求参数有误", "data": null, "errors": null }

12. 文件移动

将指定文件移动到目标文件夹。

  • 接口类型：REST 资源
  • 请求方式：PATCH
  • 请求路径：/disks/{diskId}/files/{fileId}/moveto/folderId/{destFolderId}（完整：{kms-context}/api/kms/disks/{diskId}/files/{fileId}/moveto/folderId/{destFolderId}）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
fileId path string 是 待移动文件Id
destFolderId path string 是 目标文件夹Id

请求示例

PATCH /api/kms/disks/__DISKID__/files/__FILEID__/moveto/folderId/__DESTFOLDERID__?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，true 表示移动成功。

13. 文件删除

将指定文件移入回收站（按当前用户标记软删除）。

  • 接口类型：REST 资源
  • 请求方式：DELETE
  • 请求路径：/disks/{diskId}/files/{fileId}（完整：{kms-context}/api/kms/disks/{diskId}/files/{fileId}）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
fileId path string 是 文件Id

请求示例

DELETE /api/kms/disks/__DISKID__/files/__FILEID__?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，true 表示删除成功。

14. 文件内部分享

将指定文件分享给平台内部若干用户。需当前用户对该文件拥有 CODE_SHARE 权限，否则抛 ForbiddenException（HTTP 403）。

  • 接口类型：REST 资源
  • 请求方式：POST
  • 请求路径：/disks/{diskId}/files/{fileId}/insideshare（完整：{kms-context}/api/kms/disks/{diskId}/files/{fileId}/insideshare）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
fileId path string 是 文件Id
body body array(string) 是 被分享用户Id数组
source query string 否 分享来源（无注解，Spring 默认按形参名绑定 query 参数）

请求体

["__USERID1__", "__USERID2__"]

请求示例

POST /api/kms/disks/__DISKID__/files/__FILEID__/insideshare?source=pc&accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

["__USERID1__", "__USERID2__"]

响应

结构：统一 Resource。 data：boolean，true 表示分享成功；当 userIds 为空数组时返回 false。

失败示例（权限不足）： 

{ "errcode": 403, "errmsg": "权限不足，分享文件失败", "data": null, "errors": null }

15. 别人分享给自己的文件列表

分页查询他人分享给当前用户的文件列表。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/sharefiles（完整：{kms-context}/api/kms/sharefiles）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
orderByfield query string 是 排序字段
orderMode query string 是 排序模式
pageNo query int 是 页码
linesPerPage query int 是 每页条数

请求示例

GET /api/kms/sharefiles?pageNo=1&linesPerPage=20&orderByfield=LAST_MODIFY_DATE&orderMode=DESC&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（由 dataBuilder.buildFileEntityReturnData 构造）。

16. 我的分享列表

分页查询当前用户分享给他人（内部）的所有文件。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/mysharefiles（完整：{kms-context}/api/kms/mysharefiles）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
orderByfield query string 否 排序字段
orderMode query string 否 排序模式
pageNo query int 是 页码
linesPerPage query int 是 每页条数

请求示例

GET /api/kms/mysharefiles?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（由 dataBuilder.buildFileEntityReturnData 构造）。

17. 我的外部分享列表

分页查询当前用户通过外部分享（生成分享码）分享的所有文件。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/myoutsidesharefiles（完整：{kms-context}/api/kms/myoutsidesharefiles）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
orderByfield query string 否 排序字段
orderMode query string 否 排序模式
pageNo query int 是 页码
linesPerPage query int 是 每页条数

请求示例

GET /api/kms/myoutsidesharefiles?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（直接返回服务层结果，未经 dataBuilder 包装）。

18. 添加文件到收藏

将指定文件加入当前用户的收藏。需对该文件拥有 CODE_FAVORITE 权限；重复收藏抛 InvalidRequestException（HTTP 400）。

  • 接口类型：REST 资源
  • 请求方式：POST
  • 请求路径：/files/{fileId}/favorites（完整：{kms-context}/api/kms/files/{fileId}/favorites）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileId path string 是 文件Id（若为引用类型，服务端会回溯到原始上传文件Id）

请求示例

POST /api/kms/files/__FILEID__/favorites?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，true 表示收藏成功。

失败示例（已收藏）： 

{ "errcode": 400, "errmsg": "文件已经收藏，无需重复收藏", "data": null, "errors": null }

19. 从收藏中移除文件

将指定文件从当前用户的收藏中取消。文件未收藏时抛 InvalidRequestException（HTTP 400）。

  • 接口类型：REST 资源
  • 请求方式：DELETE
  • 请求路径：/files/{fileId}/favorites（完整：{kms-context}/api/kms/files/{fileId}/favorites）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileId path string 是 文件Id

请求示例

DELETE /api/kms/files/__FILEID__/favorites?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，true 表示取消收藏成功。

20. 获取收藏文件列表

分页查询当前用户收藏的文件列表。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/favoritefiles（完整：{kms-context}/api/kms/favoritefiles）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
orderByfield query string 否 排序字段
orderMode query string 否 排序模式
pageNo query int 是 页码
linesPerPage query int 是 每页条数

请求示例

GET /api/kms/favoritefiles?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（由 dataBuilder.buildFileEntityReturnData 构造）。

21. 文件预览

对指定文件进行预览（服务端转 PDF 并按配置叠加预览水印）。对图片类型文件，服务端生成含水印的图片地址。预览前会向预览记录表插入一条当前用户的预览记录。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/disks/{diskId}/files/{fileId}/preview（完整：{kms-context}/api/kms/disks/{diskId}/files/{fileId}/preview）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
fileId path string 是 文件Id

请求示例

GET /api/kms/disks/__DISKID__/files/__FILEID__/preview?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：String（JSON 序列化结果），包含 fileEntity（文件实体，含 operations 当前用户操作权限）、pdfFileUrl/url（预览地址，图片类型为水印图地址）。

22. 手机端预览（含水印）

移动端文件预览。按当前用户名与配置生成预览水印，返回预览路径。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/mobile/disks/{diskId}/files/{fileId}/preview（完整：{kms-context}/api/kms/mobile/disks/{diskId}/files/{fileId}/preview）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
fileId path string 是 文件Id

请求示例

GET /api/kms/mobile/disks/__DISKID__/files/__FILEID__/preview?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：String，移动端预览路径。

23. 文件外部分享

对指定文件生成外部分享记录，返回分享码与分享Id。提取码 code 缺省时由服务端随机生成。

  • 接口类型：REST 资源
  • 请求方式：POST
  • 请求路径：/files/{fileId}/outsideshare（完整：{kms-context}/api/kms/files/{fileId}/outsideshare）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileId path string 是 文件Id
body body object 是 JSON 对象，含 code（提取码）、duration（有效期截止时间戳，毫秒）

请求体

{ "code": "abcd", "duration": "1735689600000" }

请求示例

POST /api/kms/files/__FILEID__/outsideshare?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "code": "abcd", "duration": "1735689600000" }

响应

结构：统一 Resource。 data：JSONObject，结构 { "code": "<提取码>", "id": "<分享Id>" }。

24. FileObjs 批量移动

将一组文件/文件夹批量移动到目标文件夹。请求体为 JSON 数组字符串，每项含 fileObjectId 与 isFolder。

  • 接口类型：REST 资源
  • 请求方式：PATCH
  • 请求路径：/disks/{diskId}/fileObjs/moveto/folders/{folderId}（完整：{kms-context}/api/kms/disks/{diskId}/fileObjs/moveto/folders/{folderId}）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
folderId path string 是 目标文件夹Id
body body string(JSON) 是 JSON 数组字符串，见下方请求体

请求体

[
  { "fileObjectId": "__FILEID1__", "isFolder": false },
  { "fileObjectId": "__FOLDERID1__", "isFolder": true }
]

请求示例

PATCH /api/kms/disks/__DISKID__/fileObjs/moveto/folders/__FOLDERID__?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

[ { "fileObjectId": "__FILEID1__", "isFolder": false } ]

响应

结构：统一 Resource。 data：boolean，true 表示批量移动成功。

25. FileObjs 批量删除

将一组文件/文件夹批量移入回收站（软删除）。请求体为 JSON 数组字符串，每项含 fileObjectId 与 isFolder。

  • 接口类型：REST 资源
  • 请求方式：DELETE
  • 请求路径：/disks/{diskId}/fileObjs（完整：{kms-context}/api/kms/disks/{diskId}/fileObjs）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
body body string(JSON) 是 JSON 数组字符串（结构同 #24）

请求示例

DELETE /api/kms/disks/__DISKID__/fileObjs?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

[ { "fileObjectId": "__FILEID1__", "isFolder": false } ]

响应

结构：统一 Resource。 data：boolean，true 表示批量删除成功。

26. 根据所属 id 和文件名查找文件

按文件夹归属 Id 与文件名分页查找文件（按 LAST_MODIFY_DATE DESC 固定排序）。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/disks/files（完整：{kms-context}/api/kms/disks/files）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
ownerId query string 是 文件夹归属Id
fileName query string 是 文件名关键字
pageNo query string 是 页码（字符串型数字）
linesPerPage query string 是 每页条数（字符串型数字）

请求示例

GET /api/kms/disks/files?ownerId=__FOLDERID__&fileName=报告&pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileObject>（直接返回服务层结果）。

27. 网盘的预览与下载次数

根据网盘 Id 统计该网盘下文件的预览次数与下载次数。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/disks/{diskId}/files/viewsAndDownloads（完整：{kms-context}/api/kms/disks/{diskId}/files/viewsAndDownloads）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id

请求示例

GET /api/kms/disks/__DISKID__/files/viewsAndDownloads?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：Map<String, Object>，含预览次数、下载次数等统计指标。

28. 给文件贴标签（批量，旧接口）

为多个文件批量贴标签。fileIds、categorys 均为逗号分隔字符串。若 fileIds 中包含文件夹 Id，返回 InvalidRequestException（HTTP 400）。

  • 接口类型：REST 资源
  • 请求方式：PUT
  • 请求路径：/files/categorys（完整：{kms-context}/api/kms/files/categorys）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileIds query string 是 文件Id逗号分隔串（不可含文件夹Id）
categorys query string 是 标签名逗号分隔串（允许空串）

请求示例

PUT /api/kms/files/categorys?fileIds=__F1__,__F2__&categorys=标签1,标签2&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：String，成功为空串 ""。

失败示例（含文件夹）： 

{ "errcode": 400, "errmsg": "请不要选择文件夹，文件夹不能贴标签", "data": null, "errors": null }

29. 按标签/用户/时间分页查询文件

按标签名、贡献者、时间范围分页查询文件（综合查询）。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/files（完整：{kms-context}/api/kms/files）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
categoryName query string 否 标签名（调用方需自行 trim）
userIds query array(string) 否 贡献者用户Id列表
beginTime query string 否 起始时间戳（毫秒，字符串型）
endTime query string 否 截止时间戳（毫秒，字符串型）
linesPerPage query string 是 每页条数（字符串型数字）
pageNo query string 是 页码（字符串型数字）

请求示例

GET /api/kms/files?categoryName=报告&linesPerPage=20&pageNo=1&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileEntity>（按 categoryName.trim() + userIds + 时间范围查询的结果）。

失败示例（分页参数缺失）： 

{ "errcode": 400, "errmsg": "每页显示的条数为空或者现在页数为空", "data": null, "errors": null }

30. 根据文件 id 获取标签

返回指定文件已贴的标签名列表。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/files/{id}/categorys（完整：{kms-context}/api/kms/files/{id}/categorys）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
id path string 是 文件Id

请求示例

GET /api/kms/files/__FILEID__/categorys?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<String>，标签名数组（文件无标签时为空数组）。

31. 根据文件 id 获取所在文件夹名称

返回指定文件所属文件夹的名称。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/files/{id}/folder/name（完整：{kms-context}/api/kms/files/{id}/folder/name）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
id path string 是 文件Id

请求示例

GET /api/kms/files/__FILEID__/folder/name?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：String，所在文件夹名称。

32. 获取编辑器所需参数（新建空文件）

在指定网盘/文件夹下创建一个空文件，返回在线编辑器所需的预览地址、相对路径、showName、用户名等参数，并更新最后编辑时间与编辑记录表。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/getneedparam（完整：{kms-context}/api/kms/getneedparam）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId query string 是 网盘Id
folderId query string 是 文件夹Id

请求示例

GET /api/kms/getneedparam?diskId=__DISKID__&folderId=__FOLDERID__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：JSONObject，结构 { "showName": "<显示名>", "username": "<用户名>", "id": "<文件Id>", "path": "<完整编辑地址>", "relativePath": "<相对路径>" }。

33. 获取编辑器所需参数（已有文件）

按指定文件 Id 加载已有文件，返回在线编辑器所需的预览地址、相对路径、showName、用户名、folderId 等参数，并更新最后编辑时间与编辑记录表。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/getneedparam2（完整：{kms-context}/api/kms/getneedparam2）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
id query string 是 文件Id

请求示例

GET /api/kms/getneedparam2?id=__FILEID__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：JSONObject，结构 { "folderId": "<文件夹Id>", "showName": "<显示名>", "username": "<用户名>", "id": "<文件Id>", "path": "<完整编辑地址>", "relativePath": "<相对路径>" }。

34. 记录文件编辑时间

更新指定文件的最后编辑时间，并向编辑记录表插入一条当前用户、当前时间的编辑记录。

  • 接口类型：REST 资源
  • 请求方式：POST
  • 请求路径：/edit/time（完整：{kms-context}/api/kms/edit/time）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileId query string 是 文件Id

请求示例

POST /api/kms/edit/time?fileId=__FILEID__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：String，回传的文件Id。

35. 创建空文档

在指定网盘/文件夹下创建一个具名空文档，返回新建文件实体。

  • 接口类型：REST 资源
  • 请求方式：POST
  • 请求路径：/disks/{diskId}/folders/{folderId}（完整：{kms-context}/api/kms/disks/{diskId}/folders/{folderId}）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
diskId path string 是 网盘Id
folderId path string 是 文件夹Id
fileName query string 是 新建文件名

请求示例

POST /api/kms/disks/__DISKID__/folders/__FOLDERID__?fileName=新建文档.docx&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：新建的 FileEntity。

36. 获取模板文件列表

列出系统模板目录下的全部模板文件名（按扩展名排序）。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/files/template（完整：{kms-context}/api/kms/files/template）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

无。

请求示例

GET /api/kms/files/template?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<String>，模板文件名数组。

37. 创建归档文件

按上传归档信息创建一条归档文件记录。

  • 接口类型：REST 资源
  • 请求方式：POST
  • 请求路径：/archive/file（完整：{kms-context}/api/kms/archive/file）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
id query string 是 归档文件Id
diskId query string 是 网盘Id
fileName query string 是 文件名
longSize query long 是 文件大小（字节）
folderId query string 是 所属文件夹Id

请求示例

POST /api/kms/archive/file?id=__ID__&diskId=__DISKID__&fileName=报告.docx&longSize=1024&folderId=__FOLDERID__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，true 表示创建成功。

38. 获取文件的自动标签集合

根据文件 Id 与当前用户企业域，返回该文件的自动推荐标签集合。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/files/{fileId}/auto/categorys（完整：{kms-context}/api/kms/files/{fileId}/auto/categorys）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileId path string 是 文件Id

请求示例

GET /api/kms/files/__FILEID__/auto/categorys?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：Map，自动推荐标签集合。

39. 通过文件校验码查询文件

根据文件校验码（checksum）查询所有匹配的文件信息列表。校验码为空时抛 InvalidRequestException（HTTP 400）。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/files/{fileChecksum}（完整：{kms-context}/api/kms/files/{fileChecksum}）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileChecksum path string 是 文件校验码

请求示例

GET /api/kms/files/__CHECKSUM__?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<Map<String, Object>>，每项含 id/name/type/size/checksum/creator/creatorId/createDate/lastModifyDate/url/folderId/diskId/categorys 字段。

40. 单个文件贴标签（新接口）

为单个文件贴标签（覆盖原标签）。请求体含 fileId 与标签数组（每项含 categoryName、categoryId）；标签数组为空时清空该文件全部标签。

  • 接口类型：REST 资源
  • 请求方式：PUT
  • 请求路径：/file/categorys/paste（完整：{kms-context}/api/kms/file/categorys/paste）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
body body object 是 JSON 对象，见下方请求体

请求体

{
  "fileId": "__FILEID__",
  "categorys": [
    { "categoryName": "标签1", "categoryId": "__CATID1__" },
    { "categoryName": "标签2", "categoryId": "__CATID2__" }
  ]
}

请求示例

PUT /api/kms/file/categorys/paste?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "fileId": "__FILEID__", "categorys": [ { "categoryName": "标签1", "categoryId": "__CATID1__" } ] }

响应

结构：统一 Resource。 data：更新后的 FileEntity。

41. 多个文件贴标签（新接口）

为多个文件追加标签（去重）。请求体为数组，每项含 fileId 与 categorys；对每个文件已有的标签做去重后追加，不动旧标签。

  • 接口类型：REST 资源
  • 请求方式：PUT
  • 请求路径：/files/categorys/paste（完整：{kms-context}/api/kms/files/categorys/paste）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
body body array(object) 是 JSON 数组，见下方请求体

请求体

[
  {
    "fileId": "__FILEID1__",
    "categorys": [ { "categoryName": "标签1", "categoryId": "__CATID1__" } ]
  },
  {
    "fileId": "__FILEID2__",
    "categorys": [ { "categoryName": "标签2", "categoryId": "__CATID2__" } ]
  }
]

请求示例

PUT /api/kms/files/categorys/paste?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

[ { "fileId": "__FILEID1__", "categorys": [ { "categoryName": "标签1", "categoryId": "__CATID1__" } ] } ]

响应

结构：统一 Resource。 data：回传请求体（List<JSONObject>）。

42. 获取用户的文件上传数量

按当前用户 Id（与文件来源类型）统计其上传文件数量。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/files/userUploadFileCount（完整：{kms-context}/api/kms/files/userUploadFileCount）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
originType query int 否 文件来源类型（不传则统计全部来源）

请求示例

GET /api/kms/files/userUploadFileCount?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：Integer，文件上传数量。

43. 删除文件单个标签

从指定文件移除单个标签（同步更新文件 categorys 字段、categorysJson 与文件标签中间表）。

  • 接口类型：REST 资源
  • 请求方式：DELETE
  • 请求路径：/files/deleteFileCategory（完整：{kms-context}/api/kms/files/deleteFileCategory）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：kms文件模块

请求参数

参数名 位置 类型 必填 说明
fileId query string 是 文件Id
categoryName query string 是 待删除标签名

请求示例

DELETE /api/kms/files/deleteFileCategory?fileId=__FILEID__&categoryName=标签1&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：更新后的 FileEntity。

失败示例（内部异常，据源码 catch 显式返回）： 

{ "errcode": 500, "errmsg": "<异常消息>", "data": null, "errors": null }