Querying the Resource Instance List

Function

This API is used to query the resource instance list by tag.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/{resource_type}/resource-instances/filter

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID, which is used to specify the project that a resource belongs to. You can query the resources of a project by project ID. You can obtain the project ID from the API or console. Obtaining the Project ID Constraints N/A Range N/A Default Value N/A
resource_type	Yes	String	Resource type.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
limit	No	String	Number of records to be queried. This parameter is not available when action is set to count. If action is set to filter, the default value is 1000. The maximum value is 1000, and the minimum value is 1. The value cannot be a negative number.
offset	No	String	Index position. This parameter is not available when action is set to count. If offset is set to N, the resource query starts from the N+1 piece of data. If action is set to filter, the value of offset is 0 by default, indicating that the query starts from the first piece of data. The offset value must be a number and cannot be a negative number.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
Content-type	Yes	String	Definition Content type. application/json;charset=UTF-8: common API request type Constraints N/A Range application/json;charset=UTF-8 Default Value N/A
X-Auth-Token	Yes	String	User token. You can call the IAM API to obtain a user token. The value of X-Subject-Token in the response header is the user token.

**Table 4** Request body parameters
Parameter	Mandatory	Type	Description
without_any_tag	No	Boolean	If this parameter is set to true, all resources without tags are queried. In this case, the tags, tags_any, not_tags, and not_tags_any fields are not required.
tags	No	Array of WorkspaceTag objects	Resources to be queried contain tags specified in this field. Each resource can contain a maximum of 50 keys. Each tag key can have a maximum of 10 tag values. The tag value corresponding to each tag key can be an empty array but the structure cannot be missing. Each key must be unique, and each value for a key must be unique. The response returns instances 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 are specified, all data is returned.
sys_tags	No	Array of WorkspaceTag objects	Only users with the permission op_service can use this field to filter resources. Currently, TMS can invoke only one tag structure. Key: _sys_enterprise_project_id. Value: enterprise project ID list. Currently, TMS can invoke only one value under key. 0 indicates the default enterprise project. sys_tags cannot be used together with tenant tag filtering criteria (without_any_tag, tags, tags_any, not_tags, and not_tags_any). If sys_tags is not specified, resources with all the tags specified in tags will be returned. If tags is not specified, all resources will be returned.
matches	No	Array of Match objects	The search field. The tag key is the field to be matched, for example, resource_name. The tag value indicates the value to be matched. The key is a fixed dictionary value and cannot be a duplicate key or unsupported key. Check whether fuzzy match is required based on the key value. For example, if key is set to resource_name, fuzzy search (case-insensitive) is performed by default. If value is empty, exact match is performed. Most services do not have resources without names. In this case, an empty list is returned. For search by resource_id, exact match is used. Only resource_name is supported currently. More fields will be supported later.

**Table 5** WorkspaceTag
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. It can contain a maximum of 128 Unicode characters. The tag key cannot be left blank. The system does not verify the character set of key when searching for resources. key cannot be empty, an empty string, or spaces. Before using key, delete single-byte character (SBC) spaces before and after the value.
values	Yes	Array of strings	The tag value list. Each value can contain a maximum of 255 Unicode characters. Before verification and usage, delete SBC spaces before and after the value. The value can be an empty array but cannot be left blank. If values is left empty, it indicates any value. All values of a tag key are in the OR relationship.

**Table 6** Match
Parameter	Mandatory	Type	Description
key	Yes	String	Key. Currently, only resource_name is supported. Other key values will be available later.
value	Yes	String	Value. Each value can contain a maximum of 255 Unicode characters. The character set is not verified.

Response Parameters

Status code: 200

**Table 7** Response body parameters
Parameter	Type	Description
resources	Array of ResourceInfo objects	Resource information.
total_count	Integer	Total resources.

**Table 8** ResourceInfo
Parameter	Type	Description
resource_id	String	Resource ID.
tags	Array of Match objects	Tag.
sys_tags	Array of Match objects	System tags.
resource_name	String	Resource name.
resource_detail	Object	Resource details.

**Table 9** Match
Parameter	Type	Description
key	String	Key. Currently, only resource_name is supported. Other key values will be available later.
value	String	Value. Each value can contain a maximum of 255 Unicode characters. The character set is not verified.

Status code: 400

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 401

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 403

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 404

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 500

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Example Requests

POST /v1/{project_id}/{resource_type}/resource_instances/filter

{
  "offset" : "100",
  "limit" : "100",
  "matches" : [ {
    "key" : "resource_name",
    "value" : "resource1"
  } ],
  "not_tags" : [ {
    "key" : "key1",
    "values" : [ "*value1", "value2" ]
  } ],
  "tags" : [ {
    "key" : "key1",
    "values" : [ "*value1", "value2" ]
  } ],
  "tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "not_tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "sys_tags" : [ {
    "key" : "_sys_enterprise_project_id",
    "values" : [ "5aa119a8-d25b-45a7-8d1b-88e127885635" ]
  } ]
}

Example Responses

Status code: 200

Request succeeded.

{
  "not_tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "*value2" ]
  } ],
  "tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  }, {
    "key" : "key2",
    "values" : [ "value1", "value2" ]
  } ],
  "tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "not_tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "sys_tags" : [ {
    "key" : "_sys_enterprise_project_id",
    "values" : [ "5aa119a8-d25b-45a7-8d1b-88e127885635" ]
  } ],
  "matches" : [ {
    "key" : "resource_name",
    "value" : "resource1"
  } ]
}