创建文件夹
2026-09-08 19:29
| 接口名 | POST: /dms/project/space/uploadOss | |||
| 入参:(body传值) | application/json | |||
| 是否必传 | 默认值 | 描述 | 备注 | |
| pfolderId | 否 | “0” | 所属文件夹ID "0"代表根目录 |
所属文件夹ID 为空时默认是"0" |
| name | 是 | - | 文件夹名 | 不超过50个字符 不能包含下列任何字符:\ / : * ? " < > | |
| fileScope | 是 | - | 文件归属域 | 我的空间->personal 项目空间(企业空间)->project |
| projectCode | 否 | - | 该项目在外部平台的唯一编码,需提前创建项目 | fileScope 为 project 时需要 传递 |
| 入参:(Header传值) | ||||
| Authorization | 是 | - | 传递AccessToken | 格式:Bearer {AccessToken} |
| 入参示例:(application/json) | ||||
|
{
"pfolderId": "",
"name": "testfolder",
"fileScope":"project",
"projectCode":"proj_openapi_001"
}
|
||||
| 回参示例:(application/json) | ||||
|
{
"code": 0,
"msg": null,
"data": {
"folderId": "7da327f74exxxx18d4ff661ac3e2830"
},
"ok": true
}
|
||||
package com.hoteam.sview.demo;
import cn.hutool.core.util.StrUtil;
import cn.hutool.http.ContentType;
import cn.hutool.http.Header;
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.http.HttpStatus;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;
import lombok.extern.slf4j.Slf4j;
import java.util.HashMap;
import java.util.Map;
/**
* 创建文件夹Demo
* 接口:POST /login-register/open-api/documents/folder
* <p>
* 成功判定:HTTP 200 且 code=0,返回data中包含folderId
* 失败:HTTP 401 / 非2xx / code!=0 / 网络异常,返回 null
*/
@Slf4j
public class CreateFolderHutoolDemo {
/** 接口地址(按实际环境替换 host) */
private static final String CREATE_FOLDER_URL =
"http://your-host/login-register/open-api/documents/folder";
/** AccessToken(按实际值替换,可通过 /auth/oauth2/token 接口预先获取) */
private static final String ACCESS_TOKEN = "your_access_token";
public static void main(String[] args) {
// 调用创建文件夹接口
JSONObject result = createFolder(
"0", // pfolderId 父文件夹ID,0代表根目录,非必传,不传默认"0"
"testfolder", // name 文件夹名称,必填
"project", // fileScope 文件归属域:personal / project,必填
"proj_openapi_001" // projectCode,fileScope=project时必填
);
if (result == null) {
log.warn("创建文件夹失败");
return;
}
log.info("创建文件夹成功,返回data:{}", result);
String folderId = result.getStr("folderId");
log.info("文件夹ID:{}", folderId);
}
/**
* 创建文件夹
*
* @param pfolderId 父文件夹ID,"0"代表根目录;允许null/空,默认"0"
* @param name 文件夹名称(必填,不能包含 \ / : * ? " < > |,最大50字符)
* @param fileScope 文件归属域:personal(我的空间) / project(项目空间)(必填)
* @param projectCode 外部平台项目唯一编码,fileScope=project时必填;fileScope=personal传null
* @return 成功返回data节点JSONObject(folderId);失败返回 null
*/
public static JSONObject createFolder(String pfolderId,
String name,
String fileScope,
String projectCode) {
// 1. 参数校验
if (StrUtil.isBlank(name) || StrUtil.isBlank(fileScope)) {
log.warn("创建文件夹必填参数缺失:name={}, fileScope={}", name, fileScope);
return null;
}
if ("project".equals(fileScope) && StrUtil.isBlank(projectCode)) {
log.warn("fileScope为project时,projectCode不能为空");
return null;
}
// pfolderId为空则赋值默认根目录"0"
if (StrUtil.isBlank(pfolderId)) {
pfolderId = "0";
}
// 2. 组装请求体
Map<String, Object> requestMap = new HashMap<>();
requestMap.put("pfolderId", pfolderId);
requestMap.put("name", name);
requestMap.put("fileScope", fileScope);
requestMap.put("projectCode", projectCode);
String requestBody = JSONUtil.toJsonStr(requestMap);
log.info("创建文件夹请求报文:{}", requestBody);
// 3. 发起请求
try (HttpResponse response = HttpRequest.post(CREATE_FOLDER_URL)
// 公共 Header,和分享链接demo保持一致
.header("tenant-id", "1")
.header("deviceId", "web")
.header("deviceModel", "web")
.header("deviceType", "4")
.header("lang", "zh-CN")
// 认证 + Content‑Type
.header(Header.AUTHORIZATION, "Bearer " + ACCESS_TOKEN)
.header(Header.CONTENT_TYPE, ContentType.JSON.getValue())
.body(requestBody)
.timeout(10_000)
.execute()) {
int status = response.getStatus();
String body = response.body();
log.info("创建文件夹响应:status={}, body={}", status, body);
// 3.1 401 认证失败
if (status == HttpStatus.HTTP_UNAUTHORIZED) {
log.warn("创建文件夹认证失败(401),accessToken 可能失效,body={}", body);
return null;
}
// 3.2 非2xx 或响应体为空
if (!response.isOk() || StrUtil.isBlank(body)) {
log.warn("创建文件夹请求失败:status={}, body={}", status, body);
return null;
}
// 4. 业务字段判定:仅以 code=0 为成功
JSONObject json = JSONUtil.parseObj(body);
Integer code = json.getInt("code");
if (code == null || code != 0) {
log.warn("创建文件夹业务失败:code={}, msg={}", code, json.getStr("msg"));
return null;
}
// 返回data节点,包含folderId
return json.getJSONObject("data");
} catch (Exception e) {
log.error("调用创建文件夹接口异常", e);
return null;
}
}
}

全部评论