Updated on 2025-07-22 GMT+08:00

Querying File Systems by Tag

Function

This API is used to query file systems by tag.

URI

POST /v1/{project_id}/sfs-turbo/resource_instances/action

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

The project ID.

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.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

action

Yes

String

The operation type of listing file systems by tag. The value can be filter or count.

Enumeration values:

  • filter

  • count

limit

No

String

The maximum number of file systems returned.

offset

No

String

The offset of the returned file systems.

without_any_tag

No

Boolean

The resources to be queried contain no tags. If this parameter is set to true, all resources without specified tags are queried. In this case, the tags field is ignored. If this parameter is set to false or not specified, it does not take effect, meaning that all resources are returned or resources are filtered by tags or matches.

tags

No

Array of Tag objects

The resources to be queried contain tags specified in this field. Each resource can contain a maximum of 20 keys. Each tag key can have a maximum of 20 tag values. The tag value corresponding to each tag key can be an empty array but the structure cannot be missing. Each tag key must be unique, and tag values of the same tag must be unique. The response returns resources containing all tags in this list. Keys in this list are in the AND relationship and values in each key-value structure are in the OR relationship. If no tag filtering criteria is specified, all data is returned.

matches

No

Array of ResourceTag objects

The search criteria. key is the field to match. Only resource_name is supported. value is the matched value. If the value ends with *, prefix search will be performed. For example, if the value is sfsturbo*, all resources whose names start with sfsturbo will be returned.

Table 4 Tag

Parameter

Mandatory

Type

Description

key

Yes

String

The tag key.

A key can contain a maximum of 128 characters and cannot be left blank.

values

Yes

Array of strings

The list the tag values. Each value can contain a maximum of 255 characters. An empty list for values indicates any value. The values are in the OR relationship.

Table 5 ResourceTag

Parameter

Mandatory

Type

Description

key

Yes

String

The tag key.

It can contain a maximum of 128 characters.

It cannot be left empty and cannot contain the following characters: ASCII (0-31), equal signs (=), asterisks (*), left angle brackets (<), right angle brackets (>), backslashes (), commas (,), vertical bars (|), and slashes (/). It can contain only letters, digits, hyphens (-), and underscores (_).

value

Yes

String

The tag value.

Each tag value can contain a maximum of 255 characters and can be an empty string.

It cannot contain the following characters: ASCII (0-31), equal signs (=), asterisks (*), left angle brackets (<), right angle brackets (>), backslashes (), commas (,), vertical bars (|), and slashes (/). It can contain only letters, digits, hyphens (-), and underscores (_).

Response Parameters

Status code: 200

Table 6 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.

Table 7 Response body parameters

Parameter

Type

Description

resources

Array of ListSharesByTagResource objects

The list of file systems queried by tag.

total_count

Integer

The total number of file systems returned.

Table 8 ListSharesByTagResource

Parameter

Type

Description

resource_id

String

The resource ID.

resource_name

String

The resource name.

resource_detail

String

The resource details.

tags

Array of ResourceTag objects

The resource tag list.

Table 9 ResourceTag

Parameter

Type

Description

key

String

The tag key.

It can contain a maximum of 128 characters.

It cannot be left empty and cannot contain the following characters: ASCII (0-31), equal signs (=), asterisks (*), left angle brackets (<), right angle brackets (>), backslashes (), commas (,), vertical bars (|), and slashes (/). It can contain only letters, digits, hyphens (-), and underscores (_).

value

String

The tag value.

Each tag value can contain a maximum of 255 characters and can be an empty string.

It cannot contain the following characters: ASCII (0-31), equal signs (=), asterisks (*), left angle brackets (<), right angle brackets (>), backslashes (), commas (,), vertical bars (|), and slashes (/). It can contain only letters, digits, hyphens (-), and underscores (_).

Status code: 400

Table 10 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.

Table 11 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Status code: 500

Table 12 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.

Table 13 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Example Requests

  • Filtering file systems by file system tag

    {
      "action" : "filter",
      "limit" : 10,
      "offset" : 10,
      "tags" : [ {
        "key" : "key1",
        "values" : [ "value1", "value2" ]
      }, {
        "key" : "key2",
        "values" : [ "value1", "value2" ]
      } ]
    }
  • Filtering file systems by file system name

    {
      "action" : "filter",
      "matches" : [ {
        "key" : "resource_name",
        "value" : "sfsturbo*"
      } ]
    }

Example Responses

Status code: 400

Error response

{
  "errCode" : "SFS.TURBO.0001",
  "errMsg" : "parameter error"
}

Status code: 500

The error response.

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

Status Codes

Status Code

Description

200

Success

400

Error response

500

The error response.

Error Codes

See Error Codes.