帮你快速理解、总结文档立即下载

历史版本

最近更新时间:2026-09-30 16:51:31
本文档已由 AI 辅助审校
我的收藏

前期准备

开始操作前,确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK,请先参考快速入门文档完成。
注意:
历史版本功能需要先通过设置历史版本配置信息接口开启。
历史版本配置设置生效可能有 1 分钟左右延迟。
清空历史版本接口会清空整个 library 全部文件的历史版本,相应的空间会释放,不可找回数据,请谨慎操作!
清空历史版本接口有频控限制,每分钟最多调用 1 次,请勿频繁调用。
历史版本合并时间可以减少冗余的历史版本,在指定时间内的覆盖操作只会生成 1 个历史版本。

查看历史版本列表

listHistory 实现查看历史版本列表,用于查询指定文件的所有历史版本信息。支持分页查询和排序。
// 使用 page/pageSize 模式分页
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.HistoryApi;
import com.tencent.cloud.smh.model.ListHistory200Response;

try {
HistoryApi.APIListHistoryRequest request = HistoryApi.APIListHistoryRequest.newBuilder()
.libraryId("your-library-id")
.spaceId("your-space-id")
.filePath("/documents/report.pdf")
.page(1)
.pageSize(10)
.orderBy("creationTime")
.orderByType("desc")
.accessToken("your-access-token")
.build();

ApiResponse<Object> apiResponse = client.history().listHistoryWithHttpInfo(request);
int statusCode = apiResponse.getStatusCode();

if (statusCode == 200) {
ListHistory200Response result = (ListHistory200Response) apiResponse.getData();
System.out.println("Total versions: " + result.getTotalNum());
for (var content : result.getContents()) {
System.out.println("Version " + content.getVersion()
+ ": " + content.getName()
+ " (" + content.getSize() + " bytes)");
}
}
} catch (ApiException e) {
System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
// 使用 marker/limit 模式分页
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.HistoryApi;
import com.tencent.cloud.smh.model.ListHistory200Response;

try {
String marker = null;
while (true) {
HistoryApi.APIListHistoryRequest.Builder builder = HistoryApi.APIListHistoryRequest.newBuilder()
.libraryId("your-library-id")
.spaceId("your-space-id")
.filePath("/documents/report.pdf")
.accessToken("your-access-token")
.limit(20);

if (marker != null) {
builder.marker(marker);
}

ApiResponse<Object> apiResponse = client.history().listHistoryWithHttpInfo(builder.build());
int statusCode = apiResponse.getStatusCode();

if (statusCode == 200) {
ListHistory200Response result = (ListHistory200Response) apiResponse.getData();
for (var content : result.getContents()) {
System.out.println("Version " + content.getVersion());
}

if (result.getHasMore() == null || !result.getHasMore()) {
break;
}

if (result.getNextMarker() != null) {
marker = result.getNextMarker();
}
}
}
} catch (ApiException e) {
System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数
String
是
filePath
文件路径,对于多级目录,使用斜杠(/)分隔,例如 foo/bar.txt
String
是
accessToken
访问令牌;对于公有读媒体库或租户空间可不指定,否则需通过本参数传入或提前调用 client.withToken() 注入,二者取一
String
否
marker
用于顺序列出分页的标识
String
否
limit
用于顺序列出分页时本地列出的项目数限制,默认为 20;若不指定任何翻页参数,默认采用(marker,limit)参数翻页
Integer
否
page
分页码,默认第一页
Integer
否
pageSize
分页大小,默认 20;若与(marker,limit)参数同时使用,默认采用(page,pageSize)参数翻页
Integer
否
orderBy
排序字段,按文件 id 排序为 id,按创建时间排序为 creationTime,默认为 id,最新版本排序始终在首位
String
否
orderByType
排序方式,升序为 asc,降序为 desc,默认为 desc
String
否
返回值说明
HTTP 状态码:200,获取成功,返回历史版本列表。
响应字段说明
字段
说明
类型
totalNum
历史版本总数,采用 page 模式才会返回该字段
Integer
hasMore
是否有更多搜索结果
Boolean
nextMarker
用于获取后续页的分页标识,仅当 hasMore 为 true 时才返回该字段
String
contents
历史版本列表
Array
contents 数组元素字段说明
字段
说明
类型
id
历史版本 ID,最新历史版本不返回这一字段
Integer
createdBy
创建人 ID
String
creationWay
创建方式,0:创建,1:更新
Integer
version
版本号
Integer
isLatestVersion
是否最新版本
Boolean
name
目录或相簿名或文件名
String
size
历史版本文件大小
Long
crc64
文件的 CRC64-ECMA182 校验值,字符串格式
String
contentType
文件元类型
String
creationTime
ISO 8601 格式的日期与时间字符串,表示文件的创建时间
String
setLatestTime
设置为最新版本的时间
String

查询历史版本配置信息

getHistoryConfig 实现查询历史版本配置信息,用于获取当前媒体库的历史版本配置。权限要求:admin 权限。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.HistoryApi;
import com.tencent.cloud.smh.model.GetHistoryConfig200Response;

try {
HistoryApi.APIGetHistoryConfigRequest request = HistoryApi.APIGetHistoryConfigRequest.newBuilder()
.libraryId("your-library-id")
.accessToken("your-access-token")
.build();

ApiResponse<Object> apiResponse = client.history().getHistoryConfigWithHttpInfo(request);
int statusCode = apiResponse.getStatusCode();

if (statusCode == 200) {
GetHistoryConfig200Response result = (GetHistoryConfig200Response) apiResponse.getData();
System.out.println("History enabled: " + result.getEnableFileHistory());
System.out.println("Max history count: " + result.getFileHistoryCount());
System.out.println("Expire days: " + result.getFileHistoryExpireDay());
System.out.println("Merge interval: " + result.getMergeInterval() + " seconds");
}
} catch (ApiException e) {
System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
accessToken
访问令牌;对于公有读媒体库或租户空间可不指定,否则需通过本参数传入或提前调用 client.withToken() 注入,二者取一
String
否
返回值说明
HTTP 状态码:200,获取成功,返回历史版本配置信息。
响应字段说明
字段
说明
类型
enableFileHistory
是否打开历史版本
Boolean
fileHistoryCount
历史版本最大数量,范围:1-999 个
Integer
fileHistoryExpireDay
历史版本过期时间,范围:0-999 天,0 表示永不过期
Integer
mergeInterval
历史版本合并时间,即在 mergeInterval 秒内的覆盖操作,只会生成 1 个历史版本
Integer

设置历史版本配置信息

setHistoryConfig 实现设置历史版本配置信息,用于配置媒体库的历史版本功能。权限要求:admin 权限。多次调用接口会覆盖之前设置,以最后一次调用为准。更新时,可以设置部分字段;未传入字段,其值保持不变。配置设置生效可能有 1 分钟左右延迟。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.HistoryApi;
import com.tencent.cloud.smh.model.SetHistoryConfigRequest;

SetHistoryConfigRequest configBody = new SetHistoryConfigRequest();
configBody.setEnableFileHistory(true);
configBody.setFileHistoryCount(100);
configBody.setFileHistoryExpireDay(30);
configBody.setMergeInterval(60);

try {
HistoryApi.APISetHistoryConfigRequest request = HistoryApi.APISetHistoryConfigRequest.newBuilder()
.libraryId("your-library-id")
.accessToken("your-access-token")
.setHistoryConfigRequest(configBody)
.build();

ApiResponse<Object> apiResponse = client.history().setHistoryConfigWithHttpInfo(request);
System.out.println("Status code: " + apiResponse.getStatusCode());
System.out.println("History config set successfully");
} catch (ApiException e) {
System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
accessToken
访问令牌;对于公有读媒体库或租户空间可不指定,否则需通过本参数传入或提前调用 client.withToken() 注入,二者取一
String
否
setHistoryConfigRequest
设置历史版本配置请求对象
SetHistoryConfigRequest
是
setHistoryConfigRequest 对象说明:
字段
参数描述
类型
是否必填
enableFileHistory
是否打开历史版本,默认为 false
Boolean
否
fileHistoryCount
历史版本最大数量,范围:1-999 个;第一次设置必填
Integer
否
fileHistoryExpireDay
历史版本过期时间,范围:0-999 天,0 表示永不过期;第一次设置必填
Integer
否
mergeInterval
历史版本合并时间,范围:0 或 5-600,默认为 0 秒(不合并)
Integer
否
返回值说明:
HTTP 状态码:204,设置成功,无响应体。

设置历史版本为最新版本

setHistoryLatest 实现设置历史版本为最新版本,将指定的历史版本恢复为当前文件的最新版本。权限要求:admin、space_admin 或 set_history_latest 权限。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.HistoryApi;
import com.tencent.cloud.smh.model.SetHistoryLatest200Response;

try {
HistoryApi.APISetHistoryLatestRequest request = HistoryApi.APISetHistoryLatestRequest.newBuilder()
.libraryId("your-library-id")
.spaceId("your-space-id")
.historyId("1")
.accessToken("your-access-token")
.build();

ApiResponse<Object> apiResponse = client.history().setHistoryLatestWithHttpInfo(request);
int statusCode = apiResponse.getStatusCode();

if (statusCode == 200) {
SetHistoryLatest200Response result = (SetHistoryLatest200Response) apiResponse.getData();
System.out.println("Set as latest version successfully");
System.out.println("File: " + result.getName());
System.out.println("Size: " + result.getSize() + " bytes");
System.out.println("Set time: " + result.getSetLatestTime());
}
} catch (ApiException e) {
System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明:
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数
String
是
historyId
历史版本 ID
String
是
accessToken
访问令牌;对于公有读媒体库或租户空间可不指定,否则需通过本参数传入或提前调用 client.withToken() 注入,二者取一
String
否
返回值说明:
HTTP 状态码:200,设置成功,返回最新版本文件信息。
响应字段说明:
字段
说明
类型
name
文件名
String
type
文件类型
String
creationTime
ISO 8601 格式的日期与时间字符串,表示最新版本文件的创建时间
String
modificationTime
ISO 8601 格式的日期与时间字符串,表示最新版本文件的修改时间
String
setLatestTime
设置为最新版本的时间
String
contentType
媒体类型
String
size
最新版本的文件大小
Long
eTag
文件 ETag
String
crc64
文件的 CRC64-ECMA182 校验值,字符串格式
String
previewByDoc
是否可通过 wps 预览
Boolean
previewByCI
是否可通过万象预览
Boolean
previewAsIcon
是否可用预览图当做 icon
Boolean
fileType
文件类型,例如 excel、powerpoint 等
String

删除历史版本

deleteHistory 实现删除指定的历史版本,可以批量删除多个历史版本。权限要求:delete_history、admin 或 space_admin 权限。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.HistoryApi;
import java.util.List;

try {
HistoryApi.APIDeleteHistoryRequest request = HistoryApi.APIDeleteHistoryRequest.newBuilder()
.libraryId("your-library-id")
.spaceId("your-space-id")
.accessToken("your-access-token")
.requestBody(List.of("1", "2", "3"))
.build();

ApiResponse<Object> apiResponse = client.history().deleteHistoryWithHttpInfo(request);
System.out.println("Status code: " + apiResponse.getStatusCode());
System.out.println("History versions deleted");
} catch (ApiException e) {
System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数
String
是
accessToken
访问令牌;对于公有读媒体库或租户空间可不指定,否则需通过本参数传入或提前调用 client.withToken() 注入,二者取一
String
否
requestBody
删除的 HistoryId 集合,单次最多传入 100 个
List<String>
是
返回值说明
HTTP 状态码:200,删除成功,无响应体。

清空历史版本

emptyHistory 实现清空整个媒体库的历史版本,包括所有文件的所有历史版本。请求此接口时,需要先关闭历史版本。
警告:
此接口会清空整个 library 全部文件的历史版本,不可找回数据,请谨慎操作!
权限要求:admin 权限。此接口有频控限制,每分钟最多调用 1 次,请勿频繁调用。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.HistoryApi;
import com.tencent.cloud.smh.model.EmptyHistory202Response;
import com.tencent.cloud.smh.model.SetHistoryConfigRequest;

// 1. 先关闭历史版本
SetHistoryConfigRequest configBody = new SetHistoryConfigRequest();
configBody.setEnableFileHistory(false);

try {
HistoryApi.APISetHistoryConfigRequest disableRequest = HistoryApi.APISetHistoryConfigRequest.newBuilder()
.libraryId("your-library-id")
.accessToken("your-access-token")
.setHistoryConfigRequest(configBody)
.build();

client.history().setHistoryConfigWithHttpInfo(disableRequest);
System.out.println("History disabled, waiting for configuration to take effect...");
// 等待配置生效(大约 1 分钟)
Thread.sleep(60_000);

// 2. 清空历史版本
HistoryApi.APIEmptyHistoryRequest request = HistoryApi.APIEmptyHistoryRequest.newBuilder()
.libraryId("your-library-id")
.accessToken("your-access-token")
.build();

ApiResponse<Object> apiResponse = client.history().emptyHistoryWithHttpInfo(request);
int statusCode = apiResponse.getStatusCode();

if (statusCode == 202) {
EmptyHistory202Response result = (EmptyHistory202Response) apiResponse.getData();
System.out.println("Empty history task submitted. Task ID: " + result.getTaskId());
}
} catch (ApiException e) {
System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
accessToken
访问令牌;对于公有读媒体库或租户空间可不指定,否则需通过本参数传入或提前调用 client.withToken() 注入,二者取一
String
否
返回值说明
HTTP 状态码:202,清空任务已提交,异步处理。
响应字段说明
字段
说明
类型
taskId
异步任务 ID
Long