Querying DB Instances_Relational Database Service_API Reference_API v3 (Recommended)

Function

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

Before calling an API, you need to understand the API in Authentication.

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** Parameter description
Name	Type	Mandatory	Description
project_id	String	Yes	Specifies the project ID of a tenant in a region. For details about how to obtain the project ID, see Obtaining a Project ID.
id	String	No	Specifies the DB 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 (*).
name	String	No	Specifies the DB 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 (*).
type	String	No	Specifies the instance type-based query. The value is Single, Ha, Replica, or Enterprise, which corresponds to single instance, primary/standby instance, read replica, and distributed instance (enterprise), respectively.
datastore_type	String	No	Specifies the database type. Its value can be any of the following and is case-sensitive: MySQL PostgreSQL SQLServer
vpc_id	String	No	Specifies the VPC ID. To obtain this parameter value, use either of the following methods: Method 1: Log in to VPC console and view the VPC ID in the VPC details. Method 2: See the "Querying VPCs" section in the Virtual Private Cloud API Reference.
subnet_id	String	No	Specifies the 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.
offset	Integer	No	Specifies the index position. 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.
limit	Integer	No	Specifies the number of records to be queried. The default value is 100. The value cannot be a negative number. The minimum value is 1 and the maximum value is 100.
tags	Array of objects	No	Specifies queries based on the instance tag keys and values. {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.

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

Request

Request parameters
None

URI example
- Querying all DB instances
  GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances
- Querying DB instances based on search criteria
  GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datastore_type=MySQL&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offset=0&limit=10&tags=rds001=001,rds002=002

Response

Normal response

**Table 3** Parameter description
Name	Type	Description
instances	Array of objects	Indicates the DB instance information. For details, see Table 4.
total_count	Integer	Indicates the total number of records.

**Table 4** instances field data structure description
Name	Type	Description
id	String	Indicates the DB instance ID.
name	String	Indicates the created DB instance name.
status	String	Indicates the DB instance status. Valid value: BUILD: The instance is being created. ACTIVE: The instance is normal. FAILED: The instance is abnormal. FROZEN: The instance is frozen. MODIFYING: The instance is being scaled out. 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. STORAGE FULL: The instance storage space is full.
alias	String	Indicates the DB instance alias.
private_ips	List<String>	Indicates the private IP address list. It is a blank string until an ECS is created.
private_dns_names	List<String>	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.
public_dns_names	List<String>	Indicates the public domain name list of the DB instance. Currently, only RDS for SQL Server supports 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>	Indicates the public IP address list.
port	Integer	Indicates the database port number. 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. For RDS for SQL Server 2022 Enterprise Edition, 2022 Standard Edition, 2022 Web Edition, 2019 Enterprise Edition, 2019 Standard Edition, 2019 Web Edition, 2017 Enterprise Edition, 2017 Standard Edition, and 2017 Web Edition, the port number can be set to 1433 or 2100 to 9500 (excluding 5050, 5353, 5355, 5985, and 5986). For other editions, the port number can be set to 1433 or 2100 to 9500 (excluding 5355 and 5985). If this parameter is not set, the default value is as follows: RDS for MySQL: 3306 RDS for PostgreSQL: 5432 RDS for SQL Server: 1433
enable_ssl	Boolean	Indicates whether to enable SSL for the instance. If the value is true, SSL has been enabled for the instance. If the value is false, SSL is disabled for the instance.
type	String	The value is Single, Ha, Replica, or Enterprise, which corresponds to single instance, primary/standby instance, read replica, and distributed instance (enterprise), respectively.
ha	Object	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	Indicates the region where the DB instance is deployed.
datastore	Object	Indicates the database information. For details, see Table 6.
created	String	Indicates the creation time 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	Indicates the update time. The format is the same as that of the created field. 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	Indicates the default username.
vpc_id	String	Indicates the VPC ID.
subnet_id	String	Indicates the network ID of the subnet.
security_group_id	String	Indicates the security group ID.
flavor_ref	String	Indicates the specification code.
cpu	String	Indicates the number of vCPUs. For example, the value 1 indicates 1 vCPU.
mem	String	Indicates the memory size in GB.
volume	Object	Indicates the volume information. For details, see Table 7.
switch_strategy	String	Indicates the database switchover policy. The value can be reliability or availability, indicating the reliability first and availability first, respectively.
read_only_by_user	Boolean	Indicates the read-only status of the DB instance. This parameter is available only to RDS for MySQL. true: indicates that the DB instance is set to read-only. false: indicates that the DB instance is set to read/write.
backup_strategy	Object	Indicates the backup policy. For details, see Table 8.
maintenance_window	String	Indicates the start time of the maintenance time window in the UTC format.
nodes	Array of objects	Indicates the primary/standby DB instance information. For details, see Table 9.
related_instance	Array of objects	Indicates all associated DB instances. For details, see Table 10.
disk_encryption_id	String	Indicates the disk encryption key ID.
enterprise_project_id	String	Indicates the enterprise project ID.
time_zone	String	Indicates the time zone.
charge_info	Object	Indicates the billing information, which is yearly/monthly or pay-per-use. By default, pay-per-use is used. For details, see Table 11.
tags	Array of objects	Indicates the tag list. If there is no tag in the list, an empty array is returned. For details, see Table 13.
backup_used_space	Double	Indicates the backup space usage in GB. This field is returned only when you query information about a specified RDS for SQL Server DB instance.
storage_used_space	Double	Indicates the storage space usage in GB. This field is returned only when you query information about a specified RDS for SQL Server DB instance.
order_id	String	Indicates the order ID. This field is returned only when the DB instance is billed on a yearly/monthly basis.
associated_with_ddm	Boolean	Indicates whether a DDM instance has been associated.
max_iops	Long	Indicates the maximum disk IOPS of the instance. This field is returned only for RDS for SQL Server instances.
expiration_time	String	Indicates the time when an instance expires. The format is yyyy-mm-ddThh:mm:ssZ. This field is returned only for yearly/monthly instances.
serverless_info	Object	Indicates the compute power range of a serverless instance, in RCU. For details, see Table 12.

**Table 5** ha field data structure description
Name	Type	Description
replication_mode	String	Indicates the replication mode for the standby DB instance. The value cannot be empty. For RDS for MySQL, the value is async or semisync. For RDS for PostgreSQL, the value is async or sync. For RDS for SQL Server, the value is 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
Name	Type	Description
type	String	Indicates the DB engine. Its value can be any of the following and is case-insensitive: MySQL PostgreSQL SQLServer
version	String	Indicates the database version.
complete_version	String	Indicates the complete version number. This parameter is returned only when the DB engine is MySQL or PostgreSQL.

**Table 7** volume field data structure description
Name	Type	Description
type	String	Indicates the volume type.
size	Integer	Indicates the volume size.

**Table 8** backup_strategy field data structure description
Name	Type	Description
start_time	String	Indicates the backup time window. Automated backups will be triggered during the backup time window. The time is in the UTC format.
keep_days	Integer	Indicates the number of days to retain the generated backup files. The value ranges from 0 to 732. If the value is 0, the automated backup policy is not configured or has been 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
Name	Type	Description
id	String	Indicates the node ID.
name	String	Indicates the node name.
role	String	Indicates the node type. The value can be master, slave, or readreplica, indicating the primary node, standby node, and read replica node, respectively.
status	String	Indicates the node status.
availability_zone	String	Indicates the AZ.

**Table 10** related_instance field data structure description
Name	Type	Description
id	String	ID of the associated DB instance.
type	String	Type of the associated DB instance. replica_of: indicates a primary DB instance. replica: indicates a read replica.

**Table 11** chargeInfo field data structure description
Name	Mandatory	Type	Description
charge_mode	Yes	String	Indicates the billing mode. Valid value: prePaid: indicates the yearly/monthly billing mode. postPaid: indicates the pay-per-use billing mode.

**Table 12** serverless_info field data structure description
Parameter	Mandatory	Type	Description
min_compute_unit	Yes	String	Minimum compute power of a serverless instance, in RCU. Value range: 0.5 to 8
max_compute_unit	Yes	String	Maximum compute power of a serverless instance, in RCU. Value range: 0.5 to 8

**Table 13** tags field data structure description
Name	Type	Description
key	String	Indicates the tag key.
value	String	Indicates the tag value.

The values of region and availability_zone are used as examples.

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.xxx.com"],
        "public_dns_names": [],
	"public_ips": [],
        "enable_ssl": false,
	"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": "",
        "read_only_by_user": false,
        "charge_info": {
            "charge_mode": "postPaid"
        },
	"backup_strategy": {
		"start_time": "19:00-20:00",
		"keep_days": 7
	},
	"maintenance_window": "02:00-06:00",
	"related_instance": [],
	"disk_encryption_id": "",
	"enterprise_project_id": "0",
	"time_zone": "",
        "tags": [
            {
                "key": "rds001",
                "value": "001"
            },
            {
                "key": "rds002",
                "value": "002"
            }
         ],
	"associated_with_ddm": false
}], "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"],
                "enable_ssl": false,
		"private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"],
                "public_dns_names": [],
		"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": "",
                "read_only_by_user": false,
                "charge_info": {
                    "charge_mode": "postPaid"
                },
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"disk_encryption_id": "",
		"enterprise_project_id": "0",
		"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.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.xxx.com"],
                "public_dns_names": [],
		"public_ips": [],
                "enable_ssl": false,
		"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": "",
                "read_only_by_user": false,
                "charge_info": {
                    "charge_mode": "postPaid"
                },
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"disk_encryption_id": "",
		"enterprise_project_id": "0",
		"time_zone": "",
    		        "tags": [
     	       {
       		         "key": "rds001",
       		         "value": "001"
      		      },
     		       {
      		          "key": "rds002",
      		          "value": "002"
     		       }
   		      ],
		"associated_with_ddm": false
	}],
	"total_count": 2
}

Query serverless DB instances.

{
    "instances": [
        {
            "id": "06f4bde8fec442d7bb122f742c9e51dein01",
            "status": "ACTIVE",
            "name": "rds-4961",
            "port": 3306,
            "type": "Ha",
            "ha": {
                "replication_mode": "semisync"
            },
            "region": "aaa",
            "datastore": {
                "type": "MySQL",
                "version": "5.7"
            },
            "created": "2023-10-24T03:10:28+0000",
            "updated": "2023-10-24T03:10:28+0000",
            "volume": {
                "type": "CLOUDSSD",
                "size": 40
            },
            "nodes": [
                {
                    "id": "0c4844b1323e4f30a7a49b021a047e36no01",
                    "name": "rds-4961_node0",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "62bb9a79e2c34c369845ede701a4cf34no01",
                    "name": "rds-4961_node1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                }
            ],
            "tags": [],
            "bpDomainId": "",
            "bpType": "Default",
            "alias": "",
            "private_ips": [],
            "private_dns_names": [
                "0aabbcc.mysql.rds.myhuaweicloud.com"
            ],
            "public_dns_names": [],
            "public_ips": [],
            "enable_ssl": false,
            "db_user_name": "root",
            "vpc_id": "a70b5818-a306-426d-a53e-11b6b57c31af",
            "subnet_id": "7cac9cc5-7b87-414e-9913-cbbc5051347e",
            "security_group_id": "89f258c5-4b81-4ef0-be30-34f2ee07dd1c",
            "flavor_ref": "rds.mysql.serverless.ha",
            "switch_strategy": "reliability",
            "read_only_by_user": false,
            "charge_info": {
                "charge_mode": "postPaid"
            },
            "backup_strategy": {
                "start_time": "19:00-20:00",
                "keep_days": 7
            },
            "maintenance_window": "18:00-22:00",
            "related_instance": [],
            "disk_encryption_id": "",
            "enterprise_project_id": "0",
            "time_zone": "UTC+08:00",
            "order_id": "",
            "associated_with_ddm": false,
            "serverless_info": {
                "max_compute_unit": "0.5",
                "min_compute_unit": "8"
            }
        }
    ],
    "total_count": 1
}

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?