前期准备
开始操作前,确保您已经完成了 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 |