Querying Instances by Tags

Function

This API is used to query instance by tags.

URI

POST /v2/{project_id}/cbs/instance/filter

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID For details about how to obtain the project ID, see "Obtaining a Project ID".

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token It 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. For details, see "Obtaining the Token of an IAM User."
limit	No	String	Specifies the 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.
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.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
without_any_tag	No	Boolean	Specifies any tag that is not contained. 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.
tags	No	Array of Tags objects	The resources to be queried contain tags listed in tags. Each resource to be queried contains 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. The key must be unique, and the values of the same key must be unique. Resources containing all tags are returned. Keys in this list are in AND relationship. While values in the key-value pairs are in OR relationship. If no tag filtering condition is specified, full data is returned.
tags_any	No	Array of Tags objects	The resources to be queried contain any tags listed in tags_any. Each resource to be queried contains 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 tag key must be unique, and each value of the same key must be unique. The response returns resources containing the tags in this list. Keys in this list are in an OR relationship and values in each key-value structure are also in an OR relationship. If no tag filtering condition is specified, full data is returned.
not_tags	No	Array of Tags objects	The resources to be queried do not contain tags listed in not_tags. Each resource to be queried contains 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 tag key must be unique, and each value of the same key must be unique. The response returns resources containing no tags in this list. Keys in this list are in an AND relationship while values in each key-value structure are in an OR relationship. If no filtering condition is specified, full data is returned.
not_tags_any	No	Array of Tags objects	The resources to be queried do not contain any tags listed in not_tags_any. Each resource to be queried contains 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 tag key must be unique, and each value of the same 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 tag filtering criteria is specified, full data is returned.
sys_tags	No	Array of Tags objects	Only users with the op_service permission can use this field to filter resources. Only one tag structure is contained when this API is called by Tag Management Service (TMS). key: _sys_enterprise_project_id value: Enterprise project ID list. Currently, key contains only one value. 0 indicates the default enterprise project. sys_tags and tenant tag filtering conditions (without_any_tag, tags, tags_any, not_tags, and not_tags_any) cannot be used at the same time. If sys_tags is not specified, filter the resources with other tag filtering criteria. If no tag filtering criteria is specified, full data is returned.
matches	No	Array of Match objects	Search field. The tag key is the field to be matched, for example, resource_name. The value is a matched value. 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. resource_id indicates exact match. Only resource_name is used now.

**Table 4** Tags
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. NOTE: Note: A key can contain 1 to 128 characters. A key can contain UTF-8 letters, digits, spaces, and the following characters: _. : = + - @ Do not enter labels starting with *sys, which are system labels. Recommended regular expression: ^((?!sys)[\p{L}\p{Z}\p{N}_.:=+\-@])$
values	Yes	Array of strings	List of tag values. NOTE: Note: A value can contain 0 to 255 characters. Can contain UTF-8 letters, digits, spaces, and the following characters: . : / = + - @ Recommended regular expression: ^([\p{L}\p{Z}\p{N}.:/=+-@]*)$ The value can be empty or null. The value of a predefined tag cannot be empty or null.

**Table 5** Match
Parameter	Mandatory	Type	Description
key	Yes	String	Tag 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 6** Response body parameters
Parameter	Type	Description
resources	Array of Resources objects	Resource instance details obtained by the query mode.
total_count	Integer	Total records.

**Table 7** Resources
Parameter	Type	Description
resource_id	String	Instance ID.
resource_detail	InstanceDetail object	CBH instance details
tags	Array of ResourceTag objects	Tags.
sys_tags	Array of ResourceTag objects	sys_tags.
resource_name	String	Resource name.

**Table 8** InstanceDetail
Parameter	Type	Description
name	String	CBH instance name.
server_id	String	ID of the server where the CBH instance is deployed..
instance_id	String	CBH instance ID.
alter_permit	Boolean	Whether the CBH instance can be expanded. true: Yes false: No
enterprise_project_id	String	Project ID.
period_num	String	Number of subscription periods of a CBH instance.
start_time	String	Start time of the CBH instance, in timestamp format.
end_time	String	End time of the CBH instance, in timestamp format.
created_time	String	Time when the CBH instance was created, in UTC format.
upgrade_time	Long	Upgrade schedule of the CBH instance, in the format of timestamp.
update	String	Whether the CBH instance can be upgraded. OLD: The current version is the latest one. NEW: Can be upgraded. CROSS_OS: Can be upgraded to any later versions. ROLLBACK: Can be rolled back. Enumeration values: OLD NEW CROSS_OS ROLLBACK
bastion_version	String	Current version of the CBH instance.
az_info	az_info object	AZ information.
status_info	status_info object	Status information.
resource_info	resource_info object	Resource information.
network	network object	Network information.
ha_info	ha_info object	Active and standby node information.

**Table 9** az_info
Parameter	Type	Description
region	String	ID of the AZ where the CBH instance locates.
zone	String	ID of the AZ where the CBH instance locates. (In primary/standby mode, the ID of the AZ where the primary instance locates is required.)
availability_zone_display	String	AZ where the CBH instance locates. (In primary/standby mode, the ID of the AZ where the primary instance locates is required. Name)
slave_zone	String	AZ where the standby CBH instance locates.
slave_zone_display	String	AZ where the standby CBH instance locates.

**Table 10** status_info
Parameter	Type	Description
status	String	CBH instance status SHOUTOFF: Closed ACTIVE: Running DELETING: Deleting BUILD: Creating DELETED: Deleting ERROR: Faulty HAWAIT: Waiting for the standby node to be created FROZEN: Frozen UPGRADING: Upgrading UNPAID: Pending Payment RESIZE: Changing specifications DILATATION: Expanding capacity HA: Configuring HA
task_status	String	CBH instance status. powering-on: Started powering-off: Stopped rebooting: Rebooting delete_wait: Deleting frozen: Frozen NO_TASK: Running unfrozen: Unfrozen alter: Changing updating: Upgrading configuring-ha: Configuring HA data-migrating: Migrating data rollback: Rolling back to the previous version. traffic-switchover: Traffic switching
create_instance_status	String	Status of a CBH instance during instance creation. Waiting for payment: Waiting for payment creating-network: Creating a network. creating-server: Creating the service. tranfering-horizontal-network: Establishing network connections. adding-policy-route: Adding a routing policy. configing-dns: Configuring DNS. starting-cbs-service: The service is running. setting-init-conf: Initializing buying-EIP: Buying an EIP.
instance_status	String	CBH instance status. building: Creating deleting: Deleting deleted: Deleted unpaid: Unpaid upgrading: Upgrading resizing: Resizing abnormal: Abnormal error: Faulty ok: Normal
instance_description	String	CBH instance description.
fail_reason	String	Instance creation failure causes.

**Table 11** resource_info
Parameter	Type	Description
specification	String	CBH instance specifications.
order_id	String	Order ID.
resource_id	String	CBH instance ID, in the UUID format.
data_disk_size	Number	Size of the data disk for the CBH instance, in TB.
disk_resource_id	Array of strings	ID of the data disk for the CBH instance.

**Table 12** network
Parameter	Type	Description
vip	String	Floating IP address of the CBH instance (This field is returned when the instance is deployed in primary/standby mode.)
web_port	String	Port used for accessing the CBH instance with a web browser.
public_ip	String	EIP bound to the CBH instance.
public_id	String	ID of the EIP bound to the CBH instance, in the UUID format.
private_ip	String	Private IP address of the CBH instance
vpc_id	String	ID of the VPC where the CBH instance locates.
subnet_id	String	ID of the subnet where the CBH instance locates.
security_group_id	String	ID of the Security group where the CBH instance locates.

**Table 13** ha_info
Parameter	Type	Description
ha_id	String	IDs of the primary and standby instances.
instance_type	String	Instance type. The value can be: master: Primary instance slave: Standby instance

**Table 14** ResourceTag
Parameter	Type	Description
key	String	Tag key. The value can contain up to 128 characters.
value	String	Tag value. A maximum of 255 characters are allowed for a tag value.

Status code: 400

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code
error_description	String	Incorrect request parameters.

Status code: 401

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Error code
error_description	String	Failed to verify the token.

Status code: 403

**Table 17** Response body parameters
Parameter	Type	Description
error_code	String	Error code
error_description	String	Permissions required.

Status code: 404

**Table 18** Response body parameters
Parameter	Type	Description
error_code	String	Error code
error_description	String	Not CBH instances found.

Example Requests

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

List CBH ByTags Success

{
  "resources" : [ {
    "resource_id" : "cdfs_cefs_wesas_12_dsad",
    "resource_name" : "resouece1",
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value1"
    } ],
    "sys_tags" : [ {
      "key" : "_sys_enterprise_project_id",
      "value" : "5aa119a8-xxxx-45a7-xxxx-88e12788xxxx"
    } ]
  } ],
  "total_count" : 1000
}