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

快速入门

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

相关资源

Java SDK 源码:源码快速下载
产品文档:SMH 产品文档
控制台:SMH 控制台

环境配置与准备

运行环境需 JDK 11 及以上版本。
登录 智能媒资托管控制台,开通 SMH 服务并创建媒体库。获取媒体库 ID(libraryId)和专属域名。


安装 SDK

Maven
Gradle
<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
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
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());
}