Querying DB Instances (v3.1)
Function
This API is used to query instances according to search criteria. Before calling this API:
- Learn how to authenticate this API.
- Obtain the required region and endpoint.
URI
GET /v3.1/{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}
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 The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A |
id |
String |
No |
Definition Instance ID, which uniquely identifies an instance and is used to query instances in the instance list. Constraints 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 (*). Range The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A |
name |
String |
No |
Definition Instance name. You can query instances by instance name. Constraints 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 (*). Range The instance name must start with a letter and can contain 4 to 64 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed. Default Value N/A |
type |
String |
No |
Definition Instance type. You can query instances by instance type. Constraints N/A Range
Default Value N/A |
datastore_type |
String |
No |
Definition Database type, which is case insensitive. You can query instances by database type. Constraints None Range GaussDB Default Value N/A |
vpc_id |
String |
No |
Definition VPC ID. You can query instances by VPC where the instances are located. To obtain the value:
Constraints N/A Range UUID format Default Value N/A |
subnet_id |
String |
No |
Definition Network ID of the subnet. You can query DB instances by network ID of the subnet where the DB instances are located. To obtain the value:
Constraints N/A Range UUID format 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 [0,2^31-1] Default Value 0 (indicating that the query starts from the first data record.) |
limit |
Integer |
No |
Definition Number of records to be queried. Constraints N/A Range [1, 100] Default Value 100 |
tags |
String |
No |
Definition
You can query instances by tag key and value. 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. Range
Default Value N/A |
charge_mode |
String |
No |
Definition Billing mode. You can query DB instances by billing mode. Constraints N/A Range
Default Value N/A |
Request Parameters
None
Response Parameters
Parameter |
Type |
Description |
---|---|---|
instances |
Array of objects |
Definition Instance information. For details, see Table 3. |
total_count |
Integer |
Definition Total number of records. Range [0, 2^31 - 1]. The actual value depends on the number of instances in the instance list. |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Explanation: Instance ID, which uniquely identifies an instance. Range The value can contain 32 characters. Only letters and digits are allowed. |
name |
String |
Explanation: Instance name. Range The instance name must start with a letter and can contain 4 to 64 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed. |
status |
String |
Explanation: Instance status. Range
|
private_ips |
List<String> |
Explanation: Private IP address list. The value is an empty string until ECSs where CNs of distributed instances are deployed or ECSs where DNs of centralized instances are deployed are created. Range N/A |
public_ips |
List<String> |
Explanation: EIPs bound to the instance. This parameter cannot be left blank after an EIP is bound. Range N/A |
port |
Integer |
Explanation: Database port number. Range The GaussDB database port is from 1024 to 39998 (excluding the following which are occupied by the system and cannot be used: 2378, 2379, 2380, 4999, 5000, 5999, 6000, 6001, 8097, 8098, 20049, 20050, 21731, and 21732). |
type |
String |
Explanation: Instance type. The value is case-sensitive. Range
|
ha |
Object |
Explanation: Instance high availability. For details, see Table 4. |
replica_num |
Integer |
Explanation: Number of replicas. Range N/A |
region |
String |
Explanation: Region where the instance is deployed. Range N/A |
datastore |
Object |
Explanation: Database information. For details, see Table 5. |
created |
String |
Explanation: Creation time in the "yyyy-mm-dd hh:mm:ss timezone" format. timezone indicates the time zone, for example, 2024-07-02 08:32:07 UTC. When the instance is being created, the value is the time when the creation request is delivered. After the instance is created, the value is the time when the creation is complete. Range N/A |
updated |
String |
Definition Update time. The format is the same as that of the created field. For example: 2024-07-16 09:31:43 UTC The value is empty when no instance has been created. After an instance is created, the value is not empty. Range N/A |
db_user_name |
String |
Definition Default username. Range root |
vpc_id |
String |
Definition ID of the VPC where the instance is located. Range UUID format |
subnet_id |
String |
Definition Network ID of the subnet, where the instance are located. Range UUID format |
security_group_id |
String |
Definition Security group ID. Range UUID format |
flavor_ref |
String |
Definition Specification code. To obtain its value, see the spec_code field in Querying Instance Specifications. Range N/A |
flavor_info |
Object |
Definition Flavor information. For details, see Table 6. |
volume |
Object |
Definition Volume information. 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. If no failover priority is selected during the creation, the failover priority is not displayed. |
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 Instance node information. For details, see Table 9. |
disk_encryption_id |
String |
Definition Disk encryption key ID. This parameter is displayed only when the instance disk is encrypted. Range N/A |
enterprise_project_id |
String |
Definition Enterprise project tag ID. If an instance does not belong to any enterprise project, the default value is 0. Range N/A |
instance_mode |
String |
Definition Product type. Range enterprise indicates enterprise edition, standard indicates the standard edition, and basic indicates the basic edition. . |
time_zone |
String |
Definition Time zone. Range N/A . |
charge_info |
Object |
Definition Billing type, which can be pay-per-use or yearly/monthly. For details, see Table 10. |
tags |
Array of objects |
Definition Tags. This parameter is not returned if there is no tag. For details, see Table 11. |
backup_used_space |
String |
Definition Used backup space, in KB. Range N/A . |
disk_usage |
String |
Definition Available disk usage of the instance. The returned value of this parameter is not a real-time value. The system updates data at 02:00 every day. It is not displayed for deleted instances. Range 0 to 1. The value contains four decimal places. |
Parameter |
Type |
Description |
---|---|---|
consistency |
String |
Definition Transaction consistency type. Range
|
replication_mode |
String |
Definition Replication mode for the standby node. Range The value can only be set to sync, indicating that data is synchronized in synchronous mode. |
Parameter |
Type |
Description |
---|---|---|
type |
String |
Definition Database engine. Range GaussDB |
version |
String |
Definition Major version of the database. Range Two-digit version, for example, 3.208. |
complete_version |
String |
Definition Major version of the database. Range Three-digit version, for example, 3.208.0. |
hotfix_versions |
String |
Definition Hot patch version that has been upgraded. After the hot patch version is successfully upgraded, the value of this parameter cannot be left blank. Range N/A |
target_version |
String |
Definition Target version that the database is being upgraded to. Range N/A |
hotfix_finished_times |
Array of strings |
Definition List of time when the hot patch installation is complete. The time when the hot patch installation is complete is expressed in the "yyyy-mm-dd hh:mm:ss timezone" format. timezone indicates the time zone, for example, 2020-12-23 03:21:41 UTC. |
Parameter |
Type |
Description |
---|---|---|
vcpu |
Integer |
Definition Number of vCPUs. Range N/A |
mem |
Integer |
Definition Memory size in GB. Range N/A |
Parameter |
Type |
Description |
---|---|---|
type |
String |
Definition Disk type. Range ULTRAHIGH (SSD storage) or ESSD (extreme SSD storage). The value is case-sensitive. |
size |
Integer |
Definition Disk size. Range N/A |
Parameter |
Type |
Description |
---|---|---|
start_time |
String |
Definition Backup time window. Automated backups will be created during the backup time window. The value is the UTC time. The format is hh:mm-HH:MM, for example, 19:00-20:00. Range N/A |
keep_days |
Integer |
Definition Number of days to retain the generated backup files. Range [1, 732] |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Definition Node ID. Range The value can contain 36 characters. Only letters and digits are allowed. |
name |
String |
Definition Node name. Range The value must start with a letter. Only letters, digits, hyphens (-), and underscores (_) are allowed. |
role |
String |
Definition Node type, indicating the role of a node in an instance. Range
|
status |
String |
Definition Node status. Range BUILD_FAILED: The node fails to be created. |
availability_zone |
String |
Definition AZ. Range N/A |
private_ip |
String |
Definition Private IP address of the node. For distributed instances, this parameter is valid only for CNs. For centralized instances, this parameter is valid for all nodes. The parameter value is returned after an ECS is created. Range N/A |
public_ip |
String |
Definition EIP that has been bound. For distributed instances, this parameter is valid only for CNs. For centralized instances, this parameter is valid for all nodes. The parameter value is returned after an ECS is created and an EIP is bound to a DB instance. Range N/A |
component_names |
String |
Definition Component information on the node (for example, cn_6001:60011). Separate information of multiple components with commas (,). Range N/A |
Example Request
- Querying all instances
GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/97b026aa9cc4417888c14c84a1ad9860/instances
- Querying instances based on search criteria
GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datastore_type=GaussDB&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offset=0&limit=10&tags=rds001=001,rds002=002
Example Response
{ "instances": [ { "id": "b331ed66cc3249f78bc20737308c01f4in14", "status": "ACTIVE", "name": "gauss-9e88", "port": 8000, "type": "Enterprise", "ha": { "consistency": "strong", "replication_mode": "sync" }, "region": "eu-de", "datastore": { "type": "GaussDB", "version": "2.7", "complete_version": "2.7.2", "hotfix_versions": "2.7.2.1,2.7.2.2", "target_version": "3.208.0", "hotfix_finished_times": [ "2020-12-23 03:21:41 UTC", "2020-12-23 03:22:41 UTC" ] }, "created": "2021-01-15 01:46:40 UTC", "updated": "2021-01-15 02:05:03 UTC", "volume": { "type": "ULTRAHIGH", "size": 120 }, "nodes": [ { "id": "02ebf757aaf94074855f49cc6e0e4712no14", "name": "gauss-9e88_gaussdbv5cn_2", "role": "master", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.16.253", "component_names": "cn_5001:" }, { "id": "0a87b8ecbfeb46aba1409cfc0f0d5c34no14", "name": "gauss-9e88_gaussdbv5cn_0", "role": "master", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.28.81", "component_names": "cn_5002:" }, { "id": "2d9fec1ab3834936b074d63acf48b1f2no14", "name": "gauss-9e88_gaussdbv5dn3_2", "role": "master", "status": "ACTIVE", "availability_zone": "az2xahz" }, { "id": "48bb08a2d635435891ac0caa1c0bf2e3no14", "name": "gauss-9e88_gaussdbv5dn1_0", "role": "master", "status": "ACTIVE", "availability_zone": "az2xahz" }, { "id": "5df830f652204827ada32f8bc28b107eno14", "name": "gauss-9e88_gaussdbv5dn1_1", "role": "slave", "status": "ACTIVE", "component_names": "dn_6002:60011", "availability_zone": "az2xahz" }, { "id": "8a97a246cee841b38c5b47290d4c9c38no14", "name": "gauss-9e88_gaussdbv5cn_1", "role": "master", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.27.52", "component_names": "cn_5003:" }, { "id": "8c1a3f8eecca4d9e9974a868bb6dd942no14", "name": "gauss-9e88_gaussdbv5dn2_0", "role": "master", "status": "ACTIVE", "component_names": "dn_6004:60042", "availability_zone": "az2xahz" }, { "id": "9bd0c80b8a684cc9bd7d99dd5adffb07no14", "name": "gauss-9e88_gaussdbv5dn3_1", "role": "slave", "status": "ACTIVE", "component_names": "dn_6005:60073", "availability_zone": "az2xahz" }, { "id": "9e2a3cd541e249d4af5aa57c5d3a7f39no14", "name": "gauss-9e88_gaussdbv5dn1_2", "role": "slave", "status": "ACTIVE", "component_names": "dn_6006:60011", "availability_zone": "az2xahz" }, { "id": "b046d28989ec4ae5a1a9ab20fe65f248no14", "name": "gauss-9e88_gaussdbv5dn2_2", "role": "slave", "status": "ACTIVE", "component_names": "dn_6007:60042", "availability_zone": "az2xahz" }, { "id": "b614cc12fd3742dbb230245f88a7bf00no14", "name": "gauss-9e88_gaussdbv5dn3_0", "role": "slave", "status": "ACTIVE", "component_names": "dn_6008:60073", "availability_zone": "az2xahz" }, { "id": "caba8e88c3c84ae58202f1f589490611no14", "name": "gauss-9e88_gaussdbv5dn2_1", "role": "slave", "status": "ACTIVE", "component_names": "dn_6009:60042", "availability_zone": "az2xahz" } ], "private_ips": [ "192.168.16.253 / 192.168.28.81 / 192.168.27.52" ], "replica_num": 3, "db_user_name": "root", "vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc", "subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05", "security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163", "flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in", "flavor_info": { "vcpu": 2, "mem": 16 }, "switch_strategy": "Reliability", "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "18:00-22:00", "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab", "enterprise_project_id": "6e76681b-a2f5-4c5f-97c5-ba4fd3c0dfb2", "time_zone": "UTC+08:00", "instance_mode":"enterprise", "disk_usage": "0.9890", "backup_used_space": "37846" }, { "id": "226b4afcfcc84c86bf1b9cb345d3b00fin14", "status": "ACTIVE", "name": "UTS-gauss-ad53-2C3D", "port": 8000, "type": "Enterprise", "ha": { "consistency": "strong", "replication_mode": "sync" }, "region": "cn-xianhz-1", "datastore": { "type": "GaussDB", "version": "2.7", "complete_version": "2.7.2", "hotfix_versions": "2.7.2.1,2.7.2.2", "target_version": "3.208.0", "hotfix_finished_times": [ "2020-12-23 03:21:41 UTC", "2020-12-23 03:22:41 UTC" ] }, "created": "2021-01-08 09:18:27 UTC", "updated": "2021-01-14 13:25:03 UTC", "volume": { "type": "ULTRAHIGH", "size": 120 }, "nodes": [ { "id": "07538a1def584cee99e2a5685eeab36ano14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_1", "role": "slave", "status": "ACTIVE", "availability_zone": "az2xahz" }, { "id": "21f41baba1e2454f82331b7cb5aeabe5no14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_2", "role": "master", "status": "ACTIVE", "component_names": "dn_6008:60042", "availability_zone": "az2xahz" }, { "id": "2909771a3b3e4e3998f9388e77d22391no14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_0", "role": "slave", "status": "ACTIVE", "component_names": "dn_6007:60011", "availability_zone": "az2xahz" }, { "id": "2bd9a90a5da242a6b0743a7f597f6106no14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_2", "role": "master", "status": "ACTIVE", "component_names": "dn_6006:60042", "availability_zone": "az2xahz" }, { "id": "77092f1dadb74d3ea13d28269cdd3590no14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_2", "role": "master", "status": "ACTIVE", "component_names": "dn_6005:60072", "availability_zone": "az2xahz" }, { "id": "a46bfaa6d5a24355a60fce7432b964cano14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_0", "role": "slave", "status": "ACTIVE", "component_names": "dn_6004:60072", "availability_zone": "az2xahz" }, { "id": "aa5277736f3844e2a7adeb9de529e2b1no14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_1", "role": "slave", "status": "ACTIVE", "component_names": "dn_6003:60042", "availability_zone": "az2xahz" }, { "id": "b1d798e4ea7344dfa95032984bc6cfd7no14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_1", "role": "master", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.29.231", "component_names": "cn_5002:" }, { "id": "b9a46540186f4c0781eabaa2a79594cbno14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_1", "role": "slave", "status": "ACTIVE", "component_names": "dn_6002:60011", "availability_zone": "az2xahz" }, { "id": "d283813030364060ab64371d50294977no14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_0", "role": "slave", "status": "ACTIVE", "component_names": "dn_6001:60042", "availability_zone": "az2xahz" }, { "id": "eb7bce29b2284cd290405eaddc1b1a1eno14", "name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_0", "role": "master", "status": "FAILED", "availability_zone": "az2xahz", "private_ip": "192.168.30.44", "component_names": "cn_5001:", "public_ip": "10.154.217.248" } ], "private_ips": [ "192.168.29.231 / 192.168.30.44" ], "public_ips": [ "10.154.217.248" ], "replica_num": 3, "db_user_name": "root", "vpc_id": "5f84a5c4-2f93-41de-8359-d7acedb585cc", "subnet_id": "300036af-a92f-4e9e-8e9f-7d20e7878b05", "security_group_id": "2dcfd40a-8f32-46b8-8a47-6cfab5eba163", "flavor_ref": "gaussdb.opengauss.ee.dn.m6.large.8.in", "flavor_info": { "vcpu": 2, "mem": 16 }, "switch_strategy": "Reliability", "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "18:00-19:00", "keep_days": 7 }, "maintenance_window": "18:00-22:00", "enterprise_project_id": "0", "time_zone": "UTC+08:00", "instance_mode":"enterprise", "disk_usage": "1.0000", "backup_used_space": "55824" }, { "id": "7139e0eee4ac4922927f22e22114a548in14", "status": "ACTIVE", "name": "gauss-readonly", "port": 8000, "type": "centralization_standard", "ha": { "consistency": "strong", "replication_mode": "sync" }, "region": "cn-xianhz-1", "datastore": { "type": "GaussDB", "version": "3.220", "complete_version": "3.220.0", "complete_kernel_version": "503.1.0.SPC1500", "target_version": "3.208.0", "hotfix_finished_times": [ "2020-12-23 03:21:41 UTC", "2020-12-23 03:22:41 UTC" ] }, "created": "2024-06-04 03:41:19 UTC", "updated": "2024-06-18 02:01:17 UTC", "volume": { "type": "ULTRAHIGH", "size": 40 }, "nodes": [ { "id": "7fd28bb9a142491a8b0f57ef3c662a2ano14", "name": "gauss-readonly_readonly_4", "role": "readreplica", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.167.105", "component_names": "dn_6005:60011", "flavor_ref": "gaussdb.opengauss.ee.c3.xlarge.x864.ha", "flavor_info": { "vcpu": "4", "mem": "16" } }, { "id": "c532d75f8ee44b4e8ef8bf291bf8ed98no14", "name": "gauss-readonly_readonly_3", "role": "readreplica", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.184.6", "component_names": "dn_6004:60011", "flavor_ref": "gaussdb.opengauss.ee.c3.xlarge.x864.ha", "flavor_info": { "vcpu": "4", "mem": "16" } }, { "id": "1624226d9281469fa2fc865299b62999no14", "name": "gauss-readonly_root_1", "role": "slave", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.243.237", "component_names": "cm_2:,dn_6002:60011,etcd_7002:" }, { "id": "236b7fb1e28e4caba6cf90e4739ed4d8no14", "name": "gauss-readonly_root_0", "role": "master", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.232.222", "component_names": "cm_1:,dn_6001:60011,etcd_7001:" }, { "id": "bfe9bff81020427a983588f5e00c7832no14", "name": "gauss-readonly_root_2", "role": "slave", "status": "ACTIVE", "availability_zone": "az2xahz", "private_ip": "192.168.135.66", "component_names": "cm_3:,dn_6003:60011,etcd_7003:" } ], "private_ips": [ "192.168.167.105 / 192.168.184.6 / 192.168.243.237 / 192.168.232.222 / 192.168.135.66" ], "replica_num": 3, "db_user_name": "root", "vpc_id": "caacd96c-6643-4106-9fea-8cab88f556c08", "subnet_id": "be02c6ca-b3b9-423e-a472-fd043e19d7b7", "security_group_id": "6b95cf16-0555-4997-96c3-udb19ac24384", "flavor_ref": "gaussdb.opengauss.ee.c3.xlarge.x864.ha", "flavor_info": { "vcpu": 4, "mem": 16 }, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "18:00-19:00", "keep_days": 7 }, "maintenance_window": "18:00-22:00", "enterprise_project_id": "0", "time_zone": "UTC+08:00", "instance_mode": "basic", "backup_used_space": "1595991", "disk_usage": "0.6922" } ], "total_count": 3 }
Status Code
- Normal
- Abnormal
For details, see Status Codes.
Error Codes
For details, see Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot