Querying DB Instances_DB Instance Management_API_API Reference_Huawei Cloud Flexus

Function

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

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
rds:instance:listAll	read	-	-	rds:instance:list	-

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	Definition 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 Range N/A Default Value N/A
id	String	No	Definition 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 Range N/A Default Value N/A
name	String	No	Definition 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 Range N/A Default Value N/A
type	String	No	Definition Instance type. Constraints N/A 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	Definition DB engine. Constraints N/A Range MySQL (case-sensitive) Default Value N/A
offset	Integer	No	Definition Index offset. Constraints N/A 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	Definition Number of records to be queried. Constraints N/A 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	Definition 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	Definition Querying FlexusRDS instances. Constraints N/A Range flexus Default Value N/A

**Table 2** tags field data structure description
Parameter	Type	Mandatory	Description
key	String	Yes	Definition Tag key. Constraints N/A 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	Definition Tag value. Constraints N/A 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	Definition Instance information. For details, see Table 4.
total_count	Integer	Definition Total number of records. Range N/A

**Table 4** instances field data structure description
Parameter	Type	Description
id	String	Definition Instance ID. Range N/A
name	String	Definition Instance name. Range N/A
status	String	Definition Instance status. 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	Definition Instance description. Range N/A
private_ips	List<String>	Definition Private IP addresses. It is a blank string until an instance is created.
private_dns_names	List<String>	Definition 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>	Definition 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>	Definition Public IP addresses.
port	Integer	Definition Database port. Range If this parameter is not specified, the default port number 3306 is used.
enable_ssl	Boolean	Definition Whether SSL is enabled for the instance. Range true: SSL is enabled for the instance. false: SSL is disabled for the instance.
type	String	Definition Instance type. Range The value can be Single or Ha, indicating single-node instances or primary/standby instances, respectively.
ha	Object	Definition HA information. This parameter is returned only for HA instances. For details, see Table 5.
region	String	Definition Region where the instance is deployed. Range N/A
datastore	Object	Definition Database information. For details, see Table 6.
created	String	Definition Creation time. 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	Definition Update time. 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	Definition Default username. Range N/A
vpc_id	String	Definition VPC ID. Range N/A
subnet_id	String	Definition Subnet ID. Range N/A
security_group_id	String	Definition Security group ID. Range N/A
flavor_ref	String	Definition Specification code. Range N/A
cpu	String	Definition Number of vCPUs. For example, the value 1 indicates 1 vCPU. Range N/A
mem	String	Definition Memory size in GB. Range N/A
volume	Object	Definition Instance storage. For details, see Table 7.
switch_strategy	String	Definition Database failover priority. 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	Definition Whether the database is read-only. Range true: The database is read-only. false: The database is not read-only.
read_only_by_user	Boolean	Definition Whether the instance is set to read-only. Range true: The instance is set to read-only. false: The instance is not set to read-only.
backup_strategy	Object	Definition Backup policy. For details, see Table 8.
maintenance_window	String	Definition Maintenance window, in the UTC format. Range N/A
nodes	Array of objects	Definition Primary/standby instance information. For details, see Table 9.
related_instance	Array of objects	Definition All associated DB instances. For details, see Table 10.
disk_encryption_id	String	Definition Disk encryption key ID. Range N/A
enterprise_project_id	String	Definition Enterprise project ID. Range N/A
time_zone	String	Definition Time zone. Range N/A
charge_info	Object	Definition Billing information. For details, see Table 11.
tags	Array of objects	Definition Tag list. If there is no tag added for the instance, an empty array is returned. For details, see Table 12.
order_id	String	Definition Order ID. Range N/A
associated_with_ddm	Boolean	Definition Whether this instance is associated with a DDM instance. Range N/A
expiration_time	String	Definition Instance expiration time. 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	Definition Replication mode for the standby instance. Range async: asynchronous replication semisync: semi-synchronous replication

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

**Table 7** volume field data structure description
Parameter	Type	Description
type	String	Definition Storage type. Range CLOUDSSD (case-sensitive): cloud SSD storage. This storage type is supported only with general-purpose and dedicated instances.
size	Integer	Definition Storage space. 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	Definition Backup time window. Automated backups will be triggered during the backup time window. 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	Definition Retention days for backups. 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	Definition Node ID. Range N/A
name	String	Definition Node name. Range N/A
role	String	Definition Node type. Range master (primary node) or slave (standby node)
status	String	Definition Node status. 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	Definition AZ. Range N/A

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

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

**Table 12** tags field data structure description
Parameter	Type	Description
key	String	Definition Tag key. Range N/A
value	String	Definition Tag 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
}

Abnormal response
For details, see Abnormal Request Results.

Status Code

Normal
200
Abnormal
For details, see Status Codes.

Querying DB Instances