Querying DB Instances

Function

This API is used to query instances according to search criteria. Before calling this API:

This API will be unavailable on March 31, 2025. You are advised to switch workloads to the new API (Querying DB Instances) before then.

Learn how to authenticate this API.
Obtain the required region and endpoint.

URI

GET https://{Endpoint}/opengauss/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}

**Table 1** Parameter description
Parameter	Type	Mandatory	Description
project_id	String	Yes	Explanation: Project ID of a tenant in a region. For details about how to obtain the project ID, see Obtaining a Project ID. Restrictions: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None
id	String	No	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	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	Instance type to be queried.
datastore_type	String	No	Database type. Its value is case-insensitive. GaussDB
vpc_id	String	No	VPC ID. Method 1: Log in to VPC console and view the VPC ID in the VPC details page. Method 2: See the section "Querying VPCs" in the Virtual Private Cloud API Reference.
subnet_id	String	No	Network ID of the subnet. Method 1: Log in to VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page. Method 2: See section "Querying Subnets" in the Virtual Private Cloud API Reference.
offset	Integer	No	Index offset. If offset is set to N, the resource query starts from the N+1 data entry. The default value is 0, indicating that the query starts from the first data entry. The value cannot be a negative number.
limit	Integer	No	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.

Request Parameters

None

Response Parameters

**Table 2** Response parameters
Parameter	Type	Description
instances	Array of objects	Instance information. For details, see Table 3.
total_count	Integer	Total number of records.

**Table 3** instances field data structure description
Parameter	Type	Description
id	String	Instance ID.
name	String	Instance name.
status	String	Instance status. Value: If the value is BUILD, the instance is being created. If the value is ACTIVE, the instance is normal. If the value is FAILED, the instance is abnormal. If the value is FROZEN, the instance is frozen. If the value is EXPANDING, nodes are being added to the instance. If the value is REBOOTING, the instance is being rebooted. If the value is UPGRADING, the instance is being upgraded. If the value is RESTORING, the instance is being restored. If the value is BACKING UP, the instance is being backed up. If the value is STORAGE FULL, the instance storage is full.
private_ips	List<String>	Private IP address list. It is a blank string unless a CN is created on the ECS.
public_ips	List<String>	Public IP address list. This parameter cannot be left blank after an EIP is bound.
port	Integer	Database port number. 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). The default value is 8000.
type	String	Instance type.
ha	Object	Returned when a distributed instance is obtained. For details, see Table 4.
region	String	Region where the instance is deployed.
datastore	Object	Database information. For details, see Table 5.
created	String	Creation time in the "yyyy-mm-dd hh:mm:ss timezone" format. timezone indicates the time zone. 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.
updated	String	Update time. 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	Default username.
vpc_id	String	VPC ID.
subnet_id	String	Network ID of the subnet.
security_group_id	String	Security group ID.
flavor_ref	String	Specification code. To obtain its value, see the spec_code field in Querying Instance Specifications.
flavor_info	Object	Flavor information. For details, see Table 6.
volume	Object	Volume information. For details, see Table 7.
switch_strategy	String	Database failover priority. The value can be reliability or availability, indicating that the reliability or availability is given priority during the failover, respectively.
backup_strategy	Object	Backup policy. For details, see Table 8.
maintenance_window	String	Maintenance window in the UTC format.
nodes	Array of objects	Instance node information. For details, see Table 9.
related_instance	Array of objects	List of associated instances. This parameter is not suitable for GaussDB.
disk_encryption_id	String	Disk encryption key ID.
enterprise_project_id	String	Enterprise project tag ID. If an instance does not belong to any enterprise project, the default value is 0.
instance_mode	String	basic indicates the basic edition and enterprise indicates the enterprise edition.
time_zone	String	Time zone.
charge_info	Object	Billing information, which is pay-per-use by default. For details, see Table 10.
tags	Array of objects	Tag list. If there is no tag in the list, an empty array is returned.

**Table 4** ha field data structure description
Parameter	Type	Description
consistency	String	Transaction consistency type. The value can be strong or eventual, indicating strong consistency and eventual consistency, respectively.
replication_mode	String	Replication mode for the standby node. The value cannot be empty. sync. NOTE: sync indicates synchronous replication.

**Table 5** datastore field data structure description
Parameter	Type	Description
type	String	DB engine.
version	String	DB engine version.

**Table 6** flavor_info field data structure description
Parameter	Type	Description
vcpu	Integer	Number of vCPUs.
mem	Integer	Memory size.

**Table 7** volume field data structure description
Parameter	Type	Description
type	String	Disk type.
size	Integer	Disk size.

**Table 8** backup_strategy field data structure description
Parameter	Type	Description
start_time	String	Backup time window. The creation of an automated backup will be triggered during the backup time window. The time is in the UTC format.
keep_days	Integer	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.

**Table 9** nodes field data structure description
Name	Type	Description
id	String	Node ID.
name	String	Node name.
role	String	Node type. The value can be master or slave, indicating the primary node and standby node respectively.
status	String	Node status.
availability_zone	String	AZ.

**Table 10** chargeInfo field data structure description
Parameter	Mandatory	Type	Description
charge_mode	Yes	String	Billing mode. Value range: postPaid: pay-per-use billing.

Example Request

Querying all instances

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/opengauss/v3/97b026aa9cc4417888c14c84a1ad9860/instances

Querying instances according to search criteria

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/opengauss/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in14&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

Example Response

Querying the instance list

{
    "instances": [
        {
            "id": "b331ed66cc3249f78bc20737308c01f4in14",
            "status": "ACTIVE",
            "name": "gauss-9e88",
            "port": 8000,
            "type": "enterprise",
            "ha": {
                "consistency": "strong",
                "replication_mode": "sync"
            },
            "region": "aaa",
            "datastore": {
                "type": "GaussDB",
                "version": "1.4"
            },
            "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": "bbb"
                },
                {
                    "id": "0a87b8ecbfeb46aba1409cfc0f0d5c34no14",
                    "name": "gauss-9e88_gaussdbv5cn_0",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "2d9fec1ab3834936b074d63acf48b1f2no14",
                    "name": "gauss-9e88_gaussdbv5dn3_2",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "48bb08a2d635435891ac0caa1c0bf2e3no14",
                    "name": "gauss-9e88_gaussdbv5dn1_0",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "5df830f652204827ada32f8bc28b107eno14",
                    "name": "gauss-9e88_gaussdbv5dn1_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "8a97a246cee841b38c5b47290d4c9c38no14",
                    "name": "gauss-9e88_gaussdbv5cn_1",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "8c1a3f8eecca4d9e9974a868bb6dd942no14",
                    "name": "gauss-9e88_gaussdbv5dn2_0",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "9bd0c80b8a684cc9bd7d99dd5adffb07no14",
                    "name": "gauss-9e88_gaussdbv5dn3_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "9e2a3cd541e249d4af5aa57c5d3a7f39no14",
                    "name": "gauss-9e88_gaussdbv5dn1_2",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "b046d28989ec4ae5a1a9ab20fe65f248no14",
                    "name": "gauss-9e88_gaussdbv5dn2_2",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "b614cc12fd3742dbb230245f88a7bf00no14",
                    "name": "gauss-9e88_gaussdbv5dn3_0",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                },
                {
                    "id": "caba8e88c3c84ae58202f1f589490611no14",
                    "name": "gauss-9e88_gaussdbv5dn2_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "bbb"
                }
            ],
            "tags": [],
            "private_ips": [
                "192.168.28.81 / 192.168.27.52 / 192.168.16.253"
            ],
            "public_ips": [],
            "replice_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": "prePaid"
            },
            "backup_strategy": {
                "start_time": "19:00-20:00",
                "keep_days": 7
            },
            "maintenance_window": "18:00-22:00",
            "related_instance": [],
            "disk_encryption_id": "24ae42b5-4009-4ea2-b66a-0b211e424dab",
            "enterprise_project_id": "6e76681b-a2f5-4c5f-97c5-ba4fd3c0dfb2",
            "time_zone": "UTC+08:00",
            "instance_mode":"enterprise",
            "order_id": "CS2101150917EUW8N"
        },
        {
            "id": "226b4afcfcc84c86bf1b9cb345d3b00fin14",
            "status": "ACTIVE",
            "name": "UTS-gauss-ad53-2C3D",
            "port": 8000,
            "type": "enterprise",
            "ha": {
                "consistency": "strong",
                "replication_mode": "sync"
            },
            "region": "aaa",
            "datastore": {
                "type": "GaussDB",
                "version": "1.4"
            },
            "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",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "2909771a3b3e4e3998f9388e77d22391no14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_0",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "2bd9a90a5da242a6b0743a7f597f6106no14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_2",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "77092f1dadb74d3ea13d28269cdd3590no14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_2",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "a46bfaa6d5a24355a60fce7432b964cano14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn3_0",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "aa5277736f3844e2a7adeb9de529e2b1no14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "b1d798e4ea7344dfa95032984bc6cfd7no14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_1",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "b9a46540186f4c0781eabaa2a79594cbno14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn1_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "d283813030364060ab64371d50294977no14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5dn2_0",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "eb7bce29b2284cd290405eaddc1b1a1eno14",
                    "name": "UTS-gauss-ad53-2C3D_gaussdbv5cn_0",
                    "role": "master",
                    "status": "FAILED",
                    "availability_zone": "az2xahz"
                }
            ],
            "private_ips": [
                "192.168.30.44 / 192.168.29.231"
            ],
            "public_ips": [
                "10.154.217.248"
            ],
            "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": "prePaid"
            },
            "backup_strategy": {
                "start_time": "18:00-19:00",
                "keep_days": 7
            },
            "maintenance_window": "18:00-22:00",
            "related_instance": [],
            "enterprise_project_id": "0",
            "time_zone": "UTC+08:00",
            "instance_mode":"enterprise",
        },
        {
            "id": "706c65c3dd7d497ab16f5b3a113690abin14",
            "status": "ACTIVE",
            "name": "UTS-gauss-7362",
            "port": 8000,
            "type": "enterprise",
            "ha": {
                "replication_mode": "sync"
            },
            "region": "cn-xianhz-1",
            "datastore": {
                "type": "GaussDB",
                "version": "1.2"
            },
            "created": "2020-12-23 03:21:41 UTC",
            "updated": "2021-01-15 02:32:13 UTC",
            "volume": {
                "type": "ULTRAHIGH",
                "size": 80
            },
            "nodes": [
                {
                    "id": "25b7f16ee4084b7884d52f1bdfab4e68no14",
                    "name": "UTS-gauss-7362_gaussdbv5dn1_2",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "ad6f02f31744422fa8ce487e81c9e7afno14",
                    "name": "UTS-gauss-7362_gaussdbv5cn_0",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "b30c56582bf44a548e3bb5b5af6c4773no14",
                    "name": "UTS-gauss-7362_gaussdbv5dn1_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "f79ea0600cba42b2888bd9bd67e52a79no14",
                    "name": "UTS-gauss-7362_gaussdbv5dn1_0",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                }
            ],
            "private_ips": [
                "192.168.26.70"
            ],
            "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": "16:00-17:00",
                "keep_days": 7
            },
            "maintenance_window": "18:00-22:00",
            "related_instance": [],
            "enterprise_project_id": "0",
            "time_zone": "UTC+08:00",
            "instance_mode":"enterprise",
        },
        {
            "id": "4ad42d079a3948d88c28d6236211b21ein14",
            "status": "ACTIVE",
            "name": "UTS-gauss-4336",
            "port": 8000,
            "type": "enterprise",
            "ha": {
                "replication_mode": "sync"
            },
            "region": "cn-xianhz-1",
            "datastore": {
                "type": "GaussDB",
                "version": "1.4"
            },
            "created": "2020-12-03 14:28:53 UTC",
            "updated": "2021-01-14 13:20:10 UTC",
            "volume": {
                "type": "ULTRAHIGH",
                "size": 40
            },
            "nodes": [
                {
                    "id": "254dbda6f03643519ad64b39481bd11cno14",
                    "name": "UTS-gauss-4336_gaussdbv5dn1_2",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az1xahz"
                },
                {
                    "id": "6ad76d4db26443c2a93b280739a31558no14",
                    "name": "UTS-gauss-4336_gaussdbv5dn1_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az1xahz"
                },
                {
                    "id": "9fdebf821bdf444a8689b19c0ff588ceno14",
                    "name": "UTS-gauss-4336_gaussdbv5cn_0",
                    "role": "master",
                    "status": "FAILED",
                    "availability_zone": "az1xahz"
                },
                {
                    "id": "dd64bdbc02a542d88823b1582f772d25no14",
                    "name": "UTS-gauss-4336_gaussdbv5cn_1",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az1xahz"
                },
                {
                    "id": "de3c41461045466faf6c2b96eb709540no14",
                    "name": "UTS-gauss-4336_gaussdbv5dn1_0",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az1xahz"
                }
            ],
            "private_ips": [
                "192.168.30.93 / 192.168.29.232"
            ],
            "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",
            "related_instance": [],
            "enterprise_project_id": "0",
            "time_zone": "UTC+08:00",
            "instance_mode":"enterprise",
        }
    ],
    "total_count": 4
}