smh-node-sdk

v1.0.0

Published

10 days ago

智能媒资托管 Node SDK

0High
0Medium
0Low

chrisscui

tencent tencent cloud qcloud smh smh-sdk

SMH Node SDK

腾讯云智能媒资托管（Smart Media Hosting，SMH）Node SDK，为开发者提供便捷的 Node.js 接口来访问和管理腾讯云 SMH 服务。

前提条件

Node.js 版本 >= 16.0.0
已开通腾讯云智能媒资托管服务
已获取媒体库 ID（libraryId）和媒体库密钥（librarySecret）

安装

使用 npm：

npm install smh-node-sdk

使用 yarn：

yarn add smh-node-sdk

使用 pnpm：

pnpm add smh-node-sdk

快速开始

1. 引入 SDK

// CommonJS
const { SMHClient } = require('smh-node-sdk');

// ES Module
import { SMHClient } from 'smh-node-sdk';

2. 初始化 SMHClient

方式一：服务端直接使用（推荐）

服务端可以安全地保存 librarySecret，因此推荐在服务端通过 SDK 创建访问令牌：

const smh = new SMHClient({
    basePath: 'https://smhxxx.api.tencentsmh.cn', // 专属域名（推荐）
});

// 创建访问令牌
const tokenResponse = await smh.token.createToken({
    libraryId: 'your-library-id',
    librarySecret: 'your-library-secret',
    spaceId: 'your-space-id',
    userId: 'your-user-id',
    clientId: `client-${Date.now()}`,
    sessionId: `session-${Date.now()}`,
    grant: 'admin',
    period: 3600
});

const accessToken = tokenResponse.data.accessToken;
console.log('访问令牌创建成功:', accessToken);

// 设置默认参数
smh.setDefaultAccessToken(accessToken);
smh.setDefaultLibraryId('your-library-id');
smh.setDefaultSpaceId('your-space-id');

方式二：已有 accessToken 时直接传入

如果已有 accessToken、libraryId、spaceId 等信息（例如从其他服务获取），可以在初始化时直接传入：

const smh = new SMHClient({
    basePath: 'https://smhxxx.api.tencentsmh.cn', // 专属域名（推荐）
    accessToken: 'your-access-token',
    libraryId: 'your-library-id',
    spaceId: 'your-space-id',
    maxRetries: 3, // 可选，请求失败重试次数
});

basePath 专属域名获取方式：在腾讯云智能媒资托管控制台创建媒体库后，控制台会展示为您生成的专属域名（如 smhxxx.api.tencentsmh.cn）。强烈建议将 basePath 设置为您的专属域名，以获得更好的访问性能和稳定性。

这样初始化后，后续调用 API 时无需每次都传入这些参数，SDK 会自动注入。

3. AccessToken 续期

accessToken 有有效期限制（默认 24 小时），过期后需要调用 renewToken 进行续期：

// 检查 token 是否即将过期，如过期则续期
const renewResponse = await smh.token.renewToken({
      libraryId: libraryId,
      accessToken: accessToken,
  });
  
  const newAccessToken = renewResponse.data.accessToken;
  const newExpiresIn = renewResponse.data.expiresIn;
  
  // 更新默认 accessToken
  smh.setDefaultAccessToken(newAccessToken);
  
  console.log('Token 续期成功，新的有效期:', newExpiresIn, '秒');

注意：建议在业务逻辑中提前进行续期以避免请求失败。

4. 使用 API

// 列出目录内容
const contents = await smh.directory.listDirectory({
    spaceId: 'your-space-id',
    filePath: '/',
    page: 1,
    pageSize: 20
});

console.log('目录内容:', contents.data);

API 参数说明

createToken 参数

| 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | libraryId | string | 是 | 媒体库 ID，在媒体托管控制台创建媒体库后获取 | | librarySecret | string | 是 | 媒体库密钥，在媒体托管控制台创建媒体库后获取 | | spaceId | string | 否 | 空间 ID，可同时指定多个空间 ID，使用英文逗号（,）分隔 | | userId | string | 否 | 用户身份识别，由业务后台自行控制 | | clientId | string | 否 | 客户端识别，由业务后台自行控制 | | sessionId | string | 否 | 会话 ID，由业务后台自行控制 | | grant | string | 否 | 授予的权限，如为空则只授予读取权限。可指定多个权限项，使用英文逗号（,）分隔 | | period | number | 否 | 令牌有效时长，单位为秒，默认 86400（24小时），最小值 300，最大值 315360000 |

Grant 权限项

| 权限项 | 描述 | |--------|------| | admin | 管理员权限，授予所有权限 | | space_admin | 租户空间管理员权限，拥有除租户空间操作以外的所有权限 | | create_space | 创建租户空间权限 | | delete_space | 删除租户空间权限 | | create_directory | 创建目录或相簿权限 | | delete_directory | 删除目录或相簿权限（未开启回收站）/移入回收站权限（开启回收站） | | delete_directory_permanent | 开启回收站时，永久删除目录或相簿权限 | | move_directory | 重命名或移动目录或相簿权限 | | copy_directory | 复制目录或相簿权限 | | upload_file | 上传文件权限，但不允许覆盖已有文件 | | upload_file_force | 上传文件权限，且允许覆盖已有文件 | | begin_upload | 开始上传文件权限，但不允许覆盖已有文件 | | begin_upload_force | 开始上传文件权限，且允许覆盖已有文件 | | confirm_upload | 完成上传文件权限（用于前后端权限分离） | | 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 | 删除历史版本权限 |

主要功能

空间管理

创建/删除租户空间
列出空间列表
获取空间信息（文件数量、空间大小、扩展信息）
获取空间内容视图
设置空间流量限制
更新空间扩展信息

目录管理

文件管理

上传文件
- 简单上传（小文件）
- 表单上传
- 分片上传（大文件）
- 断点续传
下载文件
- 直接下载
- 获取文件信息
- 获取文件预览
- 获取文件封面
文件操作
- 删除文件（支持永久删除）
- 移动/重命名文件
- 复制文件
- 创建符号链接
- 文件转码
- 检查文件状态
- 根据 inode 获取文件信息

回收站管理（RecycledApi）

列出回收站内容
恢复回收站项目（单个/批量）
永久删除回收站项目（单个/批量）
清空回收站
获取回收站项目信息
预览回收站文件
设置回收站生命周期

历史版本管理（HistoryApi）

列出文件历史版本
删除历史版本
设置历史版本为最新版本
获取/设置历史版本配置
清空历史版本

搜索功能（SearchApi）

搜索目录与文件
继续获取搜索结果（分页）
删除搜索任务

收藏管理（FavoriteApi）

收藏文件/目录
取消收藏
列出收藏列表

最近使用（RecentApi）

查看最近使用文件列表

批量操作（BatchApi）

任务管理（TaskApi）

查询异步任务状态
查询媒体库级别任务
查询空间级别任务

配额管理（QuotaApi）

创建配额
获取租户空间配额
获取配额详细信息
更新配额（按空间 ID 或配额 ID）

使用量统计（UsageApi）

查询媒体库容量信息
批量查询租户空间容量信息

文档

更多详细文档请参考：

许可证

本项目采用 MIT 许可证。

支持

如有问题或建议，欢迎：

提交 Issue
查看官方文档
联系腾讯云技术支持