前期准备
开始操作前,确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK,请先参考快速入门文档完成。
注意事项:
批量操作接口的请求体为数组,单次最多 1000 个操作项。
批量操作有三种返回形态:200(全部同步完成)、202(转为异步任务,返回 taskId,需通过任务管理接口轮询结果)、207(部分成功,返回每项的执行结果)。
批量复制
功能说明
BatchCopy 用于批量复制文件或目录,支持跨空间复制(指定 copyFromSpaceId)。使用示例
ctx := context.Background()resp200, resp202, resp207, httpRes, err := apiClient.BatchAPI.BatchCopy(ctx, "your-library-id", "your-space-id").Copy(1).BatchCopyRequest([]client.BatchCopyRequestInner{{CopyFrom: "/documents/report.pdf",To: "/backup/report.pdf",},{CopyFromSpaceId: client.PtrString("source-space-id"), // 跨空间复制时指定CopyFrom: "/photos/cover.jpg",To: "/backup/cover.jpg",},}).AccessToken("your-access-token").Execute()if err != nil {panic(err)}switch httpRes.StatusCode {case 200:for _, item := range resp200.Result {fmt.Printf("status=%d path=%v\\n", *item.Status, item.Path)}case 202:fmt.Printf("已转为异步任务,taskId=%d\\n", *resp202.TaskId)case 207:fmt.Println("部分成功")for _, item := range resp207.Result {fmt.Printf("status=%d path=%v\\n", *item.Status, item.Path)}}
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | string | 是 |
spaceId | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 | string | 是 |
Copy | 固定值 1,表示批量复制 | int32 | 是 |
BatchCopyRequest | 批量复制请求数组,最多 1000 个元素 | []BatchCopyRequestInner | 是 |
AccessToken | 访问令牌 | string | 否 |
BatchCopyRequestInner 元素说明
字段 | 参数描述 | 类型 | 是否必填 |
CopyFrom | 源文件或目录路径 | string | 是 |
To | 目标路径 | string | 是 |
CopyFromSpaceId | 跨空间复制时的源空间 ID,不传则与目标同空间 | *string | 否 |
ConflictResolutionStrategy | 冲突处理:ask、rename、overwrite | *string | 否 |
返回值说明
200/207:返回 result 数组,每项含 status(200=rename 成功、204=ask/overwrite 成功、403/404/409/500=失败)、path(最终路径)、copyFrom、to。
202:返回 taskId(int64),通过任务管理接口轮询。
批量移动
功能说明
BatchMove 用于批量移动或重命名文件或目录,支持跨空间移动(指定 fromSpaceId)。注意:目标空间开启历史版本功能时,不支持使用 overwrite 覆盖移动。
使用示例
ctx := context.Background()resp200, resp202, resp207, httpRes, err := apiClient.BatchAPI.BatchMove(ctx, "your-library-id", "your-space-id").Move(1).BatchMoveRequest([]client.BatchMoveRequestInner{{From: "/documents/old-name.pdf",To: "/documents/new-name.pdf",},}).AccessToken("your-access-token").Execute()if err != nil {panic(err)}switch httpRes.StatusCode {case 200:for _, item := range resp200.Result {fmt.Printf("status=%d path=%v\\n", *item.Status, item.Path)}case 202:fmt.Printf("已转为异步任务,taskId=%d\\n", *resp202.TaskId)case 207:fmt.Println("部分成功")}
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | string | 是 |
spaceId | 空间 ID | string | 是 |
Move | 固定值 1,表示批量移动 | int32 | 是 |
BatchMoveRequest | 批量移动请求数组,最多 1000 个元素 | []BatchMoveRequestInner | 是 |
AccessToken | 访问令牌 | string | 否 |
BatchMoveRequestInner 元素说明
字段 | 参数描述 | 类型 | 是否必填 |
From | 源文件或目录路径 | string | 是 |
To | 目标路径 | string | 是 |
FromSpaceId | 跨空间移动时的源空间 ID | *string | 否 |
ConflictResolutionStrategy | 冲突处理:ask、rename、overwrite | *string | 否 |
返回值说明
200/207:返回 result 数组,每项含 status(200=rename 成功、204=ask/overwrite 成功、403/404/409/500=失败)、path、from、to。
202:返回 taskId(int64),通过任务管理接口轮询。
批量删除
功能说明
BatchDelete 用于批量删除文件或目录,默认移入回收站,可指定永久删除。警告:permanent 为 true 时文件将被永久删除,不可恢复,请谨慎操作。
使用示例
ctx := context.Background()resp200, resp202, resp207, httpRes, err := apiClient.BatchAPI.BatchDelete(ctx, "your-library-id", "your-space-id").Delete(1).BatchDeleteRequest([]client.BatchDeleteRequestInner{{Path: "/documents/temp1.txt"},{Path: "/documents/temp2.txt", Permanent: client.PtrBool(true)}, // 永久删除}).AccessToken("your-access-token").Execute()if err != nil {panic(err)}switch httpRes.StatusCode {case 200:for _, item := range resp200.Result {if item.RecycledItemId != nil {fmt.Printf("status=%d recycledItemId=%d\\n", *item.Status, *item.RecycledItemId)} else {fmt.Printf("status=%d\\n", *item.Status)}}case 202:fmt.Printf("已转为异步任务,taskId=%d\\n", *resp202.TaskId)case 207:fmt.Println("部分成功")}
参数说明
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | string | 是 |
spaceId | 空间 ID | string | 是 |
Delete | 固定值 1,表示批量删除 | int32 | 是 |
BatchDeleteRequest | 批量删除请求数组,最多 1000 个元素 | []BatchDeleteRequestInner | 是 |
AccessToken | 访问令牌 | string | 否 |
BatchDeleteRequestInner 元素说明
字段 | 参数描述 | 类型 | 是否必填 |
Path | 待删除的文件或目录路径 | string | 是 |
Permanent | 是否永久删除,默认 false(移入回收站) | *bool | 否 |
返回值说明
200/207:返回 result 数组,每项含 status(200=移入回收站成功、204=永久删除成功、403/404/500=失败)、recycledItemId(移入回收站时返回,int64)、path。
202:返回 taskId(int64),通过任务管理接口轮询。
相关文档
异步任务返回 taskId 时,请参考任务管理文档查询任务执行结果。
批量操作的单项失败不会中断其他项的执行,请逐项检查 result 中的 status。