智能媒资托管回收站管理

前期准备
开始操作前，确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK，请先参考快速入门文档完成。
注意：
若您使用回收站管理功能，需要具有相应空间的读权限。
恢复回收站项目需要 admin、space_admin 或 restore_recycled 权限。
永久删除回收站项目需要 admin、space_admin 或 delete_recycled 权限。
清空回收站时，回收站内的文件将首先在回收站内不可见，删除和释放空间的操作将异步执行。
列出回收站项目（marker 翻页，推荐）
recycleList 实现查看回收站列表，使用 marker/limit 方式进行分页，推荐使用。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
import com.tencent.cloud.smh.model.RecycleList200Response;
﻿
try {
    RecycledApi.APIRecycleListRequest request = RecycledApi.APIRecycleListRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .byMarker(1)
        .limit(10)
        .orderBy("removalTime")
        .orderByType("desc")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recycleListWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        RecycleList200Response result = (RecycleList200Response) apiResponse.getData();
        for (var item : result.getContents()) {
            System.out.println("Item: " + item.getName() + ", Remaining days: " + item.getRemainingTime());
        }
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
marker
用于顺序列出分页的标识
String
否
limit
分页限制，取值范围 [1, 100]，默认20
Integer
否
orderBy
排序字段：name（按名称）、modificationTime（按修改时间）、size（按大小）、removalTime（按删除时间）、remainingTime（按剩余时间）
String
否
orderByType
排序方式：asc 升序，desc 降序
String
否
返回值说明
HTTP 状态码：200，获取成功，返回回收站项目列表。
响应字段说明
字段
说明
类型
nextMarker
用于顺序列出分页的标识，为空表示已翻页完毕
String
contents
回收站项目列表
Array
contents 数组元素说明
字段
说明
类型
recycledItemId
回收站 ID
Long
originalPath
原始路径
Array
spaceId
空间 ID
String
size
文件大小，字符串格式
String
previewByDoc
是否可通过 WPS 预览
Boolean
previewByCI
是否可通过万象预览
Boolean
previewAsIcon
是否可用预览图当做 icon
Boolean
fileType
文件类型
String
name
文件名
String
type
条目类型：dir、file、image、video
String
creationTime
创建时间
String
modificationTime
修改时间
String
removalTime
删除时间
String
remainingTime
剩余天数
Integer
列出回收站项目（page 翻页，不推荐）
recycleListByPage 使用传统分页方式查看回收站列表，不建议深翻页。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
import com.tencent.cloud.smh.model.RecycleListByPage200Response;
﻿
try {
    RecycledApi.APIRecycleListByPageRequest request = RecycledApi.APIRecycleListByPageRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .byPage(1)
        .page(1)
        .pageSize(20)
        .orderBy("name")
        .orderByType("asc")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recycleListByPageWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        RecycleListByPage200Response result = (RecycleListByPage200Response) apiResponse.getData();
        System.out.println("Total: " + result.getTotalNum());
        for (var item : result.getContents()) {
            System.out.println("Item: " + item.getName() + ", Remaining days: " + item.getRemainingTime());
        }
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
page
页码，默认1
Integer
否
pageSize
每页数量，取值范围 [1, 100]，默认20
Integer
否
orderBy
排序字段：name（按名称）、modificationTime（按修改时间）、size（按大小）、removalTime（按删除时间）、remainingTime（按剩余时间）
String
否
orderByType
排序方式：asc 升序，desc 降序
String
否
返回值说明
HTTP 状态码：200，获取成功。
响应字段说明
字段
说明
类型
totalNum
回收站所有文件和文件夹总数
Integer
contents
回收站项目列表
Array
查看回收站文件详情
recycleInfo 实现获取回收站项目的详细信息。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
import com.tencent.cloud.smh.model.RecycleInfo200Response;
import java.math.BigDecimal;
﻿
try {
    RecycledApi.APIRecycleInfoRequest request = RecycledApi.APIRecycleInfoRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .recycledItemId(12345L)
        .accessToken("your-access-token")
        .info(BigDecimal.ONE)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recycleInfoWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        RecycleInfo200Response result = (RecycleInfo200Response) apiResponse.getData();
        System.out.println("Type: " + result.getType());
        System.out.println("Size: " + result.getSize());
        System.out.println("COS URL: " + result.getCosUrl());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
recycledItemId
回收站项目 ID
Long
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
info
获取文件详情，固定值为 1
BigDecimal
是
返回值说明：
HTTP 状态码：200，获取成功，返回文件详情（包含 cosUrl、contentType、size、crc64、metaData、labels 等字段）。
预览回收站项目
recyclePreview 实现预览回收站中的文档、图片、视频等文件。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
import java.math.BigDecimal;
﻿
try {
    RecycledApi.APIRecyclePreviewRequest request = RecycledApi.APIRecyclePreviewRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .recycledItemId(12345L)
        .accessToken("your-access-token")
        .preview(BigDecimal.ONE)
        .size(800)
        .build();
﻿
    // 默认自动跟随重定向时，响应体为文件内容；如需获取预览 URL，先关闭自动跟随
    client.setFollowRedirects(java.net.http.HttpClient.Redirect.NEVER);
    client.recycled().recyclePreviewWithHttpInfo(request);
} catch (ApiException e) {
    if (e.getCode() == 302) {
        String previewUrl = e.getResponseHeaders().firstValue("Location").orElse("");
        System.out.println("Preview URL: " + previewUrl);
    } else {
        System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
    }
} finally {
    // 恢复默认重定向策略，避免影响该 client 的后续调用
    client.setFollowRedirects(java.net.http.HttpClient.Redirect.NORMAL);
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
recycledItemId
回收站项目 ID
Long
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
preview
预览标志，固定值为1
BigDecimal
是
type
文档预览方式，pic 以 JPG 格式预览，否则以 HTML 格式
String
否
size
图片或视频封面的缩放大小
Integer
否
scale
等比例缩放百分比
Integer
否
widthSize
缩放宽度
Integer
否
heightSize
缩放高度
Integer
否
frameNumber
gif 文件降帧的帧数
Integer
否
返回值说明：
服务端返回 HTTP 302，通过 Location 响应头重定向到可直接用于展示或下载的文件 URL。SDK 默认自动跟随重定向（followRedirects=NORMAL），此时响应体为文件内容本身；如需获取 URL，请先调用 client.setFollowRedirects(HttpClient.Redirect.NEVER) 关闭自动跟随，再从响应头 Location 读取（此时接口按非 2xx 抛出 ApiException，从其 getResponseHeaders() 中取 Location）。
恢复指定回收站项目
recycleRestore 实现恢复指定回收站项目。需要 admin、space_admin 或 restore_recycled 权限。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
import com.tencent.cloud.smh.model.RecycleRestore200Response;
import java.math.BigDecimal;
﻿
try {
    RecycledApi.APIRecycleRestoreRequest request = RecycledApi.APIRecycleRestoreRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .recycledItemId(12345L)
        .accessToken("your-access-token")
        .restore(BigDecimal.ONE)
        .conflictResolutionStrategy("rename")
        .restorePathStrategy("fallbackToRoot")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recycleRestoreWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        RecycleRestore200Response result = (RecycleRestore200Response) apiResponse.getData();
        System.out.println("Item restored to: " + result.getPath());
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
recycledItemId
回收站项目 ID
Long
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
restore
恢复标志，固定值为 1
BigDecimal
是
conflictResolutionStrategy
路径冲突处理方式：ask、rename、overwrite
String
否
restorePathStrategy
恢复路径策略：originalPath、fallbackToRoot
String
否
返回值说明：
HTTP 状态码：200，恢复成功，返回最终文件路径。
批量恢复回收站项目
recycleRestoreBatch 实现批量恢复回收站项目。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
import com.tencent.cloud.smh.model.RecycleRestoreBatch200Response;
import com.tencent.cloud.smh.model.RecycleRestoreBatch202Response;
import com.tencent.cloud.smh.model.RecycleRestoreBatch207Response;
import java.math.BigDecimal;
import java.util.List;
﻿
try {
    RecycledApi.APIRecycleRestoreBatchRequest request = RecycledApi.APIRecycleRestoreBatchRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .restore(BigDecimal.ONE)
        .restorePathStrategy("fallbackToRoot")
        .recycleRestoreBatchRequest(List.of(12345L, 67890L))
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recycleRestoreBatchWithHttpInfo(request);
    int statusCode = apiResponse.getStatusCode();
﻿
    if (statusCode == 200) {
        RecycleRestoreBatch200Response result = (RecycleRestoreBatch200Response) apiResponse.getData();
        for (var item : result.getResult()) {
            System.out.println("Item " + item.getRecycledItemId() + " status: " + item.getStatus());
        }
    } else if (statusCode == 202) {
        RecycleRestoreBatch202Response result = (RecycleRestoreBatch202Response) apiResponse.getData();
        System.out.println("Async task accepted, taskId: " + result.getTaskId());
    } else if (statusCode == 207) {
        RecycleRestoreBatch207Response result = (RecycleRestoreBatch207Response) apiResponse.getData();
        System.out.println("Partial success, details: " + result);
    }
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
restore
恢复标志，固定值为1
BigDecimal
是
restorePathStrategy
恢复路径策略：originalPath、fallbackToRoot
String
否
requestBody
回收站项目 ID 列表
List<Long>
是
返回值说明
HTTP 状态码200：同步恢复全部成功。
HTTP 状态码202：异步方式恢复，返回 taskId。
HTTP 状态码207：部分或全部执行失败。
永久删除指定回收站项目
recyclePurge 实现永久删除指定回收站项目。删除后无法恢复。需要 admin、space_admin 或 delete_recycled 权限。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
﻿
try {
    RecycledApi.APIRecyclePurgeRequest request = RecycledApi.APIRecyclePurgeRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .recycledItemId(12345L)
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recyclePurgeWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
    System.out.println("Item permanently deleted");
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
recycledItemId
回收站项目 ID
Long
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
返回值说明：
HTTP 状态码：204，删除成功，无响应体。
批量永久删除回收站项目
recyclePurgeBatch 实现批量永久删除回收站项目。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
import java.math.BigDecimal;
import java.util.List;
﻿
try {
    RecycledApi.APIRecyclePurgeBatchRequest request = RecycledApi.APIRecyclePurgeBatchRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .delete(BigDecimal.ONE)
        .recyclePurgeBatchRequest(List.of(12345L, 67890L))
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recyclePurgeBatchWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
    System.out.println("Items permanently deleted");
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
delete
永久删除标志，固定值为1
BigDecimal
是
requestBody
回收站项目 ID 列表
List<Long>
是
返回值说明：
HTTP 状态码：204，删除成功，无响应体。
设置回收站生命周期
recycleSetLifecycle 实现设置回收站生命周期。
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
import com.tencent.cloud.smh.model.RecycleSetLifecycleRequest;
import java.math.BigDecimal;
﻿
RecycleSetLifecycleRequest lifecycleBody = new RecycleSetLifecycleRequest();
lifecycleBody.setRetentionDays(30);
﻿
try {
    RecycledApi.APIRecycleSetLifecycleRequest request = RecycledApi.APIRecycleSetLifecycleRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .lifecycle(BigDecimal.ONE)
        .recycleSetLifecycleRequest(lifecycleBody)
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recycleSetLifecycleWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
    System.out.println("Lifecycle set successfully");
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明：
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
lifecycle
设置回收站生命周期标志，固定值为1
BigDecimal
是
recycleSetLifecycleRequest
生命周期设置对象
RecycleSetLifecycleRequest
是
recycleSetLifecycleRequest 对象说明
字段
参数描述
类型
是否必填
retentionDays
回收站保留天数，取值范围：0 < retentionDays ≤ 10000
Integer
是
返回值说明
HTTP 状态码：204，修改成功，无响应体。
清空回收站
recycleEmpty 实现清空回收站。回收站内的文件将首先在回收站内不可见，删除和释放空间的操作将异步执行。
警告：
清空回收站后，回收站内的所有文件将被永久删除，无法恢复，请谨慎操作！
import com.tencent.cloud.smh.ApiException;
import com.tencent.cloud.smh.ApiResponse;
import com.tencent.cloud.smh.api.RecycledApi;
﻿
try {
    RecycledApi.APIRecycleEmptyRequest request = RecycledApi.APIRecycleEmptyRequest.newBuilder()
        .libraryId("your-library-id")
        .spaceId("your-space-id")
        .accessToken("your-access-token")
        .build();
﻿
    ApiResponse<Object> apiResponse = client.recycled().recycleEmptyWithHttpInfo(request);
    System.out.println("Status code: " + apiResponse.getStatusCode());
    System.out.println("Recycle bin emptied");
} catch (ApiException e) {
    System.err.println("Error: " + e.getCode() + " - " + e.getMessage());
}
参数说明
参数名
参数描述
类型
是否必填
libraryId
媒体库 ID
String
是
spaceId
空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数
String
是
accessToken
访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一
String
否
返回值说明
HTTP 状态码：204，删除成功，无响应体。
参数名	参数描述	类型	是否必填
libraryId	媒体库 ID	String	是
spaceId	空间 ID，如果媒体库为单租户模式，则该参数固定为连字符(-)；如果媒体库为多租户模式，则必须指定该参数	String	是
accessToken	访问令牌；对于公有读媒体库或租户空间可不指定，否则需通过本参数传入或提前调用 client.withToken() 注入，二者取一	String	否
marker	用于顺序列出分页的标识	String	否
limit	分页限制，取值范围 [1, 100]，默认20	Integer	否
orderBy	排序字段：name（按名称）、modificationTime（按修改时间）、size（按大小）、removalTime（按删除时间）、remainingTime（按剩余时间）	String	否
orderByType	排序方式：asc 升序，desc 降序	String	否
字段	说明	类型
nextMarker	用于顺序列出分页的标识，为空表示已翻页完毕	String
contents	回收站项目列表	Array
回收站管理

本页目录：

前期准备

列出回收站项目（marker 翻页，推荐）

列出回收站项目（page 翻页，不推荐）

查看回收站文件详情

预览回收站项目

恢复指定回收站项目

批量恢复回收站项目

永久删除指定回收站项目

批量永久删除回收站项目

设置回收站生命周期

清空回收站
