Help Center/ Database Security Service/ API Reference (Paris and Amsterdam Regions)/ API/ Tag APIs/ Querying Resource Instances by Tag

Updated on 2024-01-15 GMT+08:00

View PDF

Querying Resource Instances by Tag

Function

This API is used to query resource instances by tag.

URI

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

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID
resource_type	Yes	String	Resource type. Default usage: auditInstance

**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	The 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	The fixed value of this parameter is application/json;charset=UTF-8, which cannot be changed.
X-Auth-Token	Yes	String	User token

**Table 4** Request body parameters
Parameter	Mandatory	Type	Description
matches	No	Array of matches objects	Specifies 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. If key is resource_id, exact match is used. Only resource_name for key is supported. Other key values will be available later.
not_tags	No	Array of TagKeyValuesBean objects	Tags are excluded, a maximum of 50 tag keys are included, and each tag value can have a maximum of 10 values. Each tag value can be an empty array, but the tag structure cannot be missing. Keys must be unique and values of a key 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.
tags	No	Array of TagKeyValuesBean objects	The resources to be queried contain tags listed in tags. Each instance to be queried contains a maximum of 50 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 and each value of the same tag 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 is specified, full data is returned.
tags_any	No	Array of TagKeyValuesBean objects	Any tags are included. A maximum of 50 tag keys are included, and each tag key can have a maximum of 10 values. Each tag value can be an empty array, but the tag structure cannot be missing. Keys must be unique and values of a key 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 no filtering condition is specified, full data is returned.
not_tags_any	No	Array of TagKeyValuesBean objects	Tags are excluded, a maximum of 50 tag keys are included, and each tag key can have a maximum of 10 values. Each tag value can be an empty array, but the tag structure cannot be missing. Keys must be unique and values of a key 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.
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 ignored.

**Table 5** matches
Parameter	Mandatory	Type	Description
key	No	String	Key
value	No	String	Value

**Table 6** TagKeyValuesBean
Parameter	Mandatory	Type	Description
key	Yes	String	Specifies the tag key. It can contain up to 128 Unicode characters. It 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	Specifies the tag values. Each value contains a maximum of 255 Unicode characters. Before verifying and using values, delete SBC spaces before and after the value.The tag value can be an empty array but cannot be left blank.If values is left blank, it indicates any_value (querying any value). All values of a tag key are in the OR relationship.

Response Parameters

Status code: 200

**Table 7** Response body parameters
Parameter	Type	Description
resources	Array of resources objects	Resource instance list
total_count	Integer	Total number of records.

**Table 8** resources
Parameter	Type	Description
resource_detail	Object	Resource details. Resource details are used for extension. This parameter is left blank by default.
resource_id	String	Resource ID (DBSS instances ID, the instance ID is not in the basic information.) This parameter can be obtained through the interface : GET /v1/{project_id}/dbss/audit/instances
resource_name	String	Specifies the resource name. If the resource does not have a name, the ID is returned.
tags	Array of tags objects	The tag list. This parameter is an empty array by default if there is no tag.

**Table 9** tags
Parameter	Type	Description
key	String	Key
value	String	Value

**Table 10** sys_tags
Parameter	Type	Description
key	String	Key
value	String	Value

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 12** ErrorDetail
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error information.

Status code: 403

**Table 13** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 14** ErrorDetail
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error information.

Status code: 500

**Table 15** Response body parameters
Parameter	Type	Description
error	Object	Error message.

**Table 16** ErrorDetail
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error information.

Example Requests

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

{
  "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" ]
  } ]
}

Example Responses

Status code: 200

Success

{
  "resources" : [ {
    "resource_detail" : null,
    "resource_id" : "cdfs_cefs_wesas_12_dsad",
    "resource_name" : "resouece1",
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value1"
    } ]
  "total_count" : 1000
}

Status code: 400

Failure

{
  "error" : {
    "error_code" : "DBSS.XXXX",
    "error_msg" : "XXX"
  }
}

Status Codes

Status Code	Description
200	Success
400	Failure
403	Authentication failed.
500	Server error.

Error Codes

See Error Codes.

Parent topic: Tag APIs

Previous topic: Querying Project Tags

Next topic: Querying the Number of Resource Instances by Tag

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