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

空间管理

最近更新时间:2026-09-30 16:51:32
本文档已由 AI 辅助审校
我的收藏

前期准备

开始操作前,确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK,请先参考快速入门文档完成。
注意:
创建租户空间需要 admin 或 create_space 权限。
列出所有租户空间需要 admin 权限,否则仅列出当前访问令牌所代表的用户所创建的租户空间。
修改租户空间属性需要 admin 或 space_admin 权限(非 acl 鉴权)。
删除租户空间需要 admin 或 delete_space 权限。

创建租户空间

功能说明
createSpace 实现创建租户空间。可以设置空间的公有读属性、多相簿模式、允许上传的文件类型、敏感内容检测等扩展属性。
使用示例
const res = await smh.space.createSpace({
userId: 'user-id',
createSpaceRequest: {
isMultiAlbum: true,
allowPhoto: true,
allowVideo: true,
allowPhotoExtname: ['.jpg', '.png', '.gif'],
allowVideoExtname: ['.mp4', '.mov'],
recognizeSensitiveContent: true
}
});

if (res.status === 201) {
console.log('空间创建成功', res.data);
}
参数说明
参数名
参数描述
类型
是否必填
spaceId
自定义租户空间 ID,名称不能以"-"开头或结尾,只支持英文小写字母和数字[a-z,0-9]、中划线"-"及其组合,长度为2~32个字符;不指定则由系统生成
String
否
userId
用户身份识别
String
否
createSpaceRequest
租户空间的扩展属性
Object
否
createSpaceRequest 对象说明
字段
参数描述
类型
是否必填
isPublicRead
是否为公有读,默认 false
Boolean
否
isMultiAlbum
是否为多相簿空间,默认 false
Boolean
否
allowPhoto
是否允许上传照片,默认 false
Boolean
否
allowVideo
是否允许上传视频,默认 false
Boolean
否
allowPhotoExtname
允许上传的照片扩展名列表
Array
否
allowVideoExtname
允许上传的视频扩展名列表
Array
否
recognizeSensitiveContent
是否检测敏感内容,默认 false
Boolean
否
spaceTag
空间标识
String
否
返回值说明
HTTP 状态码:201
创建成功,返回空间 ID。
响应字段说明
字段
说明
类型
spaceId
新创建的租户空间的空间 ID
String

列出租户空间

功能说明
listSpace 实现列出租户空间列表信息。支持分页查询。
使用示例
const res = await smh.space.listSpace({
marker: 'next-page-marker',
limit: 50
});

if (res.status === 200) {
console.log('空间列表', res.data);
}
参数说明
参数名
参数描述
类型
是否必填
marker
用于顺序列出分页的标识
String
否
limit
用于顺序列出分页时本地列出的项目数限制,默认 1000,最大 1000
Number
否
ordered
是否启用全局有序列出(按 spaceId 升序),取值为 1 表示启用,0 或不传表示不启用;启用后 prefix 与 startName 才会生效
Number
否
prefix
按 spaceId 前缀过滤,仅返回 spaceId 以该前缀开头的租户空间;仅在 ordered=1 时生效
String
否
startName
分页起始游标(不包含),仅返回 spaceId 大于 startName 的租户空间;仅在 ordered=1 时生效;当与 marker 同时传入时 marker 优先,startName 会被忽略
String
否
返回值说明
HTTP 状态码:200
获取成功。
响应字段说明
字段
说明
类型
list
租户空间列表
Array
marker
用于顺序列出分页的标识
String

查询租户空间属性

功能说明
getSpaceExtension 实现查询租户空间的扩展属性。
使用示例
const res = await smh.space.getSpaceExtension({
spaceId: 'your-space-id'
});

if (res.status === 200) {
console.log('空间属性', res.data);
}
参数说明
参数名
参数描述
类型
是否必填
spaceId
空间 ID
String
是
userId
用户身份识别
String
否
返回值说明
HTTP 状态码:200
获取成功,返回空间扩展属性(isPublicRead、allowPhoto、allowVideo 等)。

修改租户空间属性

功能说明
updateSpaceExtension 实现修改租户空间属性。需要 admin 或 space_admin 权限。
使用示例
const res = await smh.space.updateSpaceExtension({
spaceId: 'your-space-id',
updateSpaceExtensionRequest: {
isPublicRead: true,
allowPhoto: true,
allowVideo: true,
allowPhotoExtname: ['.jpg', '.png', '.heic'],
allowVideoExtname: ['.mp4', '.mov', '.avi']
}
});

if (res.status === 204) {
console.log('空间属性修改成功');
}
参数说明
参数名
参数描述
类型
是否必填
spaceId
空间 ID
String
是
userId
用户身份识别
String
否
updateSpaceExtensionRequest
租户空间的扩展属性
Object
否
updateSpaceExtensionRequest 对象说明
字段
参数描述
类型
是否必填
isPublicRead
是否为公有读
Boolean
否
allowPhoto
是否允许上传照片(媒体类型媒体库)
Boolean
否
allowVideo
是否允许上传视频(媒体类型媒体库)
Boolean
否
allowPhotoExtname
允许的照片扩展名(媒体类型媒体库)
Array
否
allowVideoExtname
允许的视频扩展名(媒体类型媒体库)
Array
否
allowFileExtname
允许的文件扩展名(非媒体类型媒体库)
Array
否
recognizeSensitiveContent
是否检测敏感内容
Boolean
否
spaceTag
空间标识,区分个人/团队空间;传入字符串更新,传入 null 清除,不传保持原值
String
否
返回值说明
HTTP 状态码:204
修改成功,无响应体。

列出空间首页内容

功能说明
getContentsView 实现列出空间首页内容,会忽略目录的层级关系,列出空间下所有文件。
使用示例
const res = await smh.space.getContentsView({
spaceId: 'your-space-id',
filter: 'onlyFile',
orderBy: 'modificationTime',
orderByType: 'desc',
withPath: true
});

if (res.status === 200) {
console.log('空间内容', res.data);
}
参数说明
参数名
参数描述
类型
是否必填
spaceId
空间 ID
String
是
filter
筛选方式:onlyDir、onlyFile
String
是
marker
用于顺序列出分页的标识
String
否
limit
分页限制
Number
否
orderBy
排序字段:name(默认)、modificationTime、size、creationTime、uploadTime、localCreationTime、localModificationTime
String
否
orderByType
排序方式:asc、desc
String
否
withPath
是否返回 path,默认 false
Boolean
否
userId
用户身份识别
String
否
category
文件自定义分类
String
否
返回值说明
HTTP 状态码:200
获取成功,返回 nextMarker 和 contents 数组。
contents 数组元素字段说明
字段
类型
说明
name
String
目录、相簿或文件的名称
path
Array<String>
文件路径,仅 withPath 为 true 时返回
inode
String
文件或目录 ID
type
String
类型:dir(目录)、file(文件)、image(照片)、video(视频)、symlink(符号链接)、virtual(虚拟文件)
creationTime
String
创建时间(目录、相簿)或上传时间(文件)
modificationTime
String
修改时间(目录、相簿)或最近一次覆盖时间(文件)
versionId
Number
历史版本 ID,仅操作历史版本时返回
contentType
String
媒体类型
size
String
文件大小,字符串格式
eTag
String
文件 ETag
crc64
String
文件 CRC64-ECMA182 校验值
metaData
Object
文件元数据键值对
previewByDoc
Boolean
是否支持文档预览(WPS)
previewByCI
Boolean
是否支持数据万象预览
previewAsIcon
Boolean
是否支持缩略图预览
fileType
String
文件类型分类(如 excel、powerpoint 等)
labels
Array<String>
文件或目录的简易标签
category
String
文件自定义分类
localCreationTime
String
文件本地创建时间,仅文件返回
localModificationTime
String
文件本地修改时间,仅文件返回

空间文件数量统计

功能说明
getFileCountInSpace 实现空间文件数量统计。需要 admin 或 space_admin 权限。
使用示例
const res = await smh.space.getFileCountInSpace({
spaceId: 'your-space-id'
});

if (res.status === 200) {
console.log('文件统计', res.data);
}
参数说明
参数名
参数描述
类型
是否必填
spaceId
空间 ID
String
是
返回值说明
HTTP 状态码:200
获取成功。
响应字段说明
字段
说明
类型
fileNum
总文件数量,字符串格式
String
dirNum
总文件夹数量,字符串格式
String
recycledFileNum
回收站文件数量,字符串格式
String
recycledDirNum
回收站文件夹数量,字符串格式
String
historyFileNum
历史版本文件数量,字符串格式
String

删除租户空间

功能说明
deleteSpace 实现删除租户空间。需要 admin 或 delete_space 权限。
使用示例
const res = await smh.space.deleteSpace({
spaceId: 'your-space-id',
force: 1
});

if (res.status === 204) {
console.log('空间删除成功');
}
参数说明
参数名
参数描述
类型
是否必填
spaceId
空间 ID
String
是
userId
用户身份识别
String
否
force
是否强制删除,0: 非强制(默认),1: 强制
Number
否
返回值说明
HTTP 状态码:204
删除成功,无响应体。

查询媒体库租户空间数量

功能说明
getLibrarySpaceCount 实现查询媒体库中的租户空间数量。
使用示例
const res = await smh.space.getLibrarySpaceCount({});

if (res.status === 200) {
console.log('空间数量:', res.data.total);
}
参数说明
参数名
参数描述
类型
是否必填
userId
用户身份识别
String
否
返回值说明
HTTP 状态码:200
获取成功。
响应字段说明
字段
说明
类型
total
租户空间数量
Number

查询租户空间大小

功能说明
getSpaceSize 实现查询租户空间大小。
使用示例
const res = await smh.space.getSpaceSize({
spaceId: 'your-space-id'
});

if (res.status === 200) {
console.log('占用空间:', res.data.size, '字节');
}
参数说明
参数名
参数描述
类型
是否必填
spaceId
空间 ID
String
是
userId
用户身份识别
String
否
返回值说明
HTTP 状态码:200
获取成功。
响应字段说明
字段
说明
类型
size
租户空间大小(单位:字节),字符串格式
String

设置租户空间限速

功能说明
setSpaceTrafficLimit 实现设置租户空间的下载限速。需要 admin 或 space_admin 权限。
使用示例
// 设置下载限速为 1MB/s
const res = await smh.space.setSpaceTrafficLimit({
spaceId: 'your-space-id',
setSpaceTrafficLimitRequest: {
downloadTrafficLimit: 1048576
}
});

if (res.status === 204) {
console.log('限速设置成功');
}

// 取消限速
const res2 = await smh.space.setSpaceTrafficLimit({
spaceId: 'your-space-id',
setSpaceTrafficLimitRequest: {
downloadTrafficLimit: -1
}
});
参数说明
参数名
参数描述
类型
是否必填
spaceId
空间 ID
String
是
setSpaceTrafficLimitRequest
限速设置对象
Object
是
setSpaceTrafficLimitRequest 对象说明
字段
参数描述
类型
是否必填
downloadTrafficLimit
空间下载限速,范围 100KB/s-100MB/s,单位字节,-1 表示取消限速
Number
是
返回值说明
HTTP 状态码:204
设置成功,无响应体。