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

批量操作

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

本页目录：

前期准备

开始操作前，确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK，请先参考快速入门文档完成。
注意事项：
批量接口可能返回200（全部同步完成）、202（已受理为异步任务，返回 taskId，需通过任务管理接口轮询）或207（部分成功）三种状态码。
简便方法（如 client.batch().batchCopy(...)）会按 200 响应类型强转，当服务端实际返回 202/207 时会抛出 ClassCastException。批量接口请务必使用 xxxWithHttpInfo 方法，先判断 getStatusCode() 再强转响应体。
批量元素单项处理结果通过响应 result 数组中每一项的 status 字段判断：批量复制/移动中，200表示重命名（rename）成功、204表示成功（ask 或 overwrite）；批量删除中，200表示移入回收站成功、204表示永久删除成功；403/404/409/500等表示该项失败。

批量复制

功能说明
batchCopy 用于批量复制目录或文件，支持跨空间复制。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.BatchApi;
import com.tencent.cloud.smh.model.BatchCopyRequestInner;
import com.tencent.cloud.smh.model.BatchCopy200Response;
import com.tencent.cloud.smh.model.BatchCopy202Response;
import com.tencent.cloud.smh.model.BatchCopy207Response;
import java.util.List;

List<BatchCopyRequestInner> copyItems = List.of(
    new BatchCopyRequestInner()
        .copyFrom("/documents/report.pdf")
        .to("/backup/report.pdf")
        .conflictResolutionStrategy(BatchCopyRequestInner.ConflictResolutionStrategyEnum.RENAME),
    new BatchCopyRequestInner()
        .copyFromSpaceId("source-space-id") // 跨空间复制时指定源空间
        .copyFrom("/images/photo.jpg")
        .to("/backup/photo.jpg")
);

try {
    BatchApi.APIBatchCopyRequest request = BatchApi.APIBatchCopyRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .copy(1)
        .accessToken("your-access-token")
        .userId("user-id")
        .batchCopyRequest(copyItems)
        .build();

    ApiResponse<Object> apiResponse = client.batch().batchCopyWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();

    if (statusCode == 200) {
        BatchCopy200Response result = (BatchCopy200Response) apiResponse.getData();
        for (var item : result.getResult()) {
            System.out.println("status: " + item.getStatus() + ", path: " + item.getPath());
        }
    } else if (statusCode == 202) {
        BatchCopy202Response result = (BatchCopy202Response) apiResponse.getData();
        System.out.println("Async task accepted, taskId: " + result.getTaskId());
        // 通过任务管理接口轮询任务执行结果
    } else if (statusCode == 207) {
        BatchCopy207Response result = (BatchCopy207Response) apiResponse.getData();
        System.out.println("Partial success, check each item status");
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
copy
固定值 1，表示批量复制操作
Integer
是
batchCopyRequest
批量复制请求数组
List<BatchCopyRequestInner>
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
userId
用户身份识别，当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份
String
否
BatchCopyRequestInner 对象说明
字段
参数描述
类型
是否必填
copyFrom
被复制的源文件或目录路径
String
是
to
复制的目标路径
String
是
copyFromSpaceId
跨空间复制时的源空间 ID，不跨空间时不传
String
否
conflictResolutionStrategy
冲突处理方式：ask（冲突时该项失败）、rename（自动重命名）、overwrite（覆盖）
String
否
返回值说明
HTTP 状态码
响应体类型
说明
200
BatchCopy200Response
全部同步完成，result 数组含每项的 status、path、copyFrom、to
202
BatchCopy202Response
已受理为异步任务，返回 taskId，需轮询任务状态
207
BatchCopy207Response
部分成功，result 数组含每项的 status，需逐项检查

批量移动（重命名）

功能说明
batchMove 用于批量重命名或移动目录或文件，支持跨空间移动。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.BatchApi;
import com.tencent.cloud.smh.model.BatchMoveRequestInner;
import com.tencent.cloud.smh.model.BatchMove200Response;
import com.tencent.cloud.smh.model.BatchMove202Response;
import com.tencent.cloud.smh.model.BatchMove207Response;
import java.util.List;

List<BatchMoveRequestInner> moveItems = List.of(
    new BatchMoveRequestInner()
        .from("/documents/old-name.pdf")
        .to("/documents/new-name.pdf"),
    new BatchMoveRequestInner()
        .from("/documents/report.pdf")
        .to("/archive/report.pdf")
        .conflictResolutionStrategy(BatchMoveRequestInner.ConflictResolutionStrategyEnum.RENAME)
);

try {
    BatchApi.APIBatchMoveRequest request = BatchApi.APIBatchMoveRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .move(1)
        .accessToken("your-access-token")
        .userId("user-id")
        .batchMoveRequest(moveItems)
        .build();

    ApiResponse<Object> apiResponse = client.batch().batchMoveWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();

    if (statusCode == 200) {
        BatchMove200Response result = (BatchMove200Response) apiResponse.getData();
        for (var item : result.getResult()) {
            System.out.println("status: " + item.getStatus() + ", path: " + item.getPath());
        }
    } else if (statusCode == 202) {
        BatchMove202Response result = (BatchMove202Response) apiResponse.getData();
        System.out.println("Async task accepted, taskId: " + result.getTaskId());
    } else if (statusCode == 207) {
        BatchMove207Response result = (BatchMove207Response) apiResponse.getData();
        System.out.println("Partial success, check each item status");
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
move
固定值1，表示批量移动操作
Integer
是
batchMoveRequest
批量移动请求数组
List<BatchMoveRequestInner>
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
userId
用户身份识别
String
否
BatchMoveRequestInner 对象说明
字段
参数描述
类型
是否必填
from
被重命名或移动的源文件或目录路径
String
是
to
移动的目标路径
String
是
fromSpaceId
跨空间移动时的源空间 ID，不跨空间时不传
String
否
conflictResolutionStrategy
冲突处理方式：ask、rename、overwrite
String
否
返回值说明
HTTP 状态码
响应体类型
说明
200
BatchMove200Response
全部同步完成，result 数组含每项的 status、path、from、to
202
BatchMove202Response
已受理为异步任务，返回 taskId，需轮询任务状态
207
BatchMove207Response
部分成功，result 数组含每项的 status，需逐项检查

批量删除

功能说明
batchDelete 用于批量删除目录或文件。媒体库开启回收站时，可选择移入回收站或永久删除。
使用示例
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.BatchApi;
import com.tencent.cloud.smh.model.BatchDeleteRequestInner;
import com.tencent.cloud.smh.model.BatchDelete200Response;
import com.tencent.cloud.smh.model.BatchDelete202Response;
import com.tencent.cloud.smh.model.BatchDelete207Response;
import java.util.List;

List<BatchDeleteRequestInner> deleteItems = List.of(
    new BatchDeleteRequestInner().path("/documents/old-report.pdf"),
    new BatchDeleteRequestInner().path("/temp/cache").permanent(true) // 永久删除
);

try {
    BatchApi.APIBatchDeleteRequest request = BatchApi.APIBatchDeleteRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .delete(1)
        .accessToken("your-access-token")
        .userId("user-id")
        .batchDeleteRequest(deleteItems)
        .build();

    ApiResponse<Object> apiResponse = client.batch().batchDeleteWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();

    if (statusCode == 200) {
        BatchDelete200Response result = (BatchDelete200Response) apiResponse.getData();
        for (var item : result.getResult()) {
            System.out.println("status: " + item.getStatus()
                + ", path: " + item.getPath()
                + ", recycledItemId: " + item.getRecycledItemId());
        }
    } else if (statusCode == 202) {
        BatchDelete202Response result = (BatchDelete202Response) apiResponse.getData();
        System.out.println("Async task accepted, taskId: " + result.getTaskId());
    } else if (statusCode == 207) {
        BatchDelete207Response result = (BatchDelete207Response) apiResponse.getData();
        System.out.println("Partial success, check each item status");
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
delete
固定值1，表示批量删除操作
Integer
是
batchDeleteRequest
批量删除请求数组
List<BatchDeleteRequestInner>
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
userId
用户身份识别
String
否
BatchDeleteRequestInner 对象说明
字段
参数描述
类型
是否必填
path
待删除的文件或目录路径
String
是
permanent
是否永久删除，true 为永久删除，false 或不传为移入回收站（需媒体库开启回收站）
Boolean
否
返回值说明
HTTP 状态码
响应体类型
说明
200
BatchDelete200Response
全部同步完成，result 数组含每项的 status、path、recycledItemId（移入回收站时返回）
202
BatchDelete202Response
已受理为异步任务，返回 taskId，需轮询任务状态
207
BatchDelete207Response
部分成功，result 数组含每项的 status，需逐项检查
中国站