注意事项
注意事项:
查询任务接口(V1)、查询媒体库任务接口(V1/V2)仅支持查询最近 30 天内创建的任务;查询任务接口 V2(空间级)无此说明,以其返回为准。
前期准备
开始操作前,确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK,请先参考快速入门文档完成。
查询任务(V1)
查询空间级别的异步任务状态(V1 版本),支持批量查询多个任务,返回任务数组。
使用示例
ctx := context.Background()resp, httpRes, err := apiClient.TaskAPI.QueryTask(ctx, "your-library-id", "your-space-id", "12345,12346").AccessToken("your-access-token").Execute()if err != nil {panic(err)}// 返回值为任务数组for _, task := range *resp {fmt.Printf("TaskId: %d, Status: %d\\n", *task.TaskId, *task.Status)// task.Result 为 map 或数组结构,按任务类型解析}
请求参数
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | string | 是 |
spaceId | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 | string | 是 |
taskIdList | 任务 ID 列表,多个任务 ID 使用英文逗号(,)分隔 | string | 是 |
accessToken | 访问令牌 | string | 否 |
userId | 用户身份识别 | string | 否 |
返回值说明
HTTP 状态码:200,返回任务数组,每项包含:
字段 | 说明 | 类型 |
taskId | 任务 ID | int64 |
status | 任务状态码:202 任务进行中、200 任务成功且有返回结果、204 任务成功无返回结果、500 任务执行失败 | int32 |
result | 任务结果(按任务类型为对象或数组结构) | object/array |
V1 任务状态码说明
状态码 | 说明 |
202 | 任务进行中,需继续轮询 |
200 | 任务成功完成且有返回结果 |
204 | 任务成功完成,无返回结果 |
500 | 任务执行失败 |
查询媒体库任务(V1)
查询媒体库级别的异步任务状态(V1 版本),支持批量查询多个任务。
使用示例
ctx := context.Background()resp, httpRes, err := apiClient.TaskAPI.QueryLibraryTask(ctx, "your-library-id", "12345,12346").AccessToken("your-access-token").Execute()if err != nil {panic(err)}for _, task := range *resp {fmt.Printf("TaskId: %d, Status: %d\\n", *task.TaskId, *task.Status)}
请求参数
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | string | 是 |
taskIdList | 任务 ID 列表,多个任务 ID 使用英文逗号(,)分隔 | string | 是 |
accessToken | 访问令牌 | string | 否 |
userId | 用户身份识别 | string | 否 |
返回值说明
HTTP 状态码:200,返回任务数组(taskId、status、result),任务状态码语义同 V1 查询任务。
查询任务
查询空间级别的异步任务状态(V2 版本),支持结构化的任务结果返回,根据不同的任务类型返回对应的结果结构。
方法签名
func (a *TaskAPIService) QueryTaskV2(ctx context.Context, libraryId string, spaceId string, taskId string) TaskAPIQueryTaskV2Request
使用示例
ctx := context.Background()resp, httpRes, err := apiClient.TaskAPI.QueryTaskV2(ctx, "your-library-id", "your-space-id", "12345").AccessToken("your-access-token").Execute()if err != nil {panic(err)}fmt.Printf("Query task V2 status: %d\\n", httpRes.StatusCode)fmt.Printf("Task ID: %s, Type: %s, Status: %d\\n", *resp.TaskId, *resp.TaskType, *resp.Status)// 根据任务类型处理不同的结果if resp.BatchMoveResults != nil {for _, result := range resp.BatchMoveResults {fmt.Printf("Move result - Path: %v, Status: %d\\n", result.Path, *result.Status)}}if resp.BatchCopyResults != nil {for _, result := range resp.BatchCopyResults {fmt.Printf("Copy result - Path: %v, Status: %d\\n", result.Path, *result.Status)}}
请求参数
libraryId | string | 是 | 媒体库 ID |
spaceId | string | 是 | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 |
taskId | string | 是 | 任务 ID |
accessToken | string | 否 | 访问令牌,对于公有读媒体库或租户空间可不指定该参数,否则必须指定该参数 |
userId | string | 否 | 用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份 |
返回值说明
HTTP 状态码:200
查询成功,返回任务详情。
响应示例
{"taskId": "12345","taskType": "batchMove","status": 200,"batchMoveResults": [{"path": ["dir", "file.txt"],"status": 200}]}
响应字段说明
taskId | 任务唯一标识符 | string |
taskType | 任务类型标识,用于 SDK 根据类型解析对应的结果结构 | string |
status | 任务状态码,202: 处理中,200: 成功,207: 部分成功,400: 全部失败,500: 任务失败 | int32 |
batchMoveResults | 批量移动任务结果(taskType 为 batchMove 时返回) | array |
batchCopyResults | 批量复制任务结果(taskType 为 batchCopy 时返回) | array |
batchDeleteResults | 批量删除任务结果(taskType 为 batchDelete 时返回) | array |
batchRestoreRecycleResults | 批量恢复回收站任务结果(taskType 为 batchRestoreRecycle 时返回) | array |
convertFileResult | 文件转换任务结果(taskType 为 convertFile 时返回) | object |
calibrateDirectoryStatsResult | 目录统计校准任务结果(taskType 为 calibrateDirectoryStats 时返回) | object |
videoTranscodeResult | 视频转码任务结果(taskType 为 videoTranscode 时返回) | object |
fileUncompressResult | 文件解压任务结果(taskType 为 fileUncompress 时返回) | object |
任务类型枚举
batchMove | 批量移动文件 | batchMoveResults | BatchMoveResultItem[] |
batchCopy | 批量复制文件 | batchCopyResults | BatchCopyResultItem[] |
batchDelete | 批量删除文件 | batchDeleteResults | BatchDeleteResultItem[] |
batchRestoreRecycle | 批量恢复回收站 | batchRestoreRecycleResults | BatchRestoreRecycleResultItem[] |
convertFile | 文件转换 | convertFileResult | ConvertFileResult |
calibrateDirectoryStats | 目录统计校准 | calibrateDirectoryStatsResult | CalibrateDirectoryStatsResult |
videoTranscode | 视频转码 | videoTranscodeResult | VideoTranscodeResult |
fileUncompress | 文件解压 | fileUncompressResult | FileUncompressResult |
任务状态说明
202 | 任务进行中 | 否 |
200 | 任务成功完成且有返回结果 | 是 |
207 | 批量任务部分成功 | 是 |
400 | 所有子任务全部失败 | 是 |
500 | 任务执行失败 | 是 |
查询媒体库任务
查询媒体库级别的异步任务状态(V2 版本),支持结构化的任务结果返回。
方法签名
func (a *TaskAPIService) QueryLibraryTaskV2(ctx context.Context, libraryId string, taskId string) TaskAPIQueryLibraryTaskV2Request
使用示例
ctx := context.Background()resp, httpRes, err := apiClient.TaskAPI.QueryLibraryTaskV2(ctx, "your-library-id", "12345").AccessToken("your-access-token").Execute()if err != nil {panic(err)}fmt.Printf("Query library task V2 status: %d\\n", httpRes.StatusCode)fmt.Printf("Task ID: %s, Type: %s, Status: %d\\n", *resp.TaskId, *resp.TaskType, *resp.Status)// 处理清空历史版本任务结果if resp.ClearLibraryHistoryResult != nil {result := resp.ClearLibraryHistoryResultfmt.Printf("Clear history result - Status: %d, Code: %s, DeleteCount: %d\\n",*result.Status, *result.Code, *result.DeleteCount)}
请求参数
libraryId | string | 是 | 媒体库 ID |
taskId | string | 是 | 任务 ID |
accessToken | string | 否 | 访问令牌,对于公有读媒体库或租户空间可不指定该参数,否则必须指定该参数 |
userId | string | 否 | 用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份 |
返回值说明
HTTP 状态码:200
查询成功,返回任务详情。
响应示例
{"taskId": "12345","taskType": "clearLibraryHistory","status": 200,"clearLibraryHistoryResult": {"status": 200,"code": "OK","deleteCount": 100}}
响应字段说明
taskId | 任务唯一标识符 | string |
taskType | 任务类型标识,用于 SDK 根据类型解析对应的结果结构 | string |
status | 任务状态码,202: 处理中,200: 成功,500: 任务失败 | int32 |
clearLibraryHistoryResult | 清空媒体库历史版本任务结果(taskType 为 clearLibraryHistory 时返回) | object |
clearLibraryHistoryResult 字段说明
status | 任务操作状态码 | int32 |
code | 操作结果代码 | string |
deleteCount | 删除的历史版本数量 | int64 |
任务类型枚举
clearLibraryHistory | 清空媒体库历史版本 | clearLibraryHistoryResult | ClearLibraryHistoryResult |