前期准备
开始操作前,确保您已经完成了 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 | 否 |