Help Center/ Scalable File Service/ API Reference/ SFS Turbo APIs/ File System Management/ Creating an Asynchronous Task for a File System
Updated on 2025-04-28 GMT+08:00
View PDF
Share

Creating an Asynchronous Task for a File System

Function

This API is used to create an asynchronous task for a file system. Only tasks for querying the directory usage can be created. Such tasks are also referred to as DU tasks. The value of feature in the API request path is dir-usage.

Constraints

This API is only supported for file systems created after August 1, 2023. If there are 10 tasks being executed, no more task can be created. You are advised not to submit five or more requests at a time, or the file system performance may be affected. It takes some time to query an oversized directory. Do not submit the request repeatedly. The value of feature in the API request path can only be the following:

  • dir-usage

This API is only supported for the following types of file systems:

  • 20 MB/s/TiB

  • 40 MB/s/TiB

  • 125 MB/s/TiB

  • 250 MB/s/TiB

  • 500 MB/s/TiB

  • 1,000 MB/s/TiB

For SFS Turbo Standard, Standard-Enhanced, Performance, Performance-Enhanced file systems, use the API for querying the file system directory usage.

URI

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

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

The project ID.

share_id

Yes

String

The file system ID.

feature

Yes

String

The task type, which can only be dir-usage.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

The account token.

Content-Type

Yes

String

The MIME type, which can be application or json.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

path

Yes

String

The valid full path of a directory in the file system. The length of a single-level directory cannot exceed 255 characters, and that of a full path cannot exceed 4,096 characters.

Response Parameters

Status code: 202

Table 4 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 5 Response body parameters

Parameter

Type

Description

task_id

String

The task ID.

Status code: 400

Table 6 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 7 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Status code: 500

Table 8 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 9 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Example Requests

The following example creates a DU task for querying the directory resource usage. path is a valid full path of a directory in the file system. The length of a single-level directory cannot exceed 255 characters, and that of a full path cannot exceed 4,096 characters.

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

{
  "path" : "/path"
}

Example Responses

Status code: 202

Accepted

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

Status code: 400

Error response

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

Status code: 500

Error response

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

Status Codes

Status Code

Description

202

Accepted

400

Error response

500

Error response

Error Codes

See Error Codes.

Parent topic: File System Management