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

分享管理

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

前期准备

开始操作前,确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK,请先参考快速入门文档完成。
注意事项:
分享相关接口分为两类:分享管理接口(创建、查询、更新、删除分享等,需要访问令牌)和分享访问接口(通过分享码/提取码访问分享内容,部分无需认证)。
访问分享文件前,需要先通过「验证提取码」接口获取分享访问令牌(有效期 10 分钟),并将其作为 accessToken 传入后续分享访问接口。
仅当 adminEnabled 与 ownerEnabled 同时为 true 时,分享外链才可用。

创建分享

功能说明
createShare 用于创建文件或目录的分享链接,支持设置有效期、提取码、预览/下载/转存权限等。
使用示例
const res = await smh.share.createShare({
spaceId: 'your-space-id',
createShareRequest: {
name: 'report.pdf',
filePath: ['/documents/report.pdf'],
config: {
isPermanent: false,
expireTime: '2026-12-31T23:59:59+08:00',
canPreview: true,
canDownload: true,
},
},
});

if (res.status === 200) {
console.log('分享 ID:', res.data.id);
console.log('分享码:', res.data.code);
console.log('访问地址:', res.data.endpoint);
}
参数说明
参数名
参数描述
类型
是否必填
spaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数
String
是
createShareRequest
创建分享请求对象
Object
是
createShareRequest 对象说明
字段
参数描述
类型
是否必填
name
分享名称
String
是
filePath
分享的文件或目录路径数组,最多 1000 个
Array<String>
是
config
分享配置
Object
否
config 对象说明
字段
参数描述
类型
是否必填
isPermanent
是否永久有效,默认 false
Boolean
否
expireTime
过期时间(ISO 8601),isPermanent 为 false 时必填
String
条件必填
extractionCode
提取码,不超过 6 位
String
否
canPreview
是否允许预览,默认 false
Boolean
否
canDownload
是否允许下载,默认 false
Boolean
否
canSaveToNetdisk
是否允许转存,默认 false
Boolean
否
forbidAnonymousUser
是否禁止匿名用户访问,默认 false
Boolean
否
previewLimit
预览次数限制,仅单文件分享生效,canPreview 为 false 时忽略
Number
否
downloadLimit
下载次数限制,仅单文件分享生效,canDownload 为 false 时忽略
Number
否
userLimit
访问人数限制
Number
否
shareToUsers
指定可访问的用户,设置后禁止匿名访问
Array<String>
否
返回值说明
HTTP 状态码:200,创建成功。
字段
说明
类型
id
分享 ID
Number
code
分享码,用于访问分享
String
endpoint
分享访问地址
String
createTime
创建时间
String
expireTime
过期时间
String
isPermanent
是否永久有效
Boolean
domain
分享域名信息,含 shareDomain 数组
Object

列出分享

功能说明
listShares 用于列出当前媒体库下的分享列表,支持分页。
使用示例
const res = await smh.share.listShares({
limit: 20,
orderByType: 'desc',
withFileInfo: 1,
});

if (res.status === 200) {
res.data.contents.forEach(share => {
console.log(share.name, share.code);
});
if (res.data.hasMore) {
console.log('还有更多分享,marker:', res.data.marker);
}
}
参数说明
参数名
参数描述
类型
是否必填
limit
每页数量,默认 10,最大 100
Number
否
marker
分页标识
String
否
orderBy
排序字段,默认 createTime
String
否
orderByType
排序方式:asc(默认)、desc
String
否
creatorId
按创建者筛选,仅管理员可用
String
否
withFileInfo
是否返回文件信息,0(默认)或 1
Number
否
userId
用户身份识别
String
否
返回值说明
HTTP 状态码:200,返回 contents 分享数组、marker 分页标识与 hasMore。分享对象主要字段:id、name、code、creatorId、createTime、expireTime、isPermanent、adminEnabled、ownerEnabled、canPreview、canDownload、canSaveToNetdisk、previewLimit/previewUsed、downloadLimit/downloadUsed、status(0 未审核、1 审核中、2 审核通过、3 审核不通过)、userLimit/userLimitUsed、fileInfo(withFileInfo=1 时返回)。

搜索分享

功能说明
searchShares 用于按名称、创建者、时间范围等条件搜索分享。仅管理员可用,QPS 上限 10。
使用示例
const res = await smh.share.searchShares({
limit: 20,
searchSharesRequest: {
name: 'report',
orderBy: 'createTime',
orderByType: 'desc',
},
});

if (res.status === 200) {
res.data.contents.forEach(share => console.log(share.name));
}
参数说明
参数名
参数描述
类型
是否必填
limit
每页数量,默认 10,最大 50
Number
否
marker
分页标识
String
否
searchSharesRequest
搜索条件对象
Object
是
searchSharesRequest 对象说明:name(名称模糊匹配)、creatorId(创建者精确匹配)、orderBy(createTime/expireTime/name/creatorId)、orderByType(asc/desc)、expireTimeStart/expireTimeEnd、createTimeStart/createTimeEnd(ISO 8601)。

获取分享详情

功能说明
getShareDetail 用于获取指定分享的详细信息。
使用示例
const res = await smh.share.getShareDetail({
shareId: '12345',
detail: 1,
withFileInfo: 1,
});

if (res.status === 200) {
console.log('名称:', res.data.name);
console.log('分享码:', res.data.code);
console.log('是否过期:', res.data.isExpired);
}
参数说明
参数名
参数描述
类型
是否必填
shareId
分享 ID
String
是
detail
固定值 1,表示获取分享详情
Number
是
withFileInfo
是否返回文件信息,0(默认)或 1
Number
否
返回值说明
HTTP 状态码:200。主要字段:id、libraryId、name、code、creatorId、creationTime、expireTime、isPermanent、isExpired、extractionCode、ownerEnabled、adminEnabled、status(0-3)、canPreview、canDownload、canSaveToNetdisk、forbidAnonymousUser、previewLimit/previewUsed、downloadLimit/downloadUsed、fileInfo、toUsers、userLimit/userLimitUsed、watermarkText。

获取分享 URL 详情

功能说明
getShareUrlDetail 用于通过分享码(shareToken)获取分享的基本信息,无需认证,适用于访问者打开分享链接时展示分享概况。
使用示例
const res = await smh.share.getShareUrlDetail({
shareToken: 'share-token-from-url',
});

if (res.status === 200) {
console.log('名称:', res.data.name);
console.log('需要提取码:', res.data.needExtractionCode);
console.log('是否可用:', res.data.enabled);
}
参数说明
参数名
参数描述
类型
是否必填
shareToken
分享链接中的分享码
String
是
返回值说明
HTTP 状态码:200。主要字段:name、enabled、isExpired、needExtractionCode、allowAnonymousUser、canPreview、canDownload、canSaveToNetDisc、status、enableShareWatermark、shareWatermarkType、watermarkText、fileName、domain(含 shareDomain 数组)。

更新分享

功能说明
updateShare 用于更新分享的名称和配置。不允许修改 shareToUsers;更新后预览/下载次数统计(previewUsed/downloadUsed)会重置为 0。
使用示例
const res = await smh.share.updateShare({
shareId: '12345',
update: 1,
updateShareRequest: {
name: 'report-v2.pdf',
config: {
isPermanent: false,
expireTime: '2027-06-30T23:59:59+08:00',
canPreview: true,
canDownload: true,
},
},
});

if (res.status === 200) {
console.log('更新成功,访问地址:', res.data.endpoint);
}
参数说明
参数名
参数描述
类型
是否必填
shareId
分享 ID
String
是
update
固定值 1,表示更新分享
Number
是
updateShareRequest
更新分享请求对象,config 字段必填(字段同创建配置,但不支持 shareToUsers)
Object
是

禁用或启用分享

功能说明
setShareEnabled 用于禁用或启用分享。仅当 adminEnabled 与 ownerEnabled 同时为 true 时,分享外链才可用。
使用示例
// 创建者禁用分享
const res = await smh.share.setShareEnabled({
shareId: '12345',
setEnabled: 1,
setShareEnabledRequest: {
ownerEnabled: false,
},
});

console.log('Status:', res.status);
参数说明
参数名
参数描述
类型
是否必填
shareId
分享 ID
String
是
setEnabled
固定值 1,表示禁用或启用分享
Number
是
setShareEnabledRequest
启用状态对象:adminEnabled(仅管理员可设置)、ownerEnabled(创建者可设置)
Object
是

删除分享

功能说明
deleteShare 用于删除指定分享,删除后分享链接立即失效。
使用示例
const res = await smh.share.deleteShare({
shareId: '12345',
});

if (res.status === 204) {
console.log('分享已删除');
}
参数说明
参数名
参数描述
类型
是否必填
shareId
分享 ID
String
是
返回值说明
HTTP 状态码:204,删除成功,无响应体。

验证提取码

功能说明
verifyExtractionCode 用于校验分享提取码,验证成功后返回分享访问令牌(有效期 10 分钟),后续访问分享文件需携带该令牌。本接口无需认证。
使用示例
const res = await smh.share.verifyExtractionCode({
shareCode: 'share-code',
verifyExtractionCodeRequest: {
extractionCode: 'ab12',
},
});

if (res.status === 200) {
const shareAccessToken = res.data.accessToken;
console.log('分享访问令牌:', shareAccessToken, '过期时间:', res.data.expireTime);
// 后续访问分享文件时,将该令牌作为 accessToken 传入
}
参数说明
参数名
参数描述
类型
是否必填
shareCode
分享码
String
是
verifyExtractionCodeRequest
验证请求对象:extractionCode(必填);libraryId 与 access_token(分享要求登录时必填,注意为 snake_case 字段名);device_id(可选)
Object
是
返回值说明
HTTP 状态码:200,验证成功。
字段
说明
类型
accessToken
分享访问令牌,有效期 10 分钟
String
expireTime
令牌过期时间
String

列出分享文件

功能说明
listShareFiles 用于列出分享中的文件和目录,支持分页浏览目录内容。
使用示例
const res = await smh.share.listShareFiles({
shareCode: 'share-code',
inodes: 'root-inode',
list: 1,
accessToken: shareAccessToken, // 验证提取码获取的分享访问令牌
limit: 50,
});

if (res.status === 200) {
res.data.contents.forEach(file => {
console.log(file.name, file.type);
});
}
参数说明
参数名
参数描述
类型
是否必填
shareCode
分享码
String
是
inodes
目录 inode 链(/ 分隔),指定列出的目录层级,最长 64 层
String
是
list
固定值 1,表示列出分享文件
Number
是
limit
每页数量,默认 10,取值 0-100
Number
否
marker
分页标识
String
否
orderBy
排序字段:name、size、updatedAt
String
否
orderByType
排序方式:asc(默认)、desc
String
否
accessToken
分享访问令牌
String
否
返回值说明
HTTP 状态码:200,返回 contents(name、spaceId、type(file/dir)、size、updateTime、canPreview、canDownload、canSaveToNetdisk、inode)、marker、hasMore。

预览或下载分享文件

功能说明
previewShareFile 与 downloadShareFile 分别用于预览和下载分享中的文件,均通过 HTTP 302 重定向到实际地址,无 JSON 响应体;axios 会自动跟随跳转,客户端实际观察到的 res.status 为最终响应的 200。调用前需先通过「验证提取码」获取分享访问令牌;预览/下载次数受分享配置的 previewLimit/downloadLimit 限制并计入 previewUsed/downloadUsed。
使用示例
// 预览分享文件
const res = await smh.share.previewShareFile({
shareCode: 'share-code',
inodes: 'file-inode',
preview: 1,
accessToken: shareAccessToken,
});
console.log('Preview status:', res.status);

// 下载分享文件
const res2 = await smh.share.downloadShareFile({
shareCode: 'share-code',
inodes: 'file-inode',
download: 1,
accessToken: shareAccessToken,
});
console.log('Download status:', res2.status);
参数说明
参数名
参数描述
类型
是否必填
shareCode
分享码
String
是
inodes
文件 inode 链,末位必须指向文件
String
是
preview / download
固定值 1,分别表示预览或下载
Number
是
internalDomain
是否使用内网域名
Number
否
accessToken
分享访问令牌
String
否

转存分享文件

功能说明
saveShareFile 用于将分享中的文件转存到自己媒体库的指定空间,需分享配置开启 canSaveToNetdisk。转存可能同步完成(200)、转为异步任务(202)或部分成功(207)。
使用示例
const res = await smh.share.saveShareFile({
shareCode: 'share-code',
save: 1,
accessToken: shareAccessToken,
saveShareFileRequest: {
targetSpaceId: 'your-space-id',
targetPath: '/saved/',
sourceInodesPath: '/',
inodes: ['file-inode-1'],
conflictResolutionStrategy: 'rename',
},
});

if (res.status === 200) {
res.data.result.forEach(item => {
console.log('status:', item.status, 'path:', item.path);
});
} else if (res.status === 202) {
console.log('异步转存任务,taskId:', res.data.taskId);
} else if (res.status === 207) {
console.log('部分成功');
}
参数说明
参数名
参数描述
类型
是否必填
shareCode
分享码
String
是
save
固定值 1,表示转存分享文件
Number
是
saveShareFileRequest
转存请求对象
Object
是
accessToken
分享访问令牌
String
否
saveShareFileRequest 对象说明
字段
参数描述
类型
是否必填
targetSpaceId
转存目标空间 ID
String
是
targetPath
转存目标路径
String
否
sourceInodesPath
分享中的源目录路径
String
是
inodes
转存的文件或目录 inode 数组,最多 1000 个
Array<String>
是
conflictResolutionStrategy
冲突处理:ask、rename、overwrite;目标为目录时默认 ask 且不支持 overwrite,目标为文件时默认 rename
String
否