智能媒资托管文件管理

前期准备
开始操作前，确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK，请先参考快速入门文档完成。
如果媒体库启用回收站功能，删除文件时会移入回收站而非永久删除
符号链接所指向的文件不会因为重命名或移动而丢失指向
虚拟文件不对应实际的 COS 对象存储，仅保存元数据信息，可用于占位或记录外部资源引用
文件信息
获取文件信息
infoFile 用于获取文件下载链接和信息。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
文件路径，使用斜杠(/)分隔，例如 foo/bar/file.txt
info
BigDecimal
是
固定值 1，表示获取文件下载链接和信息
historyId
String
否
历史版本 ID，不传默认为最新版
contentDisposition
String
否
用于设置 Content-Disposition 响应头，支持 inline 或 attachment
purpose
String
否
用途，可设置为 download 或 preview
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
trafficLimit
Long
否
单链接下载限速，范围 100KB/s-100MB/s，单位 B
preCheck
BigDecimal
否
是否只用于校验文件是否可预览和下载
contentCas
String
否
文件内容的 Cas 标识
withContentCas
Integer
否
0 或 1，是否返回文件内容的 Cas 标识
withShortLink
Integer
否
0 或 1，设置为 1 时返回的 cosUrl 将被替换为短链形式
period
Integer
否
链接有效期（秒），取值范围 [60, 7200]，默认 7200
preview
Integer
否
0 或 1，是否返回预览链接
withFavoriteStatus
Integer
否
0 或 1，是否返回收藏状态
返回值说明
HTTP 状态码：200
字段
说明
类型
cosUrl
带签名的下载链接，签名有效时长约 2 小时
String
type
文件类型
String
creationTime
文件首次完成上传的时间
OffsetDateTime
modificationTime
文件最近一次被覆盖的时间
OffsetDateTime
contentType
媒体类型
String
size
文件大小，字符串格式以避免精度问题
String
eTag
文件 ETag
String
crc64
文件的 CRC64-ECMA182 校验值
String
fileType
文件类型：excel、powerpoint 等
String
previewByDoc
是否可通过 wps 预览
Boolean
previewByCI
是否可通过万象预览
Boolean
previewAsIcon
是否可用预览图作为 icon
Boolean
versionId
文件版本号
Integer
metaData
文件元数据键值对
Map<String, String>
labels
文件简易标签
List<String>
category
文件自定义分类
String
localCreationTime
文件本地创建时间
OffsetDateTime
localModificationTime
文件本地修改时间
OffsetDateTime
contentCas
文件内容的 Cas 标识（withContentCas=1 时返回）
String
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.InfoFile200Response;
import java.math.BigDecimal;
﻿
try {
    FileApi.APIInfoFileRequest request = FileApi.APIInfoFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/report.pdf")
        .info(BigDecimal.ONE)
        .purpose("download")
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().infoFileWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
    System.out.println("Status code: " + statusCode);
﻿
    if (statusCode == 200) {
        InfoFile200Response result = (InfoFile200Response) apiResponse.getData();
        System.out.println("Download URL: " + result.getCosUrl());
        System.out.println("File size: " + result.getSize() + " bytes");
        System.out.println("File type: " + result.getFileType());
        System.out.println("Creation time: " + result.getCreationTime());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
获取照片/视频封面缩略图
getCover 用于获取照片/视频封面缩略图。视频封面使用该视频的首帧图片；针对照片或视频封面，优先使用人脸识别智能缩放裁剪为指定大小，如果未识别到人脸则居中缩放裁剪。如果文件不属于可预览的媒体类型，则会跳转至文件的下载链接。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
文件路径
preview
BigDecimal
是
预览标识，固定值为 1
size
Integer
否
缩放大小（优先使用人脸识别智能裁剪为 size×size）
scale
Integer
否
等比例缩放百分比（1-100），当未传 size 时生效
widthSize
Integer
否
缩放宽度，当未传 size 和 scale 时生效
heightSize
Integer
否
缩放高度，当未传 size 和 scale 时生效
frameNumber
Integer
否
帧数，针对 gif 的降帧处理
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
返回值说明
服务端通过 HTTP 302 Location 跳转到真实的封面图片 URL。默认情况下 SDK 自动跟随重定向（followRedirects=NORMAL），响应体为封面图片内容。如需获取 Location 中的 URL 而非跟随跳转，请先调用 client.setFollowRedirects(HttpClient.Redirect.NEVER)，再从 ApiException 的响应头中读取（302 按非 2xx 抛出）。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
﻿
import java.math.BigDecimal;
﻿
try {
    FileApi.APIGetCoverRequest request = FileApi.APIGetCoverRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/photos/landscape.jpg")
        .preview(new BigDecimal("1"))
        .size(200)
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().getCoverWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
获取文档预览
previewFile 用于获取 HTML 格式文档预览。返回 HTML 或 JPG 格式的文档用于预览；如果文件不属于可预览的文档类型，则会跳转至文件的下载链接。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
文件路径
preview
BigDecimal
是
文档预览标识，固定值为 1
historyId
String
否
历史版本 ID
type
String
否
文档预览方式，pic 以 jpg 格式预览文档首页，否则以 html 格式预览，默认 html
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
返回值说明
获取成功，返回 HTTP 302 Found，响应头 Location 包含可直接用于展示或下载的文件 URL。默认情况下 SDK 自动跟随重定向，响应体为预览内容（HTML 或 JPG）。如需获取 Location 中的 URL 而非跟随跳转，请先调用 client.setFollowRedirects(HttpClient.Redirect.NEVER)，再从 ApiException 的响应头中读取（302 按非 2xx 抛出）。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
﻿
import java.math.BigDecimal;
﻿
try {
    FileApi.APIPreviewFileRequest request = FileApi.APIPreviewFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/report.docx")
        .preview(new BigDecimal("1"))
        .type("html")
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().previewFileWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
检查文件状态
checkFileStatus 用于检查指定文件路径的状态。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
文件路径
historyId
String
否
历史版本 ID，不传默认为最新版
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
返回值说明
HTTP 状态码：200（文件存在且可访问）或 204（无响应体）。非 2xx 状态码通过 ApiException 抛出。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
﻿
try {
    FileApi.APICheckFileStatusRequest request = FileApi.APICheckFileStatusRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/report.pdf")
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().checkFileStatusWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
    System.out.println("Status code: " + statusCode);
    if (statusCode == 200 || statusCode == 204) {
        System.out.println("File exists and is accessible");
    }
} catch (ApiException e) {
    System.err.println("File status check failed: " + e.getCode() + " - " + e.getMessage());
}
根据 inode 获取文件信息
getFileInfoByInode 用于通过 inode 获取文件详细信息。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
inode
String
是
文件 ID
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
withContentCas
Integer
否
0 或 1，是否返回文件内容的 Cas 标识
返回值说明
HTTP 状态码：200
字段
说明
类型
path
文件目录路径
List<String>
name
文件目录名称
String
type
文件目录类型：dir 或 file
String
creationTime
文件目录创建时间
OffsetDateTime
modificationTime
文件最近一次被覆盖的时间
OffsetDateTime
contentType
媒体类型（仅文件返回）
String
size
文件大小（仅文件返回）
String
crc64
文件的 CRC64-ECMA182 校验值（仅文件返回）
String
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.GetFileInfoByInode200Response;
﻿
try {
    FileApi.APIGetFileInfoByInodeRequest request = FileApi.APIGetFileInfoByInodeRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .inode("file-inode-id")
        .accessToken("your-access-token")
        .withContentCas(1)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().getFileInfoByInodeWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
    System.out.println("Status code: " + statusCode);
﻿
    if (statusCode == 200) {
        GetFileInfoByInode200Response result = (GetFileInfoByInode200Response) apiResponse.getData();
        System.out.println("File name: " + result.getName());
        System.out.println("File type: " + result.getType());
        System.out.println("File path: " + result.getPath());
        System.out.println("Creation time: " + result.getCreationTime());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
文件管理
复制文件
copyFile 用于复制文件到新位置。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
目标文件路径
conflictResolutionStrategy
String
否
文件名冲突时的处理方式，默认为 rename
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
CopyFileRequest 字段说明
字段
类型
必填
说明
copyFrom
String
是
被复制的源文件路径
返回值说明
HTTP 状态码：200
字段
说明
类型
path
文件路径，null 表示父级目录已被删除
List<String>
contentCas
文件内容的 Cas 标识
String
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.CopyFileRequest;
import com.tencent.cloud.smh.model.CopyFile200Response;
﻿
CopyFileRequest copyBody = new CopyFileRequest();
copyBody.setCopyFrom("/documents/report.pdf");
﻿
try {
    FileApi.APICopyFileRequest request = FileApi.APICopyFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/backup/report-copy.pdf")
        .conflictResolutionStrategy("rename")
        .accessToken("your-access-token")
        .copyFileRequest(copyBody)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().copyFileWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
    System.out.println("Status code: " + statusCode);
﻿
    if (statusCode == 200) {
        CopyFile200Response result = (CopyFile200Response) apiResponse.getData();
        System.out.println("File copied, path: " + result.getPath());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
重命名或移动文件
moveFile 用于重命名或移动文件。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
目标文件路径
conflictResolutionStrategy
String
否
文件名冲突时的处理方式，默认为 rename
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
MoveFileRequest 字段说明
字段
类型
必填
说明
from
String
是
被重命名或移动的源文件路径
返回值说明
HTTP 状态码：200
字段
说明
类型
path
文件路径，null 表示父级目录已被删除
List<String>
contentCas
文件内容的 Cas 标识
String
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.MoveFileRequest;
import com.tencent.cloud.smh.model.MoveFile200Response;
﻿
MoveFileRequest moveBody = new MoveFileRequest();
moveBody.setFrom("/documents/report.pdf");
﻿
try {
    FileApi.APIMoveFileRequest request = FileApi.APIMoveFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/archived/report.pdf")
        .conflictResolutionStrategy("rename")
        .accessToken("your-access-token")
        .moveFileRequest(moveBody)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().moveFileWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
    System.out.println("Status code: " + statusCode);
﻿
    if (statusCode == 200) {
        MoveFile200Response result = (MoveFile200Response) apiResponse.getData();
        System.out.println("File moved, new path: " + result.getPath());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
删除文件
deleteFile 用于删除文件。当回收站功能开启且 permanent=0 时，文件移入回收站；否则文件被直接永久删除。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
文件路径
permanent
Integer
否
1: 永久删除，0: 移入回收站，默认为 0
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
contentCas
String
否
文件内容的 Cas 标识
返回值说明
该接口返回多种 2xx 状态码：
HTTP 状态码
说明
200
文件移入回收站，响应体包含 recycledItemId
204
文件被永久删除（无响应体）
200 响应字段说明
字段
说明
类型
recycledItemId
回收站项目 ID
Long
使用示例
删除文件到回收站
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.DeleteFile200Response;
﻿
try {
    FileApi.APIDeleteFileRequest request = FileApi.APIDeleteFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/old-report.pdf")
        .permanent(0)
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().deleteFileWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        DeleteFile200Response result = (DeleteFile200Response) apiResponse.getData();
        System.out.println("File moved to recycle bin, item ID: " + result.getRecycledItemId());
    } else if (statusCode == 204) {
        System.out.println("File permanently deleted");
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
永久删除文件
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
﻿
try {
    FileApi.APIDeleteFileRequest request = FileApi.APIDeleteFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/temp/unwanted-file.txt")
        .permanent(1)
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().deleteFileWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
    System.out.println("File permanently deleted");
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
创建符号链接
createSymlink 用于创建符号链接。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
符号链接路径
conflictResolutionStrategy
String
否
文件名冲突时的处理方式，默认为 rename
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
createSymlinkRequest
CreateSymlinkRequest
是
请求体，包含 linkTo 字段
CreateSymlinkRequest 字段说明
字段
类型
必填
说明
linkTo
String
是
符号链接指向的源文件绝对路径
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.CreateSymlinkRequest;
import com.tencent.cloud.smh.model.CreateSymlink200Response;
﻿
CreateSymlinkRequest symlinkBody = new CreateSymlinkRequest();
symlinkBody.setLinkTo("/documents/report.pdf");
﻿
try {
    FileApi.APICreateSymlinkRequest request = FileApi.APICreateSymlinkRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/shortcuts/document-link")
        .conflictResolutionStrategy("rename")
        .accessToken("your-access-token")
        .createSymlinkRequest(symlinkBody)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().createSymlinkWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        CreateSymlink200Response result = (CreateSymlink200Response) apiResponse.getData();
        System.out.println("Symlink created: " + result.getPath());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
文档转码
convertFile 用于文档转码。当前仅支持 doc/docx 转 pdf。路径参数 filePath 为转码输出的目标文件路径，请求体 convertFrom 为源文件路径；源与目标均需要指定完整的文件路径，可以跨越目录，且支持同时修改文件名；不会自动创建中间所需的各级父目录，所以必须保证路径的各级目录存在。
要求权限：
非 acl 鉴权：admin、space_admin
acl 鉴权：canDownload（当前文件夹可下载）& canUpload（目标文件夹可上传）
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
目标文件路径（转码输出）
convert
BigDecimal
是
文档转码操作标识，固定值为 1
convertFileRequest
ConvertFileRequest
是
请求体，包含目标路径等字段
conflictResolutionStrategy
String
否
冲突处理：ask / rename / overwrite，默认 rename
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
ConvertFileRequest 字段说明
字段
类型
必填
说明
convertFrom
String
是
指定文档转码要操作的源文件完整路径
返回值说明
HTTP 状态码：202（异步转码任务已接收）
字段
说明
类型
taskId
转码任务 ID，可用于查询任务状态
Integer
path
转码输出文件路径
List<String>
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.ConvertFileRequest;
import com.tencent.cloud.smh.model.ConvertFile202Response;
﻿
import java.math.BigDecimal;
﻿
ConvertFileRequest convertBody = new ConvertFileRequest();
convertBody.setConvertFrom("/documents/report.docx");
﻿
try {
    FileApi.APIConvertFileRequest request = FileApi.APIConvertFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/report.pdf")
        .convert(new BigDecimal("1"))
        .convertFileRequest(convertBody)
        .conflictResolutionStrategy("rename")
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().convertFileWithHttpInfo(request);
    if (apiResponse.getStatusCode() == 202) {
        ConvertFile202Response result = (ConvertFile202Response) apiResponse.getData();
        System.out.println("Convert task submitted, task ID: " + result.getTaskId());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
获取最近使用文件
listRecentlyUsedFile 用于查看最近使用文件列表。仅文件预览及文件编辑操作会被记录到最近使用文件列表中。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
ListRecentlyUsedFileRequest 字段说明
字段
类型
必填
说明
marker
String
否
分页标识
limit
Integer
否
分页大小，默认 20
filterActionBy
String
否
筛选操作方式：preview / modify
type
List<String> 或 String
否
筛选文件类型，可传字符串数组（如 [".doc",".csv"]），也可传单个字符串枚举：all/document/pdf/powerpoint/excel/word/text/doc/xls/ppt
withPath
Boolean
否
是否返回文件路径
返回值说明
HTTP 状态码：200
字段
说明
类型
nextMarker
分页标识
String
contents
最近使用文件列表
List<ListRecentlyUsedFile200ResponseContentsInner>
contents 字段说明
字段
说明
类型
name
文件名
String
spaceId
空间 ID
String
inode
文件 ID
String
size
文件大小
String
actionType
操作类型
String
operationTime
操作时间
String
creationTime
文件上传时间
String
crc64
CRC64 校验值
String
path
文件路径
List<String>
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecentApi;
import com.tencent.cloud.smh.model.ListRecentlyUsedFileRequest;
import com.tencent.cloud.smh.model.ListRecentlyUsedFile200Response;
﻿
ListRecentlyUsedFileRequest recentBody = new ListRecentlyUsedFileRequest();
recentBody.setLimit(20);
recentBody.setFilterActionBy(ListRecentlyUsedFileRequest.FilterActionByEnum.PREVIEW);
recentBody.setWithPath(true);
﻿
try {
    RecentApi.APIListRecentlyUsedFileRequest request = RecentApi.APIListRecentlyUsedFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .listRecentlyUsedFileRequest(recentBody)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recent().listRecentlyUsedFileWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        ListRecentlyUsedFile200Response result = (ListRecentlyUsedFile200Response) apiResponse.getData();
        for (var item : result.getContents()) {
            System.out.println("Name: " + item.getName());
            System.out.println("Action type: " + item.getActionType());
            System.out.println("Operation time: " + item.getOperationTime());
        }
﻿
        if (result.getNextMarker() != null) {
            System.out.println("More data available");
        }
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
操作类型筛选
preview：只返回预览操作的文件
modify：只返回编辑操作的文件
不设置此参数：返回所有操作类型的文件
创建虚拟文件
createVirtualFile 用于创建虚拟文件。虚拟文件不含实际内容，可用于创建链接、占位符等场景，支持设置 contentType、metaData、labels、category、size。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
文件路径
virtualFile
Integer
是
固定标识，表示创建虚拟文件，固定值为 1
conflictResolutionStrategy
String
否
文件名冲突时的处理方式：ask / rename / overwrite，默认 rename
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
createVirtualFileRequest
CreateVirtualFileRequest
否
请求体
CreateVirtualFileRequest 字段说明
字段
类型
必填
说明
contentType
String
否
虚拟文件的媒体类型
metaData
Map<String,String>
否
自定义元数据键值对，key 为小写字符串
labels
List<String>
否
文件标签列表
category
String
否
文件自定义分类，最大长度 16 字节
size
String
否
虚拟文件大小（字节），默认为 "0"，非零值会占用空间配额
返回值说明
HTTP 状态码：200
字段
说明
类型
path
文件路径
List<String>
type
文件类型
String
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.CreateVirtualFileRequest;
import com.tencent.cloud.smh.model.CreateVirtualFile200Response;
﻿
import java.util.HashMap;
import java.util.List;
import java.util.Map;
﻿
CreateVirtualFileRequest virtualBody = new CreateVirtualFileRequest();
virtualBody.setContentType("application/x-virtual-link");
virtualBody.setCategory("document");
virtualBody.setLabels(List.of("meeting", "notes"));
Map<String, String> metaData = new HashMap<>();
metaData.put("source", "meeting-app");
metaData.put("url", "https://example.com/meeting/123");
virtualBody.setMetaData(metaData);
﻿
try {
    FileApi.APICreateVirtualFileRequest request = FileApi.APICreateVirtualFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/virtual/meeting-notes.link")
        .virtualFile(1)
        .conflictResolutionStrategy("rename")
        .accessToken("your-access-token")
        .createVirtualFileRequest(virtualBody)
        .build();
﻿
    CreateVirtualFile200Response response = client.file().createVirtualFile(request);
    System.out.println("Path: " + response.getPath());
    System.out.println("Type: " + response.getType());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
查询文件删除原因
checkFileDeletion 用于查询文件删除的原因，可能是用户主动删除或者 quota 超限删除。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID，单租户模式固定为连字符(-)
inode
String
是
文件的 Inode
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
返回值说明
HTTP 状态码：200
字段
说明
类型
reason
文件删除的原因
String
deletedAt
文件删除的时间
String
quotaCleanupRecordRetentionDays
quota 超限删除流水保留天数
Integer
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.CheckFileDeletion200Response;
﻿
try {
    FileApi.APICheckFileDeletionRequest request = FileApi.APICheckFileDeletionRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .inode("file-inode-id")
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().checkFileDeletionWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        CheckFileDeletion200Response result = (CheckFileDeletion200Response) apiResponse.getData();
        System.out.println("Deletion reason: " + result.getReason());
        System.out.println("Deleted at: " + result.getDeletedAt());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
文件收藏
文件收藏
createFavorite 用于收藏文件目录。需要提供路径或 inode，二者二选一；如果同时提供，以 inode 为准。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
CreateFavoriteRequest 字段说明
字段
类型
必填
说明
path
String
否
文件目录路径
inode
String
否
文件目录 ID
返回值说明
HTTP 状态码：200
字段
说明
类型
inode
文件目录 ID
String
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FavoriteApi;
import com.tencent.cloud.smh.model.CreateFavoriteRequest;
import com.tencent.cloud.smh.model.CreateFavorite200Response;
﻿
CreateFavoriteRequest favBody = new CreateFavoriteRequest();
favBody.setPath("/documents/important-file.pdf");
﻿
try {
    FavoriteApi.APICreateFavoriteRequest request = FavoriteApi.APICreateFavoriteRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .createFavoriteRequest(favBody)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.favorite().createFavoriteWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        CreateFavorite200Response result = (CreateFavorite200Response) apiResponse.getData();
        System.out.println("Favorited, inode: " + result.getInode());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
查看收藏列表
listFavorite 用于查看指定空间收藏列表，支持分页和排序。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
marker
String
否
分页标识（不能与 page/pageSize 同时使用）
limit
Integer
否
分页大小（不能与 page/pageSize 同时使用）
page
Integer
否
分页码
pageSize
Integer
否
分页大小
orderBy
String
否
排序字段，默认 favoriteTime
orderByType
String
否
排序方式：asc / desc
withPath
Boolean
否
是否返回 path
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
返回值说明
HTTP 状态码：200
字段
说明
类型
nextMarker
分页标识
String
totalNum
收藏总数（仅 page 模式返回）
Integer
contents
收藏列表
List<ListFavorite200ResponseContentsInner>
contents 字段说明
字段
说明
类型
spaceId
空间 ID
String
type
文件目录类型
String
inode
文件或目录 ID
String
name
文件或目录名称
String
size
文件大小
String
favoriteTime
收藏时间
String
path
文件目录路径
List<String>
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FavoriteApi;
import com.tencent.cloud.smh.model.ListFavorite200Response;
﻿
try {
    FavoriteApi.APIListFavoriteRequest request = FavoriteApi.APIListFavoriteRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .page(1)
        .pageSize(20)
        .orderBy("favoriteTime")
        .orderByType("desc")
        .withPath(true)
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.favorite().listFavoriteWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        ListFavorite200Response result = (ListFavorite200Response) apiResponse.getData();
        System.out.println("Total favorites: " + result.getTotalNum());
        for (var content : result.getContents()) {
            System.out.println("Name: " + content.getName()
                + ", Favorite time: " + content.getFavoriteTime());
        }
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
取消收藏
deleteFavorite 用于根据路径或 inode 取消收藏，二者二选一。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
cancel
Integer
是
取消收藏标志，固定值为 1
CreateFavoriteRequest 字段说明（与收藏接口相同）
字段
类型
必填
说明
path
String
否
文件目录路径
inode
String
否
文件目录 ID
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FavoriteApi;
import com.tencent.cloud.smh.model.CreateFavoriteRequest;
﻿
CreateFavoriteRequest favBody = new CreateFavoriteRequest();
favBody.setPath("/documents/important-file.pdf");
﻿
try {
    FavoriteApi.APIDeleteFavoriteRequest request = FavoriteApi.APIDeleteFavoriteRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .cancel(1)
        .deleteFavoriteRequest(favBody)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.favorite().deleteFavoriteWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
    System.out.println("Unfavorited successfully");
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
增量同步
获取增量游标
getDeltaCursor 用于获取增量游标（cursor）。cursor 标记了当前变更日志的最新位置，调用方可保存此 cursor，后续作为增量查询变动日志接口的起始位置。
增量同步使用流程：
1. 首次同步时，先调用本接口获取当前最新的 cursor（锚定变更日志位置）
2. 然后调用列出目录或文件接口全量拉取空间文件列表
3. 全量拉取完成后，使用步骤 1 获取的 cursor 调用 queryDeltaLog 接口，补齐全量拉取期间产生的变更
4. 后续定期使用保存的 cursor 调用 queryDeltaLog 接口进行增量同步
cursor 是一个不透明的字符串标记，代表增量同步的位置，调用方应将其作为黑盒保存和传递，无需解析其内容。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
返回值说明
HTTP 状态码：200
字段
说明
类型
cursor
增量游标
String
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.GetDeltaCursor200Response;
﻿
try {
    FileApi.APIGetDeltaCursorRequest request = FileApi.APIGetDeltaCursorRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().getDeltaCursorWithHttpInfo(request);
    if (apiResponse.getStatusCode() == 200) {
        GetDeltaCursor200Response result = (GetDeltaCursor200Response) apiResponse.getData();
        System.out.println("Cursor: " + result.getCursor());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
查询增量变动日志
queryDeltaLog 用于根据增量游标（cursor）拉取文件系统的增量变更日志列表。返回的新 cursor 可用于下次请求，实现连续的增量同步。
首次调用时传入通过 getDeltaCursor 获取的 cursor，后续传入上次返回的 cursor 进行连续拉取
当返回的 hasMore 为 true 时，应继续使用返回的 cursor 拉取后续数据，直到 hasMore 为 false
变更日志按数据库事务提交顺序有序返回
cursor 的最大有效期为 180 天，使用过期 cursor 时服务端会返回 HTTP 400 错误，错误码为 CursorExpired，此时应重新获取 cursor 并进行全量同步
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
cursor
String
是
增量游标
limit
Integer
否
本次拉取的项目数限制，默认 100，最大 1000
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
返回值说明
HTTP 状态码：200
字段
说明
类型
cursor
新的增量游标，用于下次请求
String
hasMore
是否还有更多数据
Boolean
contents
变更事件列表
List
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.QueryDeltaLog200Response;
﻿
try {
    String cursor = "your-saved-cursor";
    boolean hasMore = true;
﻿
    while (hasMore) {
        FileApi.APIQueryDeltaLogRequest request = FileApi.APIQueryDeltaLogRequest.newBuilder()
            .libraryId("your-library-id")
            .spaceId("your-space-id")
            .cursor(cursor)
            .limit(500)
            .accessToken("your-access-token")
            .build();
﻿
        ApiResponse<Object> apiResponse = client.file().queryDeltaLogWithHttpInfo(request);
        if (apiResponse.getStatusCode() == 200) {
            QueryDeltaLog200Response result = (QueryDeltaLog200Response) apiResponse.getData();
            System.out.println("Events: " + result.getContents().size());
            cursor = result.getCursor();
            hasMore = Boolean.TRUE.equals(result.getHasMore());
        } else {
            break;
        }
    }
} catch (ApiException e) {
    // ApiException.getCode() 是 HTTP 状态码；CursorExpired 等服务端业务错误码在响应体中
    if (e.getCode() == 400 && e.getResponseBody() != null && e.getResponseBody().contains("CursorExpired")) {
        System.err.println("Cursor expired, need to re-init");
    } else {
        System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
    }
}
高级功能
解压预览
预览压缩包内容列表。用于在不解压的情况下查看压缩包内的文件和目录结构，支持扁平列表和树形结构两种返回格式。
注意：
此功能需在媒体库（library）级别开启 enableFileUncompress 功能后方可使用，未开启时返回 403（FileUncompressNotEnabled）。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
filePath
String
是
压缩文件路径，使用斜杠(/)分隔，例如 foo/bar/file.zip
zipPreview
Integer
是
解压预览标识，固定值为 1
format
String
否
返回格式，可选值：flat（默认，扁平列表）、tree（树形结构）；传入其他值返回 ParamInvalid 错误
password
String
否
加密压缩包的密码，默认无密码；对非加密压缩包传入密码会被忽略，不影响预览结果
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
返回值说明
HTTP 状态码：200
字段
说明
类型
fileNumber
压缩包中文件/文件夹数量
Integer
isTruncated
是否被截断，压缩包预览最多支持预览前 1000 个文件
Boolean
contents
文件内容列表，格式取决于 format 参数
List/Object
flat 格式（默认）contents 元素字段说明
字段
说明
类型
key
文件或目录在压缩包内的完整路径（含目录前缀，如 testzip/zi-dir/zi-image.png）
String
lastModified
文件最后修改时间（ISO 8601 格式）
OffsetDateTime
uncompressedSize
文件解压后大小（字节），目录条目该字段可能为 0 或不存在
Integer
tree 格式 contents 字段说明
字段
说明
类型
level
目录层级深度，根节点为 0
Integer
isDir
是否是文件夹
Boolean
filename
文件或文件夹名（不含路径前缀）
String
prename
上一级目录名
String
prefix
上一级目录前缀分隔符
String
key
文件在压缩包内的完整路径（仅文件节点有值），该路径可用于选择性解压的 selectedFilePaths 参数
String
lastModified
最后修改时间（ISO 8601 格式），仅文件节点有值
OffsetDateTime
uncompressedSize
文件解压后大小（字节），仅文件节点有值
Integer
children
子文件/文件夹信息数组，文件夹排在文件前面；文件节点该字段为 null
List<Object>
使用示例
基本解压预览（flat 格式）：
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.PreviewZipFile200Response;
﻿
try {
    FileApi.APIPreviewZipFileRequest request = FileApi.APIPreviewZipFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/archive.zip")
        .zipPreview(1)
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().previewZipFileWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
    System.out.println("Status code: " + statusCode);
﻿
    if (statusCode == 200) {
        PreviewZipFile200Response result = (PreviewZipFile200Response) apiResponse.getData();
        System.out.println("File count: " + result.getFileNumber());
        System.out.println("Is truncated: " + result.getIsTruncated());
        System.out.println("Contents: " + result.getContents());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
树形结构预览：
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.PreviewZipFile200Response;
﻿
try {
    FileApi.APIPreviewZipFileRequest request = FileApi.APIPreviewZipFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/archive.zip")
        .zipPreview(1)
        .format("tree")
        .accessToken("your-access-token")
        .build();
﻿
    PreviewZipFile200Response result = client.file().previewZipFile(request);
    System.out.println("File count: " + result.getFileNumber());
    System.out.println("Is truncated: " + result.getIsTruncated());
    System.out.println("Tree contents: " + result.getContents());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
预览加密压缩包：
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.PreviewZipFile200Response;
﻿
try {
    FileApi.APIPreviewZipFileRequest request = FileApi.APIPreviewZipFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/encrypted-archive.7z")
        .zipPreview(1)
        .password("your-zip-password")
        .accessToken("your-access-token")
        .build();
﻿
    PreviewZipFile200Response result = client.file().previewZipFile(request);
    System.out.println("File count: " + result.getFileNumber());
    System.out.println("Contents: " + result.getContents());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
使用限制：
大小限制：tar/gz/rar 需小于 128MB，zip/7zip 无大小限制
文件数限制：最多 1000 个，超出部分截断（isTruncated 为 true）
文件解压
将压缩包中的文件解压到 SMH 网盘的指定目录下，无需下载到本地。解压为异步任务，提交后返回 taskId，通过查询任务接口轮询进度。
注意：
此功能需在媒体库（library）级别开启 enableFileUncompress 功能后方可使用，未开启时返回 403（FileUncompressNotEnabled）。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
filePath
String
是
压缩文件路径，使用斜杠(/)分隔，例如 foo/bar/file.zip
uncompress
Integer
是
解压标识，固定值为 1
uncompressFileRequest
UncompressFileRequest
是
请求体
conflictResolutionStrategy
String
否
文件名冲突时的处理方式，默认为 rename：rename（冲突时自动重命名）、overwrite（冲突时覆盖已有文件）、ask（冲突时该文件解压失败，记入 failedItems 明细）
accessToken
String
否
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId
String
否
用户身份识别
UncompressFileRequest 字段说明
字段
类型
必填
说明
targetPath
String
是
解压目标目录路径，不能为空；路径会经过归一化处理，不允许包含 ../ 等路径穿越字符；该目录必须在 SMH 中已存在，不存在时返回 DirectoryNotFound 错误
targetSpaceId
String
否
解压目标空间 ID，不传则默认解压到源文件所在空间，支持跨空间解压（需 admin 权限）
selectedFilePaths
List<String>
否
指定需要解压的文件/文件夹路径列表（路径来自 previewZipFile 接口返回的 key 字段）；文件夹路径需以 / 结尾；不传或为空则整包解压；目录路径最多指定 1 个，文件路径最多指定 1000 个
password
String
否
加密压缩包的密码，默认无密码
返回值说明
HTTP 状态码：202（异步任务已接收）
字段
说明
类型
taskId
异步解压任务 ID，用于后续查询任务状态
Integer
使用示例
整包解压：
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.UncompressFileRequest;
import com.tencent.cloud.smh.model.UncompressFile202Response;
﻿
UncompressFileRequest uncompressBody = new UncompressFileRequest();
uncompressBody.setTargetPath("/documents/extracted/");
﻿
try {
    FileApi.APIUncompressFileRequest request = FileApi.APIUncompressFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/archive.zip")
        .uncompress(1)
        .uncompressFileRequest(uncompressBody)
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.file().uncompressFileWithHttpInfo(request);
    if (apiResponse.getStatusCode() == 202) {
        UncompressFile202Response result = (UncompressFile202Response) apiResponse.getData();
        System.out.println("Uncompress task submitted, taskId: " + result.getTaskId());
        // TODO: 通过任务查询接口轮询任务状态
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
选择性解压指定文件：
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.UncompressFileRequest;
import com.tencent.cloud.smh.model.UncompressFile202Response;
﻿
import java.util.List;
﻿
UncompressFileRequest uncompressBody = new UncompressFileRequest();
uncompressBody.setTargetPath("/documents/selected/");
uncompressBody.setSelectedFilePaths(List.of(
    "testzip/report.pdf",
    "testzip/images/photo.jpg"
));
﻿
try {
    FileApi.APIUncompressFileRequest request = FileApi.APIUncompressFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/archive.zip")
        .uncompress(1)
        .uncompressFileRequest(uncompressBody)
        .conflictResolutionStrategy("rename")
        .accessToken("your-access-token")
        .build();
﻿
    UncompressFile202Response result = client.file().uncompressFile(request);
    System.out.println("Uncompress task submitted, taskId: " + result.getTaskId());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
解压加密压缩包到其他空间：
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.api.FileApi;
import com.tencent.cloud.smh.model.UncompressFileRequest;
import com.tencent.cloud.smh.model.UncompressFile202Response;
﻿
UncompressFileRequest uncompressBody = new UncompressFileRequest();
uncompressBody.setTargetPath("/shared/extracted/");
uncompressBody.setTargetSpaceId("target-space-id");
uncompressBody.setPassword("your-zip-password");
﻿
try {
    FileApi.APIUncompressFileRequest request = FileApi.APIUncompressFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/encrypted-archive.7z")
        .uncompress(1)
        .uncompressFileRequest(uncompressBody)
        .conflictResolutionStrategy("overwrite")
        .accessToken("your-access-token")
        .build();
﻿
    UncompressFile202Response result = client.file().uncompressFile(request);
    System.out.println("Cross-space uncompress task submitted, taskId: " + result.getTaskId());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
使用限制：
支持格式：zip、tar、gz、7zip、rar、apk
在线文档编辑
officeEdit 用于打开在线文档编辑入口，支持 Word、Excel、PPT、PDF 系列格式，文件大小不超过 200MB。该接口为同步接口，直接返回编辑器 HTML 页面（非 JSON），可嵌入 iframe 或跳转访问。
注意：
使用本功能前，需先在媒体库级别开启文档编辑能力，否则返回 DocEditNotEnabled 错误。
文件类型不支持时返回 FileTypeNotSupported 错误，文件超过 200MB 时返回 FileSizeExceeded 错误。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
待编辑文档的路径
lang
String
否
编辑器语言，如 zh_CN、en
accessToken
String
否
访问令牌
userId
String
否
用户身份识别
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.api.FileApi;
﻿
try {
    FileApi.APIOfficeEditRequest request = FileApi.APIOfficeEditRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/report.docx")
        .lang("zh_CN")
        .accessToken("your-access-token")
        .build();
﻿
    // 返回编辑器 HTML 页面（字符串），不是 JSON，不要按 JSON 解析
    String editorHtml = client.file().officeEdit(request);
    // 可将 HTML 嵌入 iframe 或直接跳转访问
    System.out.println("Editor HTML length: " + editorHtml.length());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
下载文件（底层接口）
downloadFile 用于下载文件。服务端通过 HTTP 302 重定向到真实下载地址，SDK 会自动跟随跳转并排空响应体（返回 void）。如需获取 Location 中的 URL 而非跟随跳转，请先调用 client.setFollowRedirects(HttpClient.Redirect.NEVER)，再从 ApiException 的响应头中读取（302 按非 2xx 抛出）。日常下载建议使用「上传与下载」文档中的高层封装 downloadFile（支持分块并发、进度回调和完整性校验），或先通过 infoFile 获取带签名的下载链接（cosUrl）后自行处理。
请求参数
参数名
类型
必填
说明
libraryId
String
是
媒体库 ID
spaceId
String
是
空间 ID
filePath
String
是
文件路径
historyId
String
否
历史版本 ID，不传默认为最新版
contentDisposition
String
否
用于设置 Content-Disposition 响应头，支持 inline（默认）或 attachment
purpose
String
否
用途，download 或 preview；preview 会将文件加入最近使用列表
trafficLimit
Long
否
单链接下载限速，范围 100KB/s-100MB/s，单位 B
internalDomain
Integer
否
是否使用内网域名，默认 0
accessToken
String
否
访问令牌
userId
String
否
用户身份识别
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.FileApi;
﻿
try {
    FileApi.APIDownloadFileRequest request = FileApi.APIDownloadFileRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .filePath("/documents/report.pdf")
        .purpose("download")
        .accessToken("your-access-token")
        .build();
﻿
    // 302 跳转由 SDK 自动处理，返回 void
    ApiResponse<Object> apiResponse = client.file().downloadFileWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
底层上传接口编排说明
「上传与下载」文档中的高层封装 uploadFile 已自动完成上传全流程编排，业务应优先使用。如需自行控制上传过程（如自定义分片逻辑、对接自有上传通道），可按以下顺序编排底层上传接口：
1. 开始上传（三选一）：simpleUploadFile（简单上传，PUT + 文件内容一次上传）、formUploadFile（表单上传，POST 返回表单字段后向 COS 发起 multipart/form-data 上传，文件字段名固定 file 且须为最后一项）、multipartUploadFile（分块上传，POST + multipart=1，返回 uploadId 后按 https://{Domain}{Path}?uploadId={UploadId}&partNumber={N} 逐块上传，无需回传 ETag）。三个接口仅向 SMH 申请上传参数，文件字节流由客户端直传 COS。
2. 查询上传任务状态：getFileUpload（GET + upload 标识 + confirmKey），可查询已上传分块信息，用于断点续传。
3. 分块任务续期：renewMultipartUpload（POST + renew 标识 + confirmKey），上传参数过期前续期，仅支持分块任务。
4. 完成上传：completeFileUpload（POST + confirm 标识 + confirmKey）。上传完成后必须调用本接口，否则文件无法正确存储。
5. 取消上传：abortFileUpload（DELETE + upload 标识 + confirmKey），分块任务会同时放弃 COS 分块上传任务。
﻿
参数名	类型	必填	说明
libraryId	String	是	媒体库 ID
spaceId	String	是	空间 ID
filePath	String	是	文件路径，使用斜杠(/)分隔，例如 foo/bar/file.txt
info	BigDecimal	是	固定值 1，表示获取文件下载链接和信息
historyId	String	否	历史版本 ID，不传默认为最新版
contentDisposition	String	否	用于设置 Content-Disposition 响应头，支持 inline 或 attachment
purpose	String	否	用途，可设置为 download 或 preview
accessToken	String	否	访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
userId	String	否	用户身份识别
trafficLimit	Long	否	单链接下载限速，范围 100KB/s-100MB/s，单位 B
preCheck	BigDecimal	否	是否只用于校验文件是否可预览和下载
contentCas	String	否	文件内容的 Cas 标识
withContentCas	Integer	否	0 或 1，是否返回文件内容的 Cas 标识
withShortLink	Integer	否	0 或 1，设置为 1 时返回的 cosUrl 将被替换为短链形式
period	Integer	否	链接有效期（秒），取值范围 [60, 7200]，默认 7200
preview	Integer	否	0 或 1，是否返回预览链接
withFavoriteStatus	Integer	否	0 或 1，是否返回收藏状态
字段	说明	类型
cosUrl	带签名的下载链接，签名有效时长约 2 小时	String
type	文件类型	String
creationTime	文件首次完成上传的时间	OffsetDateTime
modificationTime	文件最近一次被覆盖的时间	OffsetDateTime
contentType	媒体类型	String
size	文件大小，字符串格式以避免精度问题	String
eTag	文件 ETag	String
crc64	文件的 CRC64-ECMA182 校验值	String
fileType	文件类型：excel、powerpoint 等	String
previewByDoc	是否可通过 wps 预览	Boolean
previewByCI	是否可通过万象预览	Boolean
previewAsIcon	是否可用预览图作为 icon	Boolean
versionId	文件版本号	Integer
metaData	文件元数据键值对	Map<String, String>
labels	文件简易标签	List<String>
category	文件自定义分类	String
localCreationTime	文件本地创建时间	OffsetDateTime
localModificationTime	文件本地修改时间	OffsetDateTime
contentCas	文件内容的 Cas 标识（withContentCas=1 时返回）	String
HTTP 状态码	说明
200	文件移入回收站，响应体包含 recycledItemId
204	文件被永久删除（无响应体）
文件管理

本页目录：

前期准备

文件信息

获取文件信息

获取照片/视频封面缩略图

获取文档预览

检查文件状态

根据 inode 获取文件信息

文件管理

复制文件

重命名或移动文件

删除文件

创建符号链接

文档转码

获取最近使用文件

创建虚拟文件

查询文件删除原因

文件收藏

文件收藏

查看收藏列表

取消收藏

增量同步

获取增量游标

查询增量变动日志

高级功能

解压预览

文件解压

在线文档编辑

下载文件（底层接口）

底层上传接口编排说明
