批量重命名或移动目录或文件

最近更新时间:2025-10-29 14:34:31

我的收藏

功能描述

用于批量重命名或移动目录或文件。
说明:
要求权限:
同空间重命名或移动:admin、space_admin 或 move_directory/move_file/move_file_force,如需同时重命名或移动目录和文件,可同时指定 move_directory 与 move_file/move_file_force 权限。
跨空间移动:admin 或同时指定源空间与目的空间的 space_admin。
有关权限详情请参见 生成访问令牌接口

请求

请求示例

POST /api/v1/batch/{LibraryId}/{SpaceId}?move&access_token={AccessToken}&user_id={UserId}

请求参数

请求参数
描述
类型
是否必选
LibraryId
媒体库 ID,在媒体托管控制台创建媒体库后获取,请参见 创建媒体库
String
SpaceId
空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数,获取请参见 创建租户空间
String
AccessToken
访问令牌,获取请参见 生成访问令牌
String
UserId
用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份,详情请参阅 生成访问令牌
String

请求体

application/json,指定重命名或移动的源路径和目的路径。
请求体示例:
[
{
"fromSpaceId":"spaceNJsnjdiq",
"from": "foo/bar_old",
"to": "foo/bar"
},
{
"from": "foo/1.jpg",
"to": "bar/1.jpg"
},
{
"from": "foo/2.jpg",
"to": "bar/2.jpg",
"conflictResolutionStrategy": "overwrite"
}
]
请求体字段说明:
请求参数
描述
类型
是否必选
fromSpaceId
跨空间移动时指定源目录或文件所在的空间,同空间移动时请勿指定该字段
String
from
被重命名或移动的源目录、相簿或文件路径
String
to
目标目录、相簿或文件路径
String
conflictResolutionStrategy
文件名冲突时的处理方式,默认为 rename
ask:冲突时返回 HTTP 409 Conflict 及 SameNameDirectoryOrFileExists 错误码
rename:冲突时自动重命名文件
overwrite:
如果目标为目录或相簿时,默认为 ask 且不支持 overwrite
如果目标为文件,覆盖已有文件
当目标空间的文件存在历史版本时,不支持移动覆盖
String
moveAuthority
是否允许移动
Boolean

响应

响应码

执行成功
当项目较多以异步方式重命名或移动时,返回 HTTP 202 Accepted。
当项目较少以同步方式重命名或移动时,返回 HTTP 200 OK(全部执行成功)或 HTTP 207 Multi-Status(存在部分或全部执行失败)。

响应体

application/json
响应体示例:
返回 HTTP 200 OK 或 HTTP 207 Multi-Status 时:
{
"result": [
{
"status": 204,
"moveAuthority":false,
"from": [ "foo", "bar_old" ],
"to": [ "foo", "bar" ]
},
{
"status": 200,
"path": [ "bar", "1 (1).jpg" ],
"from": [ "foo", "1.jpg" ],
"to": [ "bar", "1.jpg" ]
},
{
"status": 204,
"from": [ "foo", "2.jpg" ],
"to": [ "bar", "2.jpg" ]
}
]
}
返回 HTTP 202 Accepted 时:
{ "taskId": 17 }
[
{
"taskId": 17,
"status": 200,
"result": [
{
"status": 204,
"moveAuthority":false,
"from": [ "foo", "bar_old" ],
"to": [ "foo", "bar" ]
},
{
"status": 200,
"path": [ "bar", "1 (1).jpg" ],
"from": [ "foo", "1.jpg" ],
"to": [ "bar", "1.jpg" ]
},
{
"status": 204,
"from": [ "foo", "2.jpg" ],
"to": [ "bar", "2.jpg" ]
}
]
}
]
响应体字段说明:
响应参数
描述
类型
result.status
单个项目的重命名或移动结果:
200:conflictResolutionStrategy 为 rename 时重命名或移动成功
204:conflictResolutionStrategy 为 ask 或 overwrite 时重命名或移动成功
403/404/409/500等:重命名或移动失败
String
result.moveAuthority
是否允许移动
Boolean
result.path
表示最终的路径,因为可能存在自动重命名,所以这里的最终路径可能不等同于重命名或移动时指定的路径
String Array
result.from 和 result.to
发起请求时传入的对应路径的数组形式
Array
taskId
异步方式重命名或移动时的任务 ID,可通过查询任务接口查询任务状态
String
查询任务响应体字段说明:
响应参数
描述
类型
status
查询任务状态:
202:任务进行中
200:全部执行成功
207:存在部分或全部执行失败
String

错误码

该请求操作无特殊错误信息,常见的错误信息请参见 错误码 文档。