文档首页/ 高性能弹性文件服务 SFS Turbo/ API参考/ API/ 文件系统管理/ 创建文件系统异步任务 - CreateFsTask

更新时间：2026-09-30 GMT+08:00

创建文件系统异步任务 - CreateFsTask

功能介绍

创建文件系统异步任务，仅支持异步查询目录资源使用情况，API请求路径的feature取值为dir-usage，以下简称为DU任务。

接口约束

在2023年8月1号之后创建的文件系统支持该API操作。如果存在10个正在执行的任务，则不允许创建新任务。该接口并发请求数过大可能会影响文件系统性能，建议同时提交的查询请求不要超过4 个。查询超大目录耗时较久，请不要重复提交。API请求路径的feature仅支持以下取值：

dir-usage

该接口仅适用于以下类型：

20MB/s/TiB
40MB/s/TiB
125MB/s/TiB
250MB/s/TiB
500MB/s/TiB
1000MB/s/TiB
HPC缓存型
100MB/s/TiB-智算型
200MB/s/TiB-智算型

标准型、标准型-增强版、性能型、性能型-增强版类型的SFS Turbo文件系统，请使用“查询目录资源使用情况”接口。

在客户端增删目录下的文件后，DU任务返回的目录容量与数量统计存在约5分钟延迟，建议等待5分钟后查询以获取最新数据。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

POST /v1/{project_id}/sfs-turbo/shares/{share_id}/fs/{feature}/tasks

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释：项目ID，用于标识资源所属的IAM项目空间，实现项目级资源隔离与权限管控。获取方法请参见获取项目ID。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
share_id	是	String	参数解释：文件系统ID，用于唯一标识SFS Turbo文件系统实例。获取方法请参见查询文件系统列表接口。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
feature	是	String	参数解释：任务类型，用于标识要创建的异步任务类型。约束限制：不涉及。取值范围： dir-usage：查询目录资源使用情况任务。默认取值：不涉及。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	参数解释：用户Token，用于鉴权认证。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
Content-Type	是	String	参数解释：请求消息体MIME类型，用于标识请求正文的数据格式。约束限制：不涉及。取值范围： application/json 默认取值： application/json

表3 请求Body参数
参数	是否必选	参数类型	描述
path	是	String	参数解释：文件系统内合法的目录全路径。约束限制：必须以斜杠“/”开头，表示绝对路径。不能包含“/./”或“/../”等特殊路径符号。单层目录名称长度不能超过255个字符。全路径总长度不能超过4096个字符。取值范围：不涉及。默认取值：不涉及。

响应参数

状态码：202

表4 响应Header参数
参数	参数类型	描述
X-request-id	String	参数解释：请求ID，用于唯一标识和追踪本次请求。取值范围：不涉及。

表5 响应Body参数
参数	参数类型	描述
task_id	String	参数解释：任务ID，用于唯一标识创建的异步任务。可通过该ID查询任务执行状态和结果。取值范围：不涉及。

状态码：400

表6 响应Header参数
参数	参数类型	描述
X-request-id	String	参数解释：请求ID，用于唯一标识和追踪本次请求。取值范围：不涉及。

表7 响应Body参数
参数	参数类型	描述
errCode	String	参数解释：错误码，用于标识请求失败的原因。详细错误码请参见错误码。取值范围：不涉及。
errMsg	String	参数解释：错误描述，用于描述请求失败的具体原因，便于排查问题。请参见错误码。取值范围：不涉及。

状态码：500

表8 响应Header参数
参数	参数类型	描述
X-request-id	String	参数解释：请求ID，用于唯一标识和追踪本次请求。取值范围：不涉及。

表9 响应Body参数
参数	参数类型	描述
errCode	String	参数解释：错误码，用于标识请求失败的原因。详细错误码请参见错误码。取值范围：不涉及。
errMsg	String	参数解释：错误描述，用于描述请求失败的具体原因，便于排查问题。请参见错误码。取值范围：不涉及。

请求示例

DU任务:创建一个查询目录资源使用情况的DU任务。path为文件系统内合法的目录全路径。单层目录长度不允许超过255，全路径长度不允许超过4096。

POST HTTPS://{endpoint}/v1/{project_id}/sfs-turbo/shares/{share_id}/fs/dir-usage/tasks

{
  "path" : "/path"
}

响应示例

状态码：202

{
  "task_id" : "d651ea2b-2b20-4c6d-8bbf-2adcec18dac9"
}

状态码：400

{
  "errCode" : "SFS.TURBO.0123",
  "errMsg" : "feature invalid"
}

状态码：500

{
  "errCode" : "SFS.TURBO.0005",
  "errMsg" : "internal server error"
}

状态码

状态码	描述
202	已接受
400	错误响应
500	错误响应

错误码

请参见错误码。

父主题： 文件系统管理

上一篇：文件系统管理

下一篇：获取文件系统异步任务列表 - ListFsTasks