帮你快速理解、总结文档立即下载
文档中心>智能媒资托管>SDK 文档>Java SDK>任务管理

任务管理

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

本页目录：

前期准备

开始操作前，确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK，请先参考快速入门文档完成。
注意：
批量复制/移动/删除、目录复制、文档转码、文件解压、清空历史版本等接口以异步方式执行时，会返回 taskId，需通过本文档的任务查询接口轮询执行结果。
查询任务接口（V1）、查询媒体库任务接口（V1/V2）仅支持查询最近 30 天内创建的任务；查询任务接口 V2 无此说明，以其返回为准。
查询任务接口 V2 按任务类型返回结构化的执行结果，建议优先使用 V2 接口。

查询任务接口 V2（推荐）

功能说明
queryTaskV2 用于查询指定空间内异步任务的执行状态和结构化结果，任务类型包括批量移动、批量复制、批量删除、批量恢复回收站、文档转码、目录统计校准、视频转码、文件解压。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.TaskApi;
import com.tencent.cloud.smh.model.QueryTaskV2200Response;

try {
    TaskApi.APIQueryTaskV2Request request = TaskApi.APIQueryTaskV2Request.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .taskId("12345")
        .accessToken("your-access-token")
        .userId("user-id")
        .build();

    ApiResponse<Object> apiResponse = client.task().queryTaskV2WithHttpInfo(request);

    if (apiResponse.getStatusCode() == 200) {
        QueryTaskV2200Response result = (QueryTaskV2200Response) apiResponse.getData();
        System.out.println("Task type: " + result.getTaskType());
        System.out.println("Status: " + result.getStatus());
        // status：202 处理中，200 成功，207 部分成功，400 全部失败，500 失败
        if (result.getStatus() != null && result.getStatus() == 202) {
            System.out.println("Task still running, poll again later");
        }
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
taskId
任务 ID（单个）
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
userId
用户身份识别，当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份
String
否
返回值说明
HTTP 状态码：200，查询成功。
字段
说明
类型
taskId
任务 ID
String
taskType
任务类型：batchMove（批量移动）、batchCopy（批量复制）、batchDelete（批量删除）、batchRestoreRecycle（批量恢复回收站）、convertFile（文档转码）、calibrateDirectoryStats（目录统计校准）、videoTranscode（视频转码）、fileUncompress（文件解压）
String
status
任务状态：202 处理中、200 成功、207 部分成功、400 全部失败、500 失败
Integer
各任务类型的结果字段
任务类型
结果字段
说明
batchMove
batchMoveResults
数组，每项含 status、code、from、to、path、moveAuthority
batchCopy
batchCopyResults
数组，每项含 status、code、copyFromLibraryId、copyFromSpaceId、copyFrom、path、to
batchDelete
batchDeleteResults
数组，每项含 status、code、path、recycledItemId
batchRestoreRecycle
batchRestoreRecycleResults
数组，每项含 status、code、recycledItemId、path、message
convertFile
convertFileResult
对象，含 status、code、convertFrom、path、srcInode、dstInode
calibrateDirectoryStats
calibrateDirectoryStatsResult
对象，含 status、code
videoTranscode
videoTranscodeResult
对象，视频转码结果
fileUncompress
fileUncompressResult
对象，含 outputDir、fileCount、successCount、failedCount、failedItems（key/code/err）、failedItemsTruncated、code、err

查询媒体库任务接口 V2

功能说明
queryLibraryTaskV2 用于查询媒体库级别的异步任务（如清空历史版本）的执行状态和结果，无需指定空间 ID。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.TaskApi;
import com.tencent.cloud.smh.model.QueryLibraryTaskV2200Response;

try {
    TaskApi.APIQueryLibraryTaskV2Request request = TaskApi.APIQueryLibraryTaskV2Request.newBuilder()
        .libraryId("your-library-id")
        .taskId("12345")
        .accessToken("your-access-token")
        .build();

    ApiResponse<Object> apiResponse = client.task().queryLibraryTaskV2WithHttpInfo(request);

    if (apiResponse.getStatusCode() == 200) {
        QueryLibraryTaskV2200Response result = (QueryLibraryTaskV2200Response) apiResponse.getData();
        System.out.println("Task type: " + result.getTaskType());
        System.out.println("Status: " + result.getStatus());
        if (result.getClearLibraryHistoryResult() != null) {
            System.out.println("Deleted: "
                + result.getClearLibraryHistoryResult().getDeleteCount());
        }
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
taskId
任务 ID（单个）
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
userId
用户身份识别
String
否
返回值说明
HTTP 状态码：200，查询成功。
字段
说明
类型
taskId
任务 ID
String
taskType
任务类型：clearLibraryHistory（清空历史版本）
String
status
任务状态：202 处理中、200 成功、500 失败
Integer
clearLibraryHistoryResult
清空历史版本结果，含 status、code、deleteCount（已删除的历史版本数量）
Object

查询任务接口（V1）

功能说明
queryTask 用于查询指定空间内一个或多个异步任务的状态，taskId 支持逗号分隔批量查询。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.TaskApi;
import com.tencent.cloud.smh.model.QueryTask200ResponseInner;
import java.util.List;

try {
    TaskApi.APIQueryTaskRequest request = TaskApi.APIQueryTaskRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .taskIdList("12345,12346") // 多个任务 ID 用英文逗号分隔
        .accessToken("your-access-token")
        .userId("user-id")
        .build();

    ApiResponse<Object> apiResponse = client.task().queryTaskWithHttpInfo(request);

    if (apiResponse.getStatusCode() == 200) {
        @SuppressWarnings("unchecked")
        List<QueryTask200ResponseInner> tasks = (List<QueryTask200ResponseInner>) apiResponse.getData();
        for (var task : tasks) {
            System.out.println("Task " + task.getTaskId() + " status: " + task.getStatus());
            // status：202 进行中，200 成功有结果，204 成功无结果，500 失败
        }
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
taskIdList
任务 ID 列表，多个任务 ID 使用英文逗号（,）分隔
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
userId
用户身份识别
String
否
返回值说明
HTTP 状态码：200，查询成功，返回任务数组。
字段
说明
类型
taskId
任务 ID
Long
status
任务状态：202 进行中、200 成功有结果、204 成功无结果、500 失败
Integer
result
任务结果，结构随任务类型而不同
Object

查询媒体库任务接口（V1）

功能说明
queryLibraryTask 用于查询媒体库级别的异步任务状态，taskId 支持逗号分隔批量查询，无需指定空间 ID。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.TaskApi;
import com.tencent.cloud.smh.model.QueryLibraryTask200ResponseInner;
import java.util.List;

try {
    TaskApi.APIQueryLibraryTaskRequest request = TaskApi.APIQueryLibraryTaskRequest.newBuilder()
        .libraryId("your-library-id")
        .taskIdList("12345")
        .accessToken("your-access-token")
        .build();

    ApiResponse<Object> apiResponse = client.task().queryLibraryTaskWithHttpInfo(request);

    if (apiResponse.getStatusCode() == 200) {
        @SuppressWarnings("unchecked")
        List<QueryLibraryTask200ResponseInner> tasks = (List<QueryLibraryTask200ResponseInner>) apiResponse.getData();
        for (var task : tasks) {
            System.out.println("Task " + task.getTaskId() + " status: " + task.getStatus());
        }
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
taskIdList
任务 ID 列表，多个任务 ID 使用英文逗号（,）分隔
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
userId
用户身份识别
String
否
返回值说明
HTTP 状态码：200，查询成功，返回任务数组。字段同「查询任务接口（V1）」：taskId（Long）、status（202 进行中 / 200 成功有结果 / 204 成功无结果 / 500 失败）、result（Object）。
中国站