前期准备
开始操作前,确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK,请先参考快速入门文档完成。
注意:
历史版本功能需要先通过设置历史版本配置信息接口开启。
历史版本配置设置生效可能有 1 分钟左右延迟。
清空历史版本接口会清空整个 library 全部文件的历史版本,相应的空间会释放,不可找回数据,请谨慎操作!
清空历史版本接口有频控限制,每分钟最多调用 1 次,请勿频繁调用。
历史版本合并时间可以减少冗余的历史版本,在指定时间内的覆盖操作只会生成 1 个历史版本。
查看历史版本列表
ListHistory 实现查看历史版本列表,用于查询指定文件的所有历史版本信息。支持分页查询和排序。// 使用 page/pageSize 模式分页ctx := context.Background()resp, httpRes, err := apiClient.HistoryAPI.ListHistory(ctx, "your-library-id", "your-space-id", "path/to/file.pdf").AccessToken("your-access-token").Page(1).PageSize(10).OrderBy("creationTime").OrderByType("desc").Execute()if err != nil {panic(err)}fmt.Printf("Page 1 - Total: %d\\n", resp.TotalNum)for _, version := range resp.Contents {fmt.Printf("Version: %d, Size: %d bytes\\n", version.Version, version.Size)}
// 使用 marker/limit 模式分页ctx := context.Background()marker := ""for {req := apiClient.HistoryAPI.ListHistory(ctx, "your-library-id", "your-space-id", "path/to/file.pdf").AccessToken("your-access-token").Limit(20)if marker != "" {req = req.Marker(marker)}resp, httpRes, err := req.Execute()if err != nil {panic(err)}for _, version := range resp.Contents {fmt.Printf("Version: %d\\n", version.Version)}if resp.HasMore != nil && !*resp.HasMore {break}if resp.NextMarker == nil {break // 无后续分页标识,结束循环}marker = *resp.NextMarker}
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | String | 是 |
spaceId | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 | String | 是 |
filePath | 文件路径,对于多级目录,使用斜杠(/)分隔,例如 foo/bar.txt | String | 是 |
accessToken | 访问令牌 | String | 否 |
marker | 用于顺序列出分页的标识 | String | 否 |
limit | 用于顺序列出分页时本地列出的项目数限制,默认为 20;若不指定任何翻页参数,默认采用(marker,limit)参数翻页 | Int32 | 否 |
page | 分页码,默认第一页 | Int32 | 否 |
pageSize | 分页大小,默认 20;若与(marker,limit)参数同时使用,默认采用(page,page_size)参数翻页 | Int32 | 否 |
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 | 历史版本文件大小 | int64 |
crc64 | 文件的 CRC64-ECMA182 校验值,字符串格式 | String |
contentType | 文件元类型 | String |
creationTime | ISO 8601 格式的日期与时间字符串,表示文件的创建时间 | String |
setLatestTime | 设置为最新版本的时间 | String |
查询历史版本配置信息
GetHistoryConfig 实现查询历史版本配置信息,用于获取当前媒体库的历史版本配置。权限要求:admin 权限。ctx := context.Background()resp, httpRes, err := apiClient.HistoryAPI.GetHistoryConfig(ctx, "your-library-id").AccessToken("your-access-token").Execute()if err != nil {panic(err)}fmt.Printf("History Configuration:\\n")fmt.Printf(" Enabled: %v\\n", resp.EnableFileHistory)fmt.Printf(" Max Versions: %d\\n", resp.FileHistoryCount)if resp.FileHistoryExpireDay != nil {if *resp.FileHistoryExpireDay == 0 {fmt.Printf(" Expiration: Never\\n")} else {fmt.Printf(" Expiration: %d days\\n", *resp.FileHistoryExpireDay)}}fmt.Printf(" Merge Interval: %d seconds\\n", resp.MergeInterval)
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | String | 是 |
accessToken | 访问令牌 | String | 否 |
返回值说明
HTTP 状态码:200,获取成功,返回历史版本配置信息。
响应字段说明
字段 | 说明 | 类型 |
enableFileHistory | 是否打开历史版本 | Boolean |
fileHistoryCount | 历史版本最大数量,范围:1-999 个 | Integer |
fileHistoryExpireDay | 历史版本过期时间,范围:0-999 天,0 表示永不过期 | Integer |
mergeInterval | 历史版本合并时间,即在 mergeInterval 秒内的覆盖操作,只会生成 1 个历史版本 | Integer |
设置历史版本配置信息
SetHistoryConfig 实现设置历史版本配置信息,用于配置媒体库的历史版本功能。权限要求:admin 权限。多次调用接口会覆盖之前设置,以最后一次调用为准。更新时,可以设置部分字段;未传入字段,其值保持不变。配置设置生效可能有 1 分钟左右延迟。ctx := context.Background()configRequest := client.NewSetHistoryConfigRequest()configRequest.SetEnableFileHistory(true)configRequest.SetFileHistoryCount(10)configRequest.SetFileHistoryExpireDay(30)configRequest.SetMergeInterval(60)httpRes, err := apiClient.HistoryAPI.SetHistoryConfig(ctx, "your-library-id").AccessToken("your-access-token").SetHistoryConfigRequest(*configRequest).Execute()if err != nil {panic(err)}fmt.Printf("History configuration set successfully: %d\\n", httpRes.StatusCode)
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | String | 是 |
accessToken | 访问令牌 | String | 否 |
setHistoryConfigRequest | 设置历史版本配置请求对象 | SetHistoryConfigRequest | 是 |
setHistoryConfigRequest 对象说明
字段 | 参数描述 | 类型 | 是否必填 |
enableFileHistory | 是否打开历史版本,默认为 false | Boolean | 否 |
fileHistoryCount | 历史版本最大数量,范围:1-999 个;第一次设置必填 | Int32 | 否 |
fileHistoryExpireDay | 历史版本过期时间,范围:0-999 天,0 表示永不过期;第一次设置必填 | Int32 | 否 |
mergeInterval | 历史版本合并时间,范围:0 或 5-600,默认为 0 秒(不合并) | Int32 | 否 |
返回值说明
HTTP 状态码:204,设置成功,无响应体。
设置历史版本为最新版本
SetHistoryLatest 实现设置历史版本为最新版本,将指定的历史版本恢复为当前文件的最新版本。权限要求:admin、space_admin 或 set_history_latest 权限。ctx := context.Background()resp, httpRes, err := apiClient.HistoryAPI.SetHistoryLatest(ctx, "your-library-id", "your-space-id", "1").AccessToken("your-access-token").Execute()if err != nil {panic(err)}fmt.Printf("History version set as latest: %s\\n", resp.Name)fmt.Printf("Set time: %s\\n", resp.SetLatestTime)fmt.Printf("File size: %d bytes\\n", resp.Size)
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | String | 是 |
spaceId | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 | String | 是 |
historyId | 历史版本 ID | String | 是 |
accessToken | 访问令牌 | String | 否 |
返回值说明
HTTP 状态码:200,设置成功,返回最新版本文件信息。
响应字段说明
字段 | 说明 | 类型 |
name | 文件名 | String |
type | 文件类型 | String |
creationTime | ISO 8601 格式的日期与时间字符串,表示最新版本文件的创建时间 | String |
modificationTime | ISO 8601 格式的日期与时间字符串,表示最新版本文件的修改时间 | String |
setLatestTime | 设置为最新版本的时间 | String |
contentType | 媒体类型 | String |
size | 最新版本的文件大小 | int64 |
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 权限。ctx := context.Background()historyIds := []string{"1", "2", "3"}httpRes, err := apiClient.HistoryAPI.DeleteHistory(ctx, "your-library-id", "your-space-id").AccessToken("your-access-token").RequestBody(historyIds).Execute()if err != nil {panic(err)}fmt.Printf("%d history versions deleted successfully\\n", len(historyIds))
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | String | 是 |
spaceId | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 | String | 是 |
accessToken | 访问令牌 | String | 否 |
requestBody | 删除的 HistoryId 集合,单次最多传入 100 个 | []String | 是 |
返回值说明
HTTP 状态码:200,删除成功,无响应体。
清空历史版本
EmptyHistory 实现清空整个媒体库的历史版本,包括所有文件的所有历史版本。请求此接口时,需要先关闭历史版本。警告:
此接口会清空整个 library 全部文件的历史版本,不可找回数据,请谨慎操作!
权限要求:admin 权限。此接口有频控限制,每分钟最多调用 1 次,请勿频繁调用。
ctx := context.Background()// 1. 先关闭历史版本configRequest := client.NewSetHistoryConfigRequest()configRequest.SetEnableFileHistory(false)_, err := apiClient.HistoryAPI.SetHistoryConfig(ctx, "your-library-id").AccessToken("your-access-token").SetHistoryConfigRequest(*configRequest).Execute()if err != nil {panic(err)}fmt.Printf("History disabled, waiting for configuration to take effect...\\n")// 等待配置生效(大约 1 分钟)time.Sleep(60 * time.Second)// 2. 清空历史版本resp, httpRes, err := apiClient.HistoryAPI.EmptyHistory(ctx, "your-library-id").AccessToken("your-access-token").Execute()if err != nil {panic(err)}if resp.TaskId != nil {fmt.Printf("Empty history task submitted. Task ID: %d\\n", *resp.TaskId)}
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | String | 是 |
accessToken | 访问令牌 | String | 否 |
返回值说明
HTTP 状态码:202,清空任务已提交,异步处理。
响应字段说明
字段 | 说明 | 类型 |
taskId | 异步任务 ID | int64 |