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

快速入门

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

相关资源

智能媒资托管 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 main

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