Querying DB Instances_DB Instance Management_Historical APIs_API Reference

Function

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

Learn how to authenticate this API.

URI

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

**Table 1** Parameter description
Parameter	Type	Mandatory	Description
project_id	String	Yes	Explanation: Project ID of a tenant in a region. To obtain the value, 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	Explanation: Instance ID, which uniquely identifies an instance and is used to query instances in the instance list. Restrictions: 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 (). Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None
name	String	No	Explanation: Instance name. You can query instances by instance name. Restrictions: 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 (). Value 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: None
type	String	No	Explanation: Instance type. You can query instances by instance type. Restrictions: None Values: Enterprise (case-sensitive): distributed instances (in the independent deployment). Centralization_standard (case-sensitive): centralized instances. Default value: None
datastore_type	String	No	Explanation: Database type, which is case insensitive. You can query instances by database type. Restrictions: None Value: GaussDB Default value: None
vpc_id	String	No	Explanation: VPC ID. You can query instances by VPC where the instances are located. To obtain the value: Method 1: Log in to the 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. Restrictions: None Value: UUID format Default value: None
subnet_id	String	No	Explanation: 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: 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 section "Querying Subnets" in the Virtual Private Cloud API Reference. Restrictions: None Value range: UUID format Default value: None
offset	Integer	No	Explanation: Index offset. The query starts from the next piece of data indexed by this parameter. Restrictions: The value must be a non-negative number. Value range: [0, 2^31-1] Default value: 0 (indicating that the query starts from the first data record.)
limit	Integer	No	Explanation: Number of records to be queried. Restrictions: None Value range: [1, 100] Default value: 100
charge_mode	String	No	Explanation: Billing mode. You can query DB instances by billing mode. Restrictions: None Values: postPaid: pay-per-use billing. Default value: None

Request Parameters

None

Response Parameters

**Table 2** Parameter description
Parameter	Type	Description
instances	Array of objects	Explanation: Instance information. For details, see Table 3.
total_count	Integer	Explanation: Total number of records. Value range: [0, 2^31 - 1]. The actual value depends on the number of instances in the instance list.

**Table 3** instances field data structure description
Parameter	Type	Description
id	String	Explanation: Instance ID, which is the unique identifier of an instance. Value range: The value can contain 32 characters. Only letters and digits are allowed.
name	String	Explanation: Instance name. Value 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. Values: If the value is BUILD, the instance is being created. If the value is BUILD_FAILED, the instance creation failed. If the value is ACTIVE, the instance is normal. If the value is FAILED, the instance is abnormal. If the value is MODIFYING, the storage is being scaled up or instance specifications are being changed. REBOOTING: The DB 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 SWITCHOVER, the primary/standby switchover is being performed. If the value is MIGRATING, the instance is being migrated. If the value is BACKING UP, the instance is being backed up. If the value is UPGRADE TO BE OBSERVED, the instance upgrade is in the observation period. If the value is STORAGE FULL, the instance storage is full. If the value is REPAIRING, the instance is being repaired. If the value is SHUTDOWN, the instance is stopped.
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. Value range: None
port	Integer	Explanation: Database port number. Value range: The GaussDB database port .
type	String	Explanation: Instance type. The value is case-sensitive. Values:
ha	Object	Explanation: Instance high availability. For details, see Table 4.
replica_num	Integer	Explanation: Number of replicas. Value range: None
region	String	Explanation: Region where the instance is deployed. Value range: None
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. Value range: None
updated	String	Explanation: 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. Value range: None
db_user_name	String	Explanation: Default username. Value range: root
vpc_id	String	Explanation: ID of the VPC where the instance is located. Value: UUID format
subnet_id	String	Explanation: Network ID of the subnet, where the instance are located. Value: UUID format
security_group_id	String	Explanation: Security group ID. Value: UUID format
flavor_ref	String	Explanation: Specification code. To obtain its value, see the spec_code field in Querying Instance Specifications. Value range: None
flavor_info	Object	Explanation: Flavor information. For details, see Table 6.
volume	Object	Explanation: Volume information. For details, see Table 7.
backup_strategy	Object	Explanation: Backup policy. For details, see Table 8.
maintenance_window	String	Explanation: Maintenance window in the UTC format. Value range: None
nodes	Array of objects	Explanation: Instance node information. For details, see Table 9.
instance_mode	String	Explanation: Product type. Values: enterprise indicates enterprise edition. .
time_zone	String	Explanation: Time zone. Value range: None .

**Table 4** ha field data structure description
Parameter	Type	Description
consistency	String	Explanation: Transaction consistency type. Values: strong: strong consistency eventual: eventual consistency
replication_mode	String	Explanation: Replication mode for the standby node. Value: The value can only be set to sync, indicating that data is synchronized in synchronous mode.

**Table 5** datastore field data structure description
Parameter	Type	Description
type	String	Explanation: DB engine. Value: GaussDB
version	String	Explanation: Major version of the database. Value: Two-digit version, for example, 3.208.
complete_version	String	Explanation: Major version of the database. Value: Three-digit version, for example, 3.208.0.
hotfix_versions	String	Explanation: Hot patch version that has been upgraded. After the hot patch version is successfully upgraded, the value of this parameter cannot be left blank. Value range: None
target_version	String	Explanation: Target version that the database is being upgraded to. Value range: None
hotfix_finished_times	Array of strings	Explanation: 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.

**Table 6** flavor_info field data structure description
Parameter	Type	Description
vcpu	Integer	Explanation: Number of vCPUs. Value range: None
mem	Integer	Explanation: Memory size in GB. Value range: None

**Table 7** volume field data structure description
Parameter	Type	Description
type	String	Explanation: Disk type. Values:
size	Integer	Explanation: Disk size. Value range: None

**Table 8** backup_strategy field data structure description
Parameter	Type	Description
start_time	String	Explanation: Backup time window. The creation of an automated backup will be triggered during the backup time window. The value is the UTC time. The format is hh:mm-HH:MM, for example, 19:00-20:00. Value range: None
keep_days	Integer	Explanation: Number of days to retain the generated backup files. Value range: [1, 732]

**Table 9** nodes field data structure description
Parameter	Type	Description
id	String	Explanation: Node ID. Value range: The value can contain 36 characters. Only letters and digits are allowed.
name	String	Explanation: Node name. Value range: The value must start with a letter. Only letters, digits, hyphens (-), and underscores (_) are allowed.
role	String	Explanation: Node type, indicating the role of a node in an instance. Values: master: primary node slave: standby node secondary: log node readreplica: read replica.
status	String	Explanation: Node status.
availability_zone	String	Explanation: AZ. Value range: None

Example Request

Querying all instances

GET https://gaussdb-opengauss.eu-west-101.myhuaweicloud.eu/v3.1/97b026aa9cc4417888c14c84a1ad9860/instances

Querying instances based on search criteria

GET https://gaussdb-opengauss.eu-west-101.myhuaweicloud.eu/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

Example Response

Instance information queried.

{
    "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"
            },
            "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",
                },
                {
                    "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",
                    "availability_zone": "az2xahz"
                    
                    
                },
                {
                    "id": "8a97a246cee841b38c5b47290d4c9c38no14",
                    "name": "gauss-9e88_gaussdbv5cn_1",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz",
                    "private_ip": "192.168.27.52",
                },
                {
                    "id": "8c1a3f8eecca4d9e9974a868bb6dd942no14",
                    "name": "gauss-9e88_gaussdbv5dn2_0",
                    "role": "master",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "9bd0c80b8a684cc9bd7d99dd5adffb07no14",
                    "name": "gauss-9e88_gaussdbv5dn3_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "9e2a3cd541e249d4af5aa57c5d3a7f39no14",
                    "name": "gauss-9e88_gaussdbv5dn1_2",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "b046d28989ec4ae5a1a9ab20fe65f248no14",
                    "name": "gauss-9e88_gaussdbv5dn2_2",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "b614cc12fd3742dbb230245f88a7bf00no14",
                    "name": "gauss-9e88_gaussdbv5dn3_0",
                    "role": "slave",
                    "status": "ACTIVE",
                    "availability_zone": "az2xahz"
                },
                {
                    "id": "caba8e88c3c84ae58202f1f589490611no14",
                    "name": "gauss-9e88_gaussdbv5dn2_1",
                    "role": "slave",
                    "status": "ACTIVE",
                    "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",
            "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"
        },
        {
            "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"
            },
            "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",
                    "private_ip": "192.168.29.231"
                },
                {
                    "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_ip": "192.168.30.44",
                    "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",
            "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"
        }
    ],
    "total_count": 3
}

Querying instance details

{
    "instances": [
        {
            "id": "706c65c3dd7d497ab16f5b3a113690abin14",
            "status": "ACTIVE",
            "name": "UTS-gauss-7362",
            "port": 8000,
            "type": "Enterprise",
            "ha": {
                "consistency": "strong",
                "replication_mode": "sync"
            },
	    "region": "aaa",
            "datastore": {
                "type": "GaussDB",
                "version": "1.4"
            },
            "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"
                },
                {
                    "id": "ad6f02f31744422fa8ce487e81c9e7afno14",
                    "name": "UTS-gauss-7362_gaussdbv5cn_0",
                    "role": "master",
                    "status": "ACTIVE",

                },
                {
                    "id": "b30c56582bf44a548e3bb5b5af6c4773no14",
                    "name": "UTS-gauss-7362_gaussdbv5dn1_1",
                    "role": "slave",
                    "status": "ACTIVE"
                },
                {
                    "id": "f79ea0600cba42b2888bd9bd67e52a79no14",
                    "name": "UTS-gauss-7362_gaussdbv5dn1_0",
                    "role": "slave",
                    "status": "ACTIVE"
                }
            ],
            "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.2xlarge.8.in",
            "flavor_info": {
                "vcpu": 8,
                "mem": 64
            },
            "charge_info": {
                "charge_mode": "postPaid"
            },
            "backup_strategy": {
                "start_time": "16:00-17:00",
                "keep_days": 7
            },
            "maintenance_window": "18:00-22:00",
            "enterprise_project_id": "0",
            "time_zone": "UTC+08:00",
            "instance_mode":"enterprise"
        }
    ],
    "total_count": 1
}

Status Code

Normal
200
Abnormal
For details, see Status Codes.

Error Codes

For details, see Error Codes.

Querying DB Instances