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

异步任务管理

最近更新时间:2026-09-30 16:51:33
我的收藏

注意事项

注意事项:
查询任务接口(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.ClearLibraryHistoryResult
fmt.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