Querying Resources by Tag¶

Function¶

You can use this API to filter resources by tag.

URI¶

POST /v1.0/resource-instances/filter

Request¶

**Table 1** Header parameters¶
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Specifies the user token. TMS is a global service. So you need to set scope to domain when calling an IAM API to obtain a user token. The value of X-Subject-Token in the response header is the user token.

**Table 2** Body parameters¶
Parameter	Mandatory	Type	Description
project_id	No	String	Project ID. This parameter is mandatory when resource_type is a region-specific service.
resource_types	Yes	Array of strings	Resource type. This parameter is case-sensitive. Supported resource types can be provided as ecs,scaling_group, images, disk,vpcs,security-groups, shared_bandwidth,eip, cdn.
tags	Yes	Array of Tag objects	Tags
without_any_tag	No	Boolean	Specifies whether to query only untagged resources. If this parameter is set to true, only untagged resources are queried.
offset	No	Integer	Index position. The query starts from the next data specified by offset. The value must be a number and cannot be negative. The default value is 0.
limit	No	Integer	The maximum queries supported. The value 200 is used by default if this parameter is not set. The value range is 1 to 200.

**Table 3** Tag¶
Parameter	Mandatory	Type	Description
key	Yes	String	Key. It can contain up to 36 characters. The key cannot be empty. Only digits, letters, hyphens (-), at signs (@), and underscores (_) are allowed.
values	Yes	Array of strings	Specifies tag values. Each value contains a maximum of 43 Unicode characters and can be an empty string. Only digits, letters, hyphens (-), at signs (@), and underscores (_) are allowed.

Response¶

Status code: 200

**Table 4** Body parameters¶
Parameter	Type	Description
resources	Array of Resources objects	Specifies resources.
errors	Array of Errors objects	Specifies resources of the tag.
total_count	Integer	Specifies the total number of resources of the tag.

**Table 5** Resources¶
Parameter	Type	Description
project_id	String	ProjectID
project_name	String	Specifies the project name.
resource_id	String	Specifies the resource ID.
resource_name	String	Specifies the resource name.
resource_type	String	Specifies the resource type.
tags	Array of FilterTagResponse objects	Specifies the resource tag.

**Table 6** FilterTagResponse¶
Parameter	Type	Description
key	String	Specifies the key. It can contain up to 36 characters. The key cannot be empty. Only digits, letters, hyphens (-), at signs (@), and underscores (_) are allowed.
value	String	Specifies the value. Each value contains a maximum of 43 Unicode characters and can be an empty string. Only digits, letters, hyphens (-), at signs (@), and underscores (_) are allowed.

**Table 7** Errors¶
Parameter	Type	Description
error_code	String	Specifies the error code.
error_msg	String	Specifies the error.
project_id	String	ProjectID
resource_type	String	Specifies the resource type.

Example Request¶

Filtering resources by tag

POST https://v1.0/resource-instances/filter

{
  "project_id" : "e1eb7c40cbeaxxxxxxcde527594a306d",
  "resource_types" : [ "disk", "ecs" ],
  "tags" : [ {
    "key" : "env",
    "values" : [ "dev", "prod" ]
  }, {
    "key" : "test",
    "values" : [ "test" ]
  } ],

  "without_any_tag" : true,
  "offset" : 0,
  "limit" : 10
}

Example Response¶

Status code: 200

Successful operation

{
  "resources" : [ {
    "project_id" : "e1eb7c40cbeaxxxxxxde527594a306d",
    "project_name" : "XXXX",
    "resource_type" : "disk",
    "resource_id" : "b621f5ae-xxxx-xxxx-xxxx-752c445434b4",
    "resource_name" : "xxx1-volume-0001",
    "tags" : [ {
      "key" : "ENV",
      "value" : "dev"
    } ]
  }, {
    "project_id" : "e1eb7c40cbxxxxxx89cde527594a306d",
    "project_name" : "XXXX",
    "resource_type" : "disk",
    "resource_id" : "87c9edc9-xxxx-xxxx-xxxx-372b2e22d579",
    "resource_name" : "xxx2-volume-0002",
    "tags" : [ {
      "key" : "test",
      "value" : "test"
    } ]
  } ],
  "errors" : [],
  "total_count" : 2
}

Status Codes¶

See Status Codes.

Error Codes¶

See Error Codes.

last updated: 2025-02-13 16:04 UTC - commit: ec1616a32d88242efd3e55ad5f07c909b7471752