Querying Resource Instances

Updated on 2023-11-23 GMT+08:00

View PDF

Function

This API is used to filter instances by tag.

URI

POST /v2/{project_id}/{resource_type}/resource_instances/action

**Table 1** Path parameters
Parameter	Type	Description
project_id	String	Project ID. For details about how to obtain a project ID, see Obtaining a Project ID.
resource_type	String	Resource type. ief-edge_node ief-deployment ief-application ief-device

Request

Request parameters

**Table 2** Parameters in the request header
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Message body type (format). The default value application/json is recommended.
X-Auth-Token	Yes	String	User token. The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

**Table 3** Parameters in the request body
Parameter	Mandatory	Type	Description
tags	No	Array of tag objects	The instances to be queried contain tags listed in tags. Each instance to be queried contains a maximum of 20 keys. Each tag key has 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 tag key must be unique, and each tag value in a tag 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 both tags_any and tags fields are specified, the union set of the two fields is returned after deduplication. If no filtering condition is specified, full data is returned.
tags_any	No	Array of tag objects	The instances to be queried contain any tag listed in tags_any. Each instance to be queried contains a maximum of 20 keys. Each tag key has a maximum of 10 tag values. Each tag key must be unique, and each tag value in a tag must be unique. The response returns instances containing any tag in this list. Keys in this list are in the OR relationship and values in each key-value structure are also in the OR relationship. If both tags_any and tags fields are specified, the union set of the two fields is returned after deduplication. If no filtering condition is specified, full data is returned.
not_tags	No	Array of tag objects	The instances to be queried do not contain any tag listed in this field. Each instance to be queried contains a maximum of 20 keys. Each tag key has a maximum of 10 tag values. Each tag key must be unique, and each tag value in a tag must be unique. The response returns instances containing no tag in this list. Keys are in the AND relationship and values in each key-value structure is in the OR relationship. If no filtering condition is specified, full data is returned.
not_tags_any	No	Array of tag objects	The instances to be queried do not contain all tags listed in this field. Each instance to be queried contains a maximum of 20 keys. Each tag key has a maximum of 10 tag values. Each tag key must be unique, and each tag value in a tag must be unique. The response returns resources containing no tag in this list. Keys in this list are in the OR relationship and values in each key-value structure are also in the OR relationship. If no filtering condition is specified, full data is returned.
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.
action	Yes	String	Operation to be performed. The value can only be filter or count. If action is set to filter, the query is performed based on the filter criteria. If action is set to count, only the total number of records is returned.
matches	No	Array of match objects	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 contain duplicate keys or unsupported keys. This field determines whether fuzzy match is required based on the keys. For example, if key is resource_name, fuzzy match (case insensitive, not supporting , and supporting character string matching) is used by default. If value* is empty, an empty list is returned because for IEF, resource_name cannot be left blank.
console	No	Boolean	This field is used to check whether the request is initiated from the console to determine whether the content of resource_detail is returned. If the value is true, the content is returned. If the value is false or the parameter is not contained, an empty list is returned.
sorted	No	Table 31 object	Sorting mode of results returned after resources are filtered by tag.

**Table 4** tag
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key, which can contain a maximum of 36 Unicode characters. It cannot be left blank. The character set of this parameter is not verified during search. Key cannot be empty, an empty string, or spaces. Before verifying and using key, delete spaces of single-byte character (SBC) before and after the value.
values	No	Array of strings	List of tag values. Each value contains a maximum of 43 Unicode characters. Before verifying and using this field, delete SBC spaces before and after the value. The asterisk () is reserved for the system. If the value starts with , it indicates that fuzzy match is performed based on the value following . The value cannot contain only asterisks (). If values is left blank, it indicates any_value (querying any value). All values of a tag key are in the OR relationship.

**Table 5** match
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. Currently, only resource_name is supported.
value	No	String	Tag value. Each tag value can contain a maximum of 64 Unicode characters. The character set range is not verified.

Example request

When action is set to filter:

{
    "action": "filter",
    "limit": "10",
    "offset": "0",
    "matches":[{"key":"resource_name","value":"q"}],
    "tags":[
        {
            "key":"test",
            "values": ["value1","value2"]
        }
        ]
}

Response

Response parameters

**Table 6** Parameters in the response body
Parameter	Mandatory	Type	Description
resources	Yes	Array of resource objects	Resource instances.
total_count	Yes	Integer	Total number of records.

**Table 7** resource
Parameter	Mandatory	Type	Description
resource_id	Yes	String	Resource ID.
tags	Yes	Array of resource_tag objects	A list of tags. This parameter is an empty array by default if there is no tag.
resource_name	Yes	String	Resource name. This parameter is an empty string by default if there is no resource name.

**Table 8** resource_tag
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key.
value	Yes	String	Tag value.

Example response

When action is set to filter:

{
    "total_count": 2,
    "resources": [
        {
            "tags": [
                {
                    "value": "",
                    "key": "testtest"
                },
                {
                    "value": "value2",
                    "key": "test"
                }
            ],
            "resource_name": "node_test_0108_1",
            "resource_id": "e25307d4-bd25-4c29-ba7f-176376ed2f99"
        },
        {
            "tags": [
                {
                    "value": "value1",
                    "key": "key1"
                },
                {
                    "value": "",
                    "key": "test"
                }
            ],
            "resource_name": "node_test-0109_1",
            "resource_id": "fc3aeee8-24e1-4912-bf7a-54854251d0e5"
        }
    ]
}

Response body when action is set to count: