相关资源
智能媒资托管 SMH 的 Go SDK 源码:源码快速下载
产品文档:SMH 产品文档
控制台:SMH 控制台
环境配置与准备
Golang:用于下载和安装 Go 编译运行环境,请前往 Golang 官网 进行下载。
最低支持的 Go 版本为1.21,推荐使用最新稳定版。
登录 智能媒资托管控制台,开通 SMH 服务并创建媒体库。获取媒体库 ID(libraryId)和专属域名(basePath)。

安装 SDK
go get cnb.cool/tencent/cloud/smh/smh-go-sdk
初始化 SMH 服务
引入 SDK
client "cnb.cool/tencent/cloud/smh/smh-go-sdk"
初始化 SMH 服务
package mainimport ("context"client "cnb.cool/tencent/cloud/smh/smh-go-sdk")func main() {cfg := client.NewConfiguration()// 设置专属域名(必须),请将 URL 替换为您在控制台获取的专属访问域名cfg.Servers = client.ServerConfigurations{{URL: "https://smhxxx.api.tencentsmh.cn", // 替换为您的专属域名Description: "SMH API Server",},}apiClient := client.NewAPIClient(cfg)}
生成访问令牌
// 生成访问令牌ctx := context.Background()tokenResp, httpRes, err := apiClient.TokenAPI.CreateToken(ctx).LibraryId("your-library-id"). // 媒体库 ID,在媒体托管控制台创建媒体库后获取LibrarySecret("your-library-secret"). // 媒体库密钥,在媒体托管控制台创建媒体库后获取SpaceId("your-space-id").UserId("user-id").Execute()if err != nil {panic(err)}
请求参数
请求参数 | 描述 | 类型 | 是否必选 |
LibraryId | String | 是 | |
LibrarySecret | String | 是 | |
SpaceId | 空间 ID,可同时指定多个空间 ID,使用英文逗号(,)分隔 | String | 如果媒体库为单租户模式,则无需指定该参数 如果媒体库为多租户模式,当需要操作租户空间时,无需指定该参数。当进行其他操作时,若授予管理员权限则该参数为可选,否则必须指定该参数 |
UserId | 用户身份识别,由业务后台自行控制 | String | 否 |
ClientId | 客户端识别,由业务后台自行控制 | String | 否 |
SessionId | SessionId,由业务后台自行控制 | String | 否 |
Period | 令牌有效时长及每次使用令牌后自动续期的有效时长,可选参数,单位为秒,有效值为正整数,传入其他值将使用默认值 86400(24小时),传入小于 300 的值将自动使用最小值 300(5 分钟),传入大于 315360000 的值将自动使用最大值 315360000(10 年) | int32 | 否 |
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 续期逻辑:
// Token 续期函数func renewToken(ctx context.Context, smhClient *client.APIClient, libraryId string, accessToken string) (string, error) {resp, _, err := smhClient.TokenAPI.RenewToken(ctx, libraryId, accessToken).Execute()if err != nil {return "", err}if resp != nil && resp.AccessToken != nil {return *resp.AccessToken, nil}return "", fmt.Errorf("renew token failed")}
注意:
建议在业务逻辑中提前进行续期以避免请求失败。
删除访问令牌
令牌不再需要时可主动删除使其立即失效:
// 删除指定访问令牌(立即失效)_, err := apiClient.TokenAPI.DeleteToken(ctx, "your-library-id", "your-access-token").Execute()if err != nil {panic(err)}// 删除特定用户的全部访问令牌(需要媒体库密钥,可选 ClientId/SessionId 进一步限定范围)_, err = apiClient.TokenAPI.DeleteUserTokens(ctx, "your-library-id").LibrarySecret("your-library-secret").UserId("user-id").Execute()if err != nil {panic(err)}
两个接口成功均返回 HTTP 204,无响应体。
快速开始示例
使用 API
完成初始化和令牌获取后,即可调用各种 API 进行文件操作。
说明:
Go SDK 没有客户端级别的令牌注入机制,访问令牌通过每次调用的
AccessToken(...) 方法以 query 参数传递;同理 LibraryId/SpaceId 也需在每次调用时显式传入(作为路径参数)。ctx := context.Background()resp, httpRes, err := apiClient.FileAPI.InfoFile(ctx, "your-library-id", "your-space-id", "/test.txt").AccessToken("your-access-token").UserId("user-id").Info(1).ContentDisposition("inline").Execute()if err != nil {panic(err)}fmt.Printf("File info: %s, Size: %s\\n", *resp.CosUrl, *resp.Size)