doc-exports/docs/tms/api-ref/ListResource.html

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 cannot be left blank and can contain a maximum of 36 Unicode characters. 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 cannot be left blank and can contain a maximum of 36 Unicode characters. 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.

Parent topic: Resource Tags