Querying DB Instances

Function

This API is used to query DB instances according to search criteria.

URI

URI format
GET /v3/{project_id}/instances?id={id}&name={name}&type={type}&datastore_type={datastore_type}&group_type={group_type}&offset={offset}&limit={limit}&tags={key}={value}

Parameter description

**Table 1** Parameters
Parameter	Type	Mandatory	Description
project_id	Yes	String	Explanation: Project ID of a tenant in a region. For details about how to obtain the project ID, see Obtaining a Project ID. Constraints: N/A Value range: N/A Default value: N/A
id	String	No	Explanation: Instance ID. The asterisk () is reserved for the system. If the instance ID starts with , fuzzy match is performed based on the value following . Otherwise, the exact match is performed based on the instance ID. The value cannot contain only asterisks (). Constraints: N/A Value range: N/A Default value: N/A
name	String	No	Explanation: Instance name. The asterisk () is reserved for the system. If the instance name starts with , it indicates that fuzzy match is performed based on the value following * Otherwise, the exact match is performed based on the instance name. The value cannot contain only asterisks (). Constraints: N/A Value range: N/A Default value*: N/A
type	String	No	Explanation: Instance type. Constraints: N/A Value range: The value can be Single or Ha, indicating single-node instances or primary/standby instances, respectively. Default value: N/A
datastore_type	String	No	Explanation: DB engine. Constraints: N/A Value range: MySQL (case-sensitive) Default value: N/A
offset	Integer	No	Explanation: Index offset. Constraints: N/A Value range: If offset is set to N, the resource query starts from the N+1 piece of data. The value is 0 by default, indicating that the query starts from the first piece of data. The value cannot be a negative number. Default value: 0
limit	Integer	No	Explanation: Number of records to be queried. Constraints: N/A Value range: The default value is 100. The value cannot be a negative number. The minimum value is 1 and the maximum value is 100. Default value: 100
tags	Array of objects	No	Explanation: Tag key-value pairs of the instance. For details, see Table 2. Constraints: To query instances with multiple tag keys and values, separate key-value pairs with commas (,). A maximum of 20 key-value pairs are supported.
group_type	String	Yes	Explanation: Querying FlexusRDS instances. Constraints: N/A Value range: flexus Default value: N/A

**Table 2** tags field data structure description
Parameter	Type	Mandatory	Description
key	String	Yes	Explanation: Tag key. Constraints: N/A Value range: The value must consist of 1 to 128 Unicode characters. It can contain letters, digits, spaces, and special characters _.:=+-@. However, it cannot start or end with a space, or start with _sys_. Default value: N/A
value	String	No	Explanation: Tag value. Constraints: N/A Value range: It can be left blank or contain a maximum of 255 Unicode characters. It can contain letters, digits, spaces, and special characters _.:=+-@. Default value: N/A

Request Parameters

None

Example Request

Query all instances.

GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances

Query instances based on search criteria.

GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datastore_type=MySQL&offset=0&limit=10&tags=rds001=001,rds002=002&group_type=flexus

Response

Normal response

**Table 3** Parameter description
Parameter	Type	Description
instances	Array of objects	Explanation: Instance information. For details, see Table 4.
total_count	Integer	Explanation: Total number of records. Value range: N/A

**Table 4** instances field data structure description
Parameter	Type	Description
id	String	Explanation: Instance ID. Value range: N/A
name	String	Explanation: Instance name. Value range: N/A
status	String	Explanation: Instance status. Value range: BUILD: The instance is being created. ACTIVE: The instance is running properly. FAILED: The instance is abnormal. MODIFYING: The instance is being scaled out. REBOOTING: The instance is being rebooted. RESTORING: The instance is being restored. BACKING UP: The instance is being backed up. STORAGE FULL: The instance storage space is full.
alias	String	Explanation: Instance description. Value range: N/A
private_ips	List<String>	Explanation: Private IP addresses. It is a blank string until an instance is created.
private_dns_names	List<String>	Explanation: Private domain names. After a DB instance is created, you need to manually apply for a private domain name, or the private domain name is left blank.
public_dns_names	List<String>	Explanation: Public domain names. After a DB instance is created, you need to manually apply for a public domain name, or the public domain name is left blank.
public_ips	List<String>	Explanation: Public IP addresses.
port	Integer	Explanation: Database port. Value range: If this parameter is not specified, the default port number 3306 is used.
enable_ssl	Boolean	Explanation: Whether SSL is enabled for the instance. Value range: true: SSL is enabled for the instance. false: SSL is disabled for the instance.
type	String	Explanation: Instance type. Value range: The value can be Single or Ha, indicating single-node instances or primary/standby instances, respectively.
ha	Object	Explanation: HA information. This parameter is returned only for HA instances. For details, see Table 5.
region	String	Explanation: Region where the instance is deployed. Value range: N/A
datastore	Object	Explanation: Database information. For details, see Table 6.
created	String	Explanation: Creation time. Value range: The value is in the "yyyy-mm-ddThh:mm:ssZ" format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100. The value is empty when the DB instance is being created. After the DB instance is created, the value is not empty.
updated	String	Explanation: Update time. Value range: The value is in the "yyyy-mm-ddThh:mm:ssZ" format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100. The value is empty when the DB instance is being created. After the DB instance is created, the value is not empty.
db_user_name	String	Explanation: Default username. Value range: N/A
vpc_id	String	Explanation: VPC ID. Value range: N/A
subnet_id	String	Explanation: Subnet ID. Value range: N/A
security_group_id	String	Explanation: Security group ID. Value range: N/A
flavor_ref	String	Explanation: Specification code. Value range: N/A
cpu	String	Explanation: Number of vCPUs. For example, the value 1 indicates 1 vCPU. Value range: N/A
mem	String	Explanation: Memory size in GB. Value range: N/A
volume	Object	Explanation: Instance storage. For details, see Table 7.
switch_strategy	String	Explanation: Database failover priority. Value range: The value can be reliability or availability, indicating that the reliability or availability is given priority during the failover, respectively.
db_read_only_from_tenant	String	Explanation: Whether the database is read-only. Value range: true: The database is read-only. false: The database is not read-only.
read_only_by_user	Boolean	Explanation: Whether the instance is set to read-only. Value range: true: The instance is set to read-only. false: The instance is not set to read-only.
backup_strategy	Object	Explanation: Backup policy. For details, see Table 8.
maintenance_window	String	Explanation: Maintenance window, in the UTC format. Value range: N/A
nodes	Array of objects	Explanation: Primary/standby instance information. For details, see Table 9.
related_instance	Array of objects	Explanation: All associated DB instances. For details, see Table 10.
disk_encryption_id	String	Explanation: Disk encryption key ID. Value range: N/A
enterprise_project_id	String	Explanation: Enterprise project ID. Value range: N/A
time_zone	String	Explanation: Time zone. Value range: N/A
charge_info	Object	Explanation: Billing information. For details, see Table 11.
tags	Array of objects	Explanation: Tag list. If there is no tag added for the instance, an empty array is returned. For details, see Table 12.
order_id	String	Explanation: Order ID. Value range: N/A
associated_with_ddm	Boolean	Explanation: Whether this instance is associated with a DDM instance. Value range: N/A
expiration_time	String	Explanation: Instance expiration time. Value range: The value is in the "yyyy-mm-ddThh:mm:ssZ" format. This field is returned only for yearly/monthly instances.

**Table 5** ha field data structure description
Parameter	Type	Description
replication_mode	String	Explanation: Replication mode for the standby instance. Value range: async indicates the asynchronous replication mode. semisync indicates the semi-synchronous replication mode.

**Table 6** datastore field data structure description
Parameter	Type	Description
type	String	Explanation: DB engine. Value range: MySQL (case-insensitive)
version	String	Explanation: DB engine version. Value range: 5.7 or 8.0
complete_version	String	Explanation: Complete database version number. Value range: N/A

**Table 7** volume field data structure description
Parameter	Type	Description
type	String	Explanation: Storage type. Value range: CLOUDSSD (case-sensitive): cloud SSD storage. This storage type is supported only with general-purpose and dedicated instances.
size	Integer	Explanation: Storage space. Value range: 40–4000, in GB. The value must be a multiple of 10.

**Table 8** backup_strategy field data structure description
Parameter	Type	Description
start_time	String	Explanation: Backup time window. Automated backups will be triggered during the backup time window. Value range: The value cannot be empty. It must be a valid value in the "hh:mm-HH:MM" format. The current time is the UTC time. The HH value must be 1 greater than the hh value. The values of mm and MM must be the same and must be set to 00, 15, 30, or 45. Example: 08:15-09:15 23:00-00:00
keep_days	Integer	Explanation: Retention days for backups. Value range: 0–732. 0 indicates that the automated backup policy is disabled. To extend the retention period, contact customer service. Automated backups can be retained for up to 2,562 days.

**Table 9** nodes field data structure description
Parameter	Type	Description
id	String	Explanation: Node ID. Value range: N/A
name	String	Explanation: Node name. Value range: N/A
role	String	Explanation: Node type. Value range: master (primary node) or slave (standby node)
status	String	Explanation: Node status. Value range: creating: The node is being created. active or normal: The node is normal. abnormal: The node is abnormal. createfail: The node failed to be created. enlargefail: The node failed to be expanded. restarting: The node is being restarted. resizing: The node specifications are being changed. resizefailed: The node specifications failed to be changed. data_disk_full: The storage space is full.
availability_zone	String	Explanation: AZ. Value range: N/A

**Table 10** related_instance field data structure description
Parameter	Type	Description
id	String	Explanation: ID of the associated instance. Value range: N/A
type	String	Explanation: Type of the associated instance. Value range: replica_of: primary instance

**Table 11** chargeInfo field data structure description
Parameter	Mandatory	Type	Description
charge_mode	Yes	String	Explanation: Billing mode. Value range: prePaid: yearly/monthly billing

**Table 12** tags field data structure description
Parameter	Type	Description
key	String	Explanation: Tag key. Value range: N/A
value	String	Explanation: Tag value. Value range: N/A

The values of region and availability_zone in the example response are only for reference.

Example normal response

Query DB instances based on search criteria.

{
	"instances": [{
		"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01",
		"status": "ACTIVE",
		"name": "mysql-0820-022709-01",
		"port": 3306,
		"type": "Single",
		"region": "aaa",
		"datastore": {
			"type": "MySQL",
			"version": "5.7"
		},
		"created": "2018-08-20T02:33:49+0800",
		"updated": "2018-08-20T02:33:50+0800",
		"volume": {
			"type": "ULTRAHIGH",
			"size": 100
		},
		"nodes": [{
			"id": "06f1c2ad57604ae89e153e4d27f4e4b8no01",
			"name": "mysql-0820-022709-01_node0",
			"role": "master",
			"status": "ACTIVE",
			"availability_zone": "bbb"
		}],
                "alias": "description",
		"private_ips": ["192.168.0.1"],
		"private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.cn-xianhz-1.mysql.rds.myhuaweicloud.com"],
		"public_ips": ["10.10.10.1"],
		"db_user_name": "root",
		"vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7",
		"subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef",
		"security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97",
		"flavor_ref": "rds.mysql.s1.large",
                "switch_strategy": "",
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"disk_encryption_id": "",
		"time_zone": "",
  		"tags": [
           		 {
           		     "key": "rds001",
           		     "value": "001"
         		   },
       		     {
           		     "key": "rds002",
           		     "value": "002"
    		        }
    	     ]
        	}],
	"total_count": 1
}

Query all DB instances.

{
	"instances": [{
		"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01",
		"status": "ACTIVE",
		"name": "mysql-0820-022709-01",
		"port": 3306,
		"type": "Single",
		"region": "aaa",
		"datastore": {
			"type": "MySQL",
			"version": "5.7"
		},
		"created": "2018-08-20T02:33:49+0800",
		"updated": "2018-08-20T02:33:50+0800",
		"volume": {
			"type": "ULTRAHIGH",
			"size": 100
		},
		"nodes": [{
			"id": "06f1c2ad57604ae89e153e4d27f4e4b8no01",
			"name": "mysql-0820-022709-01_node0",
			"role": "master",
			"status": "ACTIVE",
			"availability_zone": "bbb"
		}],
                "alias": "description",
		"private_ips": ["192.168.0.1"],
		"private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.cn-xianhz-1.mysql.rds.myhuaweicloud.com"],
		"public_ips": ["10.10.10.1"],
		"db_user_name": "root",
		"vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7",
		"subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef",
		"security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97",
		"flavor_ref": "rds.mysql.s1.large",
                "cpu": "2",
                "mem": "4",
		"switch_strategy": "",
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"disk_encryption_id": "",
		"time_zone": "",
                "tags": [
                    {
                        "key": "rds001",
                        "value": "001"
                    },
                    {
                        "key": "rds002",
                        "value": "002"
                    }
                 ],
		"associated_with_ddm": false
	}, {
		"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in02",
		"status": "ACTIVE",
		"name": "mysql-0820-022709-02",
		"port": 3306,
		"type": "Single",
		"region": "aaa",
		"datastore": {
			"type": "MySQL",
			"version": "5.6"
		},
		"created": "2019-08-20T02:33:49+0800",
		"updated": "2019-08-20T02:33:50+0800",
		"volume": {
			"type": "ULTRAHIGH",
			"size": 100
		},
		"nodes": [{
			"id": "06f1c2ad57604ae89e153e4d27f4e4b8no01",
			"name": "mysql-0820-022709-01_node0",
			"role": "master",
			"status": "ACTIVE",
			"availability_zone": "bbb"
		}],
                "alias": "description",
		"private_ips": ["192.168.0.1"],
		"private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.cn-xianhz-1.mysql.rds.myhuaweicloud.com"],
		"public_ips": ["10.10.10.1"],
		"db_user_name": "root",
		"vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7",
		"subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef",
		"security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97",
		"flavor_ref": "rds.mysql.s1.large",
                "cpu": "2",
                "cpu": "4",
		"switch_strategy": "",
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"disk_encryption_id": "",
		"time_zone": "",
                "tags": [
                    {
                        "key": "rds001",
                        "value": "001"
                    },
                    {
                        "key": "rds002",
                        "value": "002"
                    }
                 ],
		"associated_with_ddm": false
	}],
	"total_count": 2
}