Help Center/ Scalable File Service Turbo/ API Reference/ API/ Tag Management/ Querying File Systems by Tag

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

Online Debugging

CLI Examples

View PDF

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.

Parent topic: Tag Management

Previous topic: Querying Tags of All File Systems of a Tenant

Next topic: Name Management

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot