相关资源
Java SDK 源码:源码快速下载
产品文档:SMH 产品文档
控制台:SMH 控制台
环境配置与准备
运行环境需 JDK 11 及以上版本。
登录 智能媒资托管控制台,开通 SMH 服务并创建媒体库。获取媒体库 ID(libraryId)和专属域名。

安装 SDK
<dependency><groupId>com.qcloud.smh</groupId><artifactId>smh-java-sdk</artifactId><version>1.1.0</version></dependency>
dependencies {implementation 'com.qcloud.smh:smh-java-sdk:1.1.0'}
初始化 SMH 服务
调用方式建议:推荐使用
xxxWithHttpInfo 方法SDK 的每个 REST 接口都会同时生成两种调用方式:
xxx(request):直接返回业务数据对象,使用简单,但无法获取 HTTP 状态码和响应头。xxxWithHttpInfo(request):返回 ApiResponse<T> 包装对象,可通过 getStatusCode()、getHeaders()、getData() 分别获取状态码、响应头和响应体。引入 SDK
import com.tencent.cloud.smh.SmhClient;import com.tencent.cloud.smh.ApiException;import com.tencent.cloud.smh.api.TokenApi;import com.tencent.cloud.smh.api.FileApi;import com.tencent.cloud.smh.model.*;import java.math.BigDecimal;
初始化 SmhClient
// 创建 SMH 客户端,设置专属域名(必须)SmhClient client = new SmhClient("https://smhxxx.api.tencentsmh.cn");
说明:
SmhClient 不会自动注入 libraryId、spaceId、accessToken 的默认值,每次调用 API 都需要显式传入 libraryId 和 spaceId。访问令牌有两种使用方式:调用
client.withToken(accessToken) 后由 SDK 自动携带 Authorization: Bearer 头(推荐);或在每次调用时通过 accessToken 参数单独传入。生成访问令牌
// 生成访问令牌SmhClient client = new SmhClient("https://smhxxx.api.tencentsmh.cn");try {// 构建创建令牌请求TokenApi.APICreateTokenRequest request = TokenApi.APICreateTokenRequest.newBuilder().libraryId("your-library-id") // 媒体库 ID,在媒体托管控制台创建媒体库后获取.librarySecret("your-library-secret") // 媒体库密钥,在媒体托管控制台创建媒体库后获取.spaceId("your-space-id") // 空间 ID(可选).userId("user-id") // 用户身份识别(可选).build();// 获取访问令牌(WithHttpInfo 返回 ApiResponse<Object>,需强转)CreateToken200Response tokenResp = (CreateToken200Response) client.token().createTokenWithHttpInfo(request).getData();String accessToken = tokenResp.getAccessToken();System.out.println("Access Token: " + accessToken);System.out.println("Expires In: " + tokenResp.getExpiresIn() + " seconds");// 将令牌注入客户端,后续调用自动携带 Authorization: Bearer 头client.withToken(accessToken);} catch (ApiException e) {System.err.println("获取令牌失败: " + e.getCode() + " - " + e.getMessage());}
请求参数
请求参数 | 描述 | 类型 | 是否必选 |
libraryId | String | 是 | |
librarySecret | String | 是 | |
spaceId | 空间 ID,可同时指定多个空间 ID,使用英文逗号(,)分隔 | String | 如果媒体库为单租户模式,则无需指定该参数
如果媒体库为多租户模式,当需要操作租户空间时,无需指定该参数。当进行其他操作时,若授予管理员权限则该参数为可选,否则必须指定该参数 |
userId | 用户身份识别,由业务后台自行控制 | String | 否 |
clientId | 客户端识别,由业务后台自行控制 | String | 否 |
sessionId | SessionId,由业务后台自行控制 | String | 否 |
period | 令牌有效时长及每次使用令牌后自动续期的有效时长,可选参数,单位为秒,有效值为正整数,传入其他值将使用默认值 86400(24小时),传入小于 300 的值将自动使用最小值 300(5 分钟),传入大于 315360000 的值将自动使用最大值 315360000(10 年) | Integer | 否 |
grant | 授予的权限,如为空则只授予读取权限,可指定此参数在只读基础上同时附加下述多个权限项,并使用英文逗号(,)分隔,例如:create_directory,upload_file | String | 否 |
以下是 Grant 参数支持的权限项:
权限项 | 描述 |
admin | 管理员权限,授予所有权限 |
create_space | 拥有创建租户空间权限 |
delete_space | 拥有删除租户空间权限 |
space_admin | 租户空间管理员权限,拥有除租户空间操作以外的所有权限 |
create_directory | 拥有创建目录或相簿权限 |
delete_directory | 拥有删除目录或相簿权限(未开启回收站)/将目录或相簿移入回收站权限(开启回收站) |
delete_directory_permanent | 开启回收站时,拥有永久删除目录或相簿权限 |
move_directory | 拥有重命名或移动目录或相簿权限 |
copy_directory | 拥有复制目录或相簿权限 |
upload_file | 拥有上传文件权限,但不允许覆盖已有文件 |
upload_file_force | 拥有上传文件权限,且允许覆盖已有文件 |
begin_upload | 拥有开始上传文件权限,但不允许覆盖已有文件 |
begin_upload_force | 拥有开始上传文件权限,且允许覆盖已有文件 |
confirm_upload | 拥有完成上传文件权限;将开始上传与完成上传权限分离,主要用于业务前后端权限的分离,使完成上传必须经过业务后端;如果同时需要开始上传和完成上传权限,可简单指定 upload_file 或 upload_file_force |
create_symlink | 拥有创建符号链接权限,但不允许覆盖已有文件或符号链接 |
create_symlink_force | 拥有创建符号链接权限,且允许覆盖已有文件或符号链接 |
delete_file | 拥有删除文件权限(未开启回收站)/将文件移入回收站权限(开启回收站) |
delete_file_permanent | 开启回收站时,拥有永久删除文件权限 |
move_file | 拥有重命名或移动文件权限,但不允许覆盖已有文件 |
move_file_force | 拥有重命名或移动文件权限,且允许覆盖已有文件 |
copy_file | 拥有复制文件权限,但不允许覆盖已有文件 |
copy_file_force | 拥有复制文件权限,且允许覆盖已有文件 |
delete_recycled | 拥有删除回收站项目权限 |
restore_recycled | 拥有恢复回收站项目权限 |
set_history_latest | 拥有将某个历史版本设置为最新版本权限 |
delete_history | 拥有删除历史版本权限 |
Access Token 续期
Token 有效期(默认 24 小时),过期后需要重新获取。建议在业务代码中实现 Token 续期逻辑:
// 构建续期令牌请求TokenApi.APIRenewTokenRequest request = TokenApi.APIRenewTokenRequest.newBuilder().libraryId("your-library-id").accessToken("your-access-token") // 待续期的访问令牌.build();try {CreateToken200Response resp = (CreateToken200Response) client.token().renewTokenWithHttpInfo(request).getData();if (resp != null && resp.getAccessToken() != null) {System.out.println("Token renewed: " + resp.getAccessToken());System.out.println("Expires in: " + resp.getExpiresIn() + " seconds");// 将新 Token 设置到客户端中继续使用client.withToken(resp.getAccessToken());}} catch (ApiException e) {System.err.println("续期失败: " + e.getCode() + " - " + e.getMessage());}
注意:
建议在业务逻辑中提前进行续期以避免请求失败。
删除访问令牌
令牌不再需要时可主动删除使其立即失效:
// 删除指定访问令牌(立即失效)TokenApi.APIDeleteTokenRequest delRequest = TokenApi.APIDeleteTokenRequest.newBuilder().libraryId("your-library-id").accessToken("your-access-token").build();client.token().deleteTokenWithHttpInfo(delRequest);// 删除特定用户的全部访问令牌(需要媒体库密钥,可选 clientId/sessionId 进一步限定范围)TokenApi.APIDeleteUserTokensRequest delUserRequest = TokenApi.APIDeleteUserTokensRequest.newBuilder().libraryId("your-library-id").librarySecret("your-library-secret").userId("user-id").build();client.token().deleteUserTokensWithHttpInfo(delUserRequest);
两个接口成功均返回 HTTP 204,无响应体。
快速开始示例
使用 API
完成初始化和令牌获取后,即可调用各种 API 进行文件操作:
try {// 构建获取文件信息请求(info 为固定标识参数,传 1 即可)FileApi.APIInfoFileRequest infoRequest = FileApi.APIInfoFileRequest.newBuilder().libraryId("your-library-id").spaceId("your-space-id").filePath("/path/to/file.txt").info(BigDecimal.ONE).build();// WithHttpInfo 返回 ApiResponse<Object>,getData() 需强转为对应响应类型InfoFile200Response response = (InfoFile200Response) client.file().infoFileWithHttpInfo(infoRequest).getData();System.out.println("媒体类型: " + response.getContentType());System.out.println("文件大小: " + response.getSize());} catch (ApiException e) {System.err.println("API 错误: " + e.getCode() + " - " + e.getMessage());}