Querying DB Instances_DB Instance Management_API v3 (Recommended)_API Reference

Function

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

Before calling this API, learn how to authenticate it.
Before calling this API, learn about request header parameters.

URI

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

Parameter description

**Table 1** Parameters
Parameter	Type	Mandatory	Description
project_id	String	Yes	Definition Project ID of a tenant in a region. To obtain the value, 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 , it indicates that 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 Single: single-node instance Ha: primary/standby instance Replica: read replica Enterprise: distributed instance (Enterprise Edition) Default Value N/A
datastore_type	String	No	Definition DB engine. Constraints The value is case-sensitive. Range MySQL PostgreSQL Default Value N/A
vpc_id	String	No	Definition VPC ID. To obtain this parameter value, use either of the following methods: Method 1: Log in to the VPC console and view the VPC ID on the VPC details page. Method 2: See the "Querying VPCs" section in the Virtual Private Cloud API Reference. Constraints N/A Range N/A Default Value N/A
subnet_id	String	No	Definition Subnet ID. To obtain this parameter value, use either of the following methods: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page. Method 2: See the "Querying Subnets" section in the Virtual Private Cloud API Reference. Constraints N/A Range N/A Default Value N/A
offset	Integer	No	Definition Index offset. The query starts from the next piece of data indexed by this parameter. Constraints The value must be a non-negative number. Range An integer greater than or equal to 0 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. {key} indicates the tag key. It must be unique and cannot be empty. {value} indicates the tag value, which can be left empty. To query instances with multiple tag keys and values, separate key-value pairs with commas (,). A maximum of 10 key-value pairs are supported. For details, see Table 2. Constraints N/A Range N/A 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 It 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

Request parameters
None

Response

Normal response

**Table 3** Parameters
Parameter	Type	Description
instances	Array of objects	Definition Indicates the DB instance information. For details, see Table 4.
total_count	Integer	Definition Indicates the total number of records. Range N/A

**Table 4** instances field data structure description
Parameter	Type	Description
id	String	Definition Indicates the DB instance ID. Range N/A
name	String	Definition Indicates the created DB instance name. Range N/A
status	String	Definition Indicates the DB instance status. Range BUILD: The instance is being created. CREATE FAIL: The instance failed to be created. ACTIVE: The instance is running properly. FAILED: The instance is abnormal. MODIFYING: The vCPU, memory, or storage space of the instance is being changed. REBOOTING: The instance is being rebooted. RESTORING: The instance is being restored. MODIFYING INSTANCE TYPE: The instance is changing from single to primary/standby. SWITCHOVER: The instance is performing a primary/standby switchover. MIGRATING: The instance is being migrated. BACKING UP: The instance is being backed up. MODIFYING DATABASE PORT: The database port is being changed.
alias	String	Definition Indicates the DB instance alias. Range N/A
private_ips	List<String>	Definition Indicates the private IP address list. It is a blank string until an ECS is created. Range N/A
private_dns_names	List<String>	Definition Indicates the private domain name list of the DB instance. After a DB instance is created, you need to manually apply for a private domain name, or the private domain name is left blank. Range N/A
public_ips	List<String>	Definition Indicates the public IP address list. Range N/A
port	Integer	Definition Indicates the database port number. Range RDS for MySQL instances can use database ports 1024 to 65535, excluding 12017 and 33071, which are reserved for RDS system use. RDS for PostgreSQL instances can use database ports 2100 to 9500. If this parameter is not set, the default value is as follows: RDS for MySQL: 3306 RDS for PostgreSQL: 5432
type	String	Definition Instance type. Range Single: single-node instance Ha: primary/standby instance Replica: read replica Enterprise: distributed instance (Enterprise Edition)
ha	Object	Definition Indicates the primary/standby DB instance information. Returned only when you obtain a primary/standby DB instance list. For details, see Table 5.
region	String	Definition Indicates the region where the DB instance is deployed. Range N/A
datastore	Object	Definition Indicates the database information. For details, see Table 6.
created	String	Definition Indicates the 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 instance is being created. After the instance is created, the value is not empty.
updated	String	Definition Indicates the update time. Range The format is the same as that of the created field. The value is empty when the instance is being created. After the instance is created, the value is not empty.
db_user_name	String	Definition Indicates the default username. Range N/A
vpc_id	String	Definition Indicates the VPC ID. Range N/A
subnet_id	String	Definition Indicates the network ID of the subnet. Range N/A
security_group_id	String	Definition Indicates the security group ID. Range N/A
flavor_ref	String	Definition Indicates the specification code. Range N/A
volume	Object	Definition Indicates instance storage. For details, see Table 7.
switch_strategy	String	Definition Indicates the database failover priority. Range reliability: Reliability is given priority during the failover. availability: Availability is given priority during the failover.
backup_strategy	Object	Definition Indicates the backup policy. For details, see Table 8.
maintenance_window	String	Definition Indicates the start time of the maintenance time window in the UTC format. Range N/A
nodes	Array of objects	Definition Indicates the primary/standby DB instance information. For details, see Table 9.
related_instance	Array of objects	Definition Indicates all associated DB instances. For details, see Table 10.
disk_encryption_id	String	Definition Indicates the disk encryption key ID. Range N/A
time_zone	String	Definition Indicates the time zone. Range N/A
tags	Array of objects	Definition Indicates the tag list. If there is no tag in the list, an empty array is returned. For details, see Table 11.

**Table 5** ha field data structure description
Parameter	Type	Description
replication_mode	String	Definition Indicates the replication mode for the standby instance. Range For RDS for MySQL, the value is async or semisync. For RDS for PostgreSQL, the value is async or sync. NOTE: async indicates the asynchronous replication mode. semisync indicates the semi-synchronous replication mode. sync indicates the synchronous replication mode.

**Table 6** datastore field data structure description
Parameter	Type	Description
type	String	Definition Indicates the DB engine. Its value can be any of the following and is case-insensitive: Range MySQL PostgreSQL
version	String	Definition Indicates the database version. When the DB engine is SQL Server, WEB indicates the web edition, SE indicates the standard edition, and EE indicates the enterprise edition. Range N/A

**Table 7** volume field data structure description
Parameter	Type	Description
type	String	Definition Storage type. The value is case-sensitive.
size	Integer	Definition Storage space in GB. Range N/A

**Table 8** backup_strategy field data structure description
Parameter	Type	Description
start_time	String	Definition Indicates the backup time window. Automated backups will be triggered during the backup time window. The time is in the UTC format. Range N/A
keep_days	Integer	Definition Indicates the number of days to retain the generated backup files. Range 0–732 If the value is 0, the automated backup policy is not configured or has been disabled.

**Table 9** nodes field data structure description
Parameter	Type	Description
id	String	Definition Indicates the node ID. Range N/A
name	String	Definition Indicates the node name. Range N/A
role	String	Definition Indicates the node type. Range master: primary node slave: standby node readreplica: read replica node
status	String	Definition Indicates the node status.
availability_zone	String	Definition Indicates the AZ. Range N/A

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

**Table 11** tags field data structure description
Parameter	Type	Description
key	String	Definition Indicates the tag key. Range N/A
value	String	Definition Indicates the tag value. Range N/A

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": "CLOUDSSD",
		"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.xxx.com"],
	"public_ips": [],
	"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": ""
}], "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": "CLOUDSSD",
			"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.xxx.com"],
		"public_ips": [],
		"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": ""
	}, {
		"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in02",
		"status": "ACTIVE",
		"name": "mysql-0820-022709-02",
		"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": "CLOUDSSD",
			"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.xxx.com"],
		"public_ips": [],
                
		"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": ""
	}],
	"total_count": 2
}

Abnormal response
For details, see Abnormal Request Results.

Status Code

Normal
200
Abnormal
For details, see Status Codes.

Error Code

For details, see Error Codes.

Querying DB Instances

Function

URI

Request

Response

Status Code

Error Code

Feedback

Was this page helpful?