tencent cloud

智能媒资托管

产品简介
产品概述
功能介绍
产品优势
应用场景
基本概念
购买指南
快速入门
创建媒体库
发起请求
服务级 API 文档
History
Introduction
API Category
Making API Requests
PaaS Service APIs
Official Cloud Disk APIs
Data Types
Error Codes
业务级 API 文档
简介
访问令牌操作接口
租户空间操作接口
文件操作接口
目录或相簿操作接口
回收站操作接口
配额操作接口
查询任务操作接口
搜索操作接口
历史版本操作接口
目录和文件批量操作接口
收藏操作接口
Error Codes
SDK 文档
Android SDK
iOS SDK
鸿蒙 SDK
常见问题
企业网盘
产品简介
购买指南
快速入门
常见问题
Service Level Agreement
词汇表

文件

PDF
聚焦模式
字号
最后更新时间: 2026-01-07 10:49:13

简介

本文档提供关于文件相关接口介绍以及示例代码

文件上传

功能说明

该上传方法内部会自动进行快速上传、简单上传、分块上传的逻辑,生成的 task 可以供外部进行暂停、恢复、取消等。

示例代码

上传
try {
let filePath = "本地文件路径";
// 调用 SMHFileApis 的 uploadObject 方法进行文件上传
let task = SMHFileApis.uploadObject({
spaceId: "spaceId",
libraryId: "libraryId",
body: filePath, // 本地路径
uploadPath: `smh/test.jpg`, // 目标路径
});
task.onStateChange = (state: SMHTransferState) => {
// 任务状态回调
}
task.confirmKeyInitCallback = (confimKey: string) => {
// 上传返回 confirmKey 回调。用于断点续传
}
task.onProgress = (progress) => {
// 进度回调
}
task.onFinish = (result?: object, error?: SMHError) => {
// 完成回调
}
// 启动任务
task.start();

//其他方法
//task.pause() 暂停任务
//task.cancel() 取消任务
//task.resume() 重新启动任务,与 pause 配合使用
}catch (e) {
// 异常处理
}
断点续传
try {
let filePath = "本地文件路径";
// 调用 SMHFileApis 的 uploadObject 方法进行文件上传
let task = SMHFileApis.uploadObject({
spaceId: "spaceId",
libraryId: "libraryId",
body: filePath, // 本地路径
uploadPath: `smh/test.jpg`, // 目标路径
confirmKey:"confirmKey"// confirmKeyInitCallback 回调返回的 confirmKey。
});
task.onStateChange = (state: SMHTransferState) => {
// 任务状态回调
}
task.confirmKeyInitCallback = (confimKey: string) => {
// 上传返回 confirmKey 回调。用于断点续传
}
task.onProgress = (progress) => {
// 进度回调
}
task.onFinish = (result?: object, error?: SMHError) => {
// 完成回调
}
// 启动任务
task.start();

//其他方法
//task.pause() 暂停任务
//task.cancel() 取消任务
//task.resume() 重新启动任务,与 pause 配合使用
}catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
body
待上传的文件,格式为本地文件路径或者 ArrayBuffer
String/ArrayBuffer
uploadPath
目标路径,例如 foo/bar/file.docx
String
confirmKey
确认参数,指定为开始上传文件时响应体中的 confirmKey 字段的值,用于续传
String
simpleUploadLimit
简单上传阈值 默认1m。小于1m则使用简单上传,否则使用分块上传
Number
sliceLength
分块大小:默认1m
Number
conflictResolutionStrategy
文件名冲突时的处理方式:
ask:冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename:冲突时自动重命名文件
overwrite:如果冲突目标为目录时返回 HTTP 409 Conflict 及SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件
SMHConflictResolutionStrategy
customHeader
自定义请求头
Map
trafficLimit
单链接下载限速,范围100KB/s-100MB/s,单位 B
Number
withInode
上传完是否返回 inode,即文件目录 ID
Bool

文件下载

功能说明

该下载方法内部会自动进行下载到本地以及续传的逻辑,生成的 task 可以供外部进行暂停、恢复、取消等。
说明:
下载接口默认支持断点续传,确保写入本地路径不变即可。

示例代码

try {
// 调用 SMHFileApis 的 downloadObject 方法进行文件上传
let task = SMHFileApis.downloadObject({
spaceId: "spaceId",
libraryId: "libraryId",
filePath: `smh/test.jpg`,// 远端路径
savePath: "本地路径" // 本地路径
})
task.onStateChange = (state: SMHTransferState) => {
// 任务状态回调
}
task.onProgress = (progress: HttpProgress) => {
// 进度回调
}
task.onFinish = (result?: object, error?: SMHError) => {
// 完成回调
}
// 启动任务
task.start();
//其他方法
//task.pause() 暂停任务
//task.cancel() 取消任务
//task.resume() 重新启动任务,与 pause 配合使用
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
savePath
保存到本地的路径
String
historyId
历史版本 ID,用于获取不同版本的文件内容
String
trafficLimit
单链接下载限速,范围 100KB/s-100MB/s,单位 B
Number

获取照片/视频封面缩略图

功能说明

用于获取照片/视频封面缩略图。

示例代码

try {
let result = await SMHFileApis.preview({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/image.jpg"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/image.jpg
String
size
缩放大小
String
scale
等比例缩放百分比,不传 Size 时生效
String
widthSize
缩放宽度,不传高度时,高度按等比例缩放,不传 Size 和 Scale 时生效
String
heightSize
缩放高度,不传宽度时,宽度按等比例缩放,不传 Size 和 Scale 时生效
String
frameNumber
帧数,针对 gif 的降帧处理
String

获取文件下载链接和信息

功能说明

用于获取文件下载链接和信息。

示例代码

try {
let result =
await SMHFileApis.downloadInfo({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
historyId
历史版本 ID,用于获取不同版本的文件内容
String
trafficLimit
单链接下载限速,范围 100KB/s-100MB/s,单位 B
Number
contentDisposition
用于设置 Content-Disposition 响应头,支持 inline 或者 attachment
SMHContentDisposition
purpose
用途,可以设置为 download 或者 preview,用于决定是否将该文件加入最近使用文件列表中,如果设置为 preview,则会将该文件加入最近使用文件列表中,否则不会加入
SMHPurpose
pre_check
是否只用于校验文件是否可预览和下载,设置该参数后返回结果中不包含 cosUrl
Bool

删除文件

功能说明

用于删除文件。

示例代码

try {
let result = await SMHFileApis.deleteFile({
libraryId: "TestLibraryId",
spaceId: "TestSpaceId",
filePath: "foo/bar/file.docx",
permanent: true
});
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
permanent
当媒体库开启回收站时,则该参数指定将文件移入回收站还是永久删除文件,true: 永久删除,false: 移入回收站,默认为 false
Bool

复制文件

功能说明

用于复制文件。

示例代码

try {
let result = await SMHFileApis.copyFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file_new.docx",
copyFrom: "foo/bar/file.docx"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file_new.docx
String
copyFrom
被复制的源文件云端路径,例如 foo/bar/file.docx
String
conflictResolutionStrategy
文件名冲突时的处理方式,默认为 rename
ask: 冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename: 冲突时自动重命名文件
overwrite: 如果冲突目标为目录时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件
SMHConflictResolutionStrategy

重命名或移动文件

功能说明

用于重命名或移动文件。

示例代码

try {
let result = await SMHFileApis.moveFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file_new.docx",
from: "foo/bar/file.docx"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file_new.docx
String
from
被移动的源文件云端路径,例如 foo/bar/file.docx
String
conflictResolutionStrategy
文件名冲突时的处理方式,默认为 rename
ask: 冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename: 冲突时自动重命名文件
overwrite: 如果冲突目标为目录时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码,否则覆盖已有文件
SMHConflictResolutionStrategy

更新文件的标签(Labels)或分类(Category)

功能说明

用于更新文件的标签(Labels)或分类(Category)。

示例代码

try {
let result = await SMHFileApis.updateTagAndCategory({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.jpg",
labels: ["大象","动物","亚洲象"],
category: "image",
localCreationTime: "2022-07-26T02:58:09Z",
localModificationTime: "2022-07-26T02:58:09Z",
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
labels
文件标签列表
String 数组
category
文件自定义的分类
String
localCreationTime
文件对应的本地创建时间
String
localModificationTime
文件对应的本地修改时间
String

查看最近使用文件列表

功能说明

用于查看最近使用文件列表。

示例代码

try {
let result = await SMHFileApis.recentlyUseFile({
libraryId: "libraryId",
spaceId: "spaceId",
filterActionBy: SMHFilterAction.preview,
withPath: true
});
}catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
marker
用于顺序列出分页的标识,不传默认第一页
String
limit
用于顺序列出分页时本地列出的项目数限制,可选参数,不传则默认20
String
filterActionBy
筛选操作方式,不传返回全部,preview 只返回预览操作,modify 返回编辑操作
SMHFilterAction
type
筛选文件类型,当前支持的类型包括:
all: 搜索所有文件,当不传 type 或传空时默认为 all
document: 搜索所有文档,文档类型为:['pdf', 'powerpoint', 'excel', 'word','text']
pdf: 仅搜索 PDF 文档,对应的文件扩展名为 .pdf
powerpoint: 仅搜索演示文稿,如 .ppt、.pptx、.pot、.potx 等
excel: 仅搜索表格文件,如 .xls、.xlsx、.ett、.xltx、.csv 等
word: 仅搜索文档,如 .doc、.docx、.dot、.wps、.wpt 等
text: 仅搜索纯文本,如 .txt、.asp、.htm 等
doc、xls 或 ppt: 仅搜索 Word、Excel 或 Powerpoint 类型文档,对应的文件扩展名为 .doc(x)、.xls(x) 或 .ppt(x)
字符串数组: 可以是文档后缀数组,如 ['.ppt', '.doc', '.excel']等;也可以是上述筛选类型数组,如 ['pdf', 'powerpoint', 'word'] 等
SMHFileInfoType 数组
withPath
是否返回文件路径,true|false,默认为 false,可选参数
Bool

根据文件 ID 查询文件信息

功能说明

用于根据文件 ID 查询文件信息。

示例代码

try {
let result = await SMHFileApis.getFileInfoByInode({
libraryId: "libraryId",
spaceId: "spaceId",
inode: "inode"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
inode
文件 ID
String

检查文件状态

功能说明

用于检查文件状态。

示例代码

try {
let result = await SMHFileApis.headFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
});
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
historyId
历史版本 ID
String

获取 HTML 格式文档预览

功能说明

用于获取 HTML 格式文档预览。

示例代码

try {
let result = await SMHFileApis.previewHtml({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
})
} catch (e) {
// 异常处理
}

参数说明

请求参数
描述
类型
是否必选
libraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(`-`);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
filePath
云端目标路径,例如 foo/bar/file.docx
String
historyId
历史版本 ID,用于获取不同版本的文件内容
String
type
文档预览方式,如果设置为"pic"则以 jpg 格式预览文档首页,否则以 html 格式预览文档
SMHPreviewType

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈