Reviewed-by: Boka, Ladislav <ladislav.boka@t-systems.com> Co-authored-by: Ru, Li Yi <liyiru7@huawei.com> Co-committed-by: Ru, Li Yi <liyiru7@huawei.com>
83 KiB
Querying DB Instances
Function
This API is used to query instances according to search criteria. Before calling this API:
- Learn how to authenticate this API.
- Understand the API in Using APIs.
- Obtain the required region and endpoint.
URI
- URI format
GET https://{Endpoint}/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}
- Example
- Querying all instances
https://gaussdb.eu-de.otc.t-systems.com/v3/97b026aa9cc4417888c14c84a1ad9860/instances
- Querying instances based on search criteria
https://gaussdb.eu-de.otc.t-systems.com/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Enterprise&datastore_type=GaussDB&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offset=0&limit=10
- Querying all instances
- Parameter description
Table 1 Parameter description Name
Type
Mandatory
Description
project_id
String
Yes
Project ID of a tenant in a region.
To obtain this value, see Obtaining a Project ID.
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. Currently, the following values are supported:
- Enterprise (case-sensitive): distributed instances (in the independent deployment).
datastore_type
String
No
Database type. Its value is case-insensitive.
GaussDB
vpc_id
String
No
VPC ID. To obtain this parameter value, use the following methods:
- Method 1: Log in to VPC console and view the VPC ID in the VPC details.
- 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" under "APIs" or section "Querying Networks" under "OpenStack Neutron APIs" 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 piece of data. The default value is 0, indicating that the query starts from the first piece of data. 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
None
Response
- Normal response
Table 2 Parameter description Name
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 Name
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 MODIFYING, the storage is being scaled up or instance specifications are being changed.
If the value is EXPANDING, CNs or DNs 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 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.
private_ips
List<String>
Private IP address list. The value is an empty string until ECSs where CNs of distributed instances are deployed or ECSs where DNs of primary/standby instances are deployed are created.
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).
type
String
Instance type. The value is case-sensitive. The value Enterprise indicates the distributed instance (Enterprise Edition).
ha
Object
Instance high availability.
For details, see Table 4.
replica_num
Integer
Number of replicas.
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. For details on how to obtain the GaussDB specification code, see DB Instance Specifications.
flavor_info
Object
Flavor information.
For details, see Table 6.
volume
Object
Volume information.
For details, see Table 7.
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.
disk_encryption_id
String
Disk encryption key ID. This parameter is displayed only when the instance disk is encrypted.
instance_mode
String
enterprise indicates enterprise edition.
time_zone
String
Time zone.
backup_used_space
String
Used backup space, in KB.
Table 4 ha field data structure description Name
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.
The value is sync.
NOTE:sync indicates synchronous replication.
Table 5 datastore field data structure description Name
Type
Description
type
String
DB engine.
version
String
DB engine version.
Table 6 flavor_info field data structure description Name
Type
Description
vcpu
Integer
Number of vCPUs.
mem
Integer
Memory size in GB.
Table 7 volume field data structure description Name
Type
Description
type
String
Disk type.
size
Integer
Disk size.
Table 8 backup_strategy field data structure description Name
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.
Value range: 1-732.
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.
Value:
- ACTIVE: The node is normal.
- BUILD: The node is being created.
- FAILED: The node is abnormal or fails to be created.
- DELETED: The node has been deleted.
availability_zone
String
AZ.
private_ip
String
Private IP address of the node. For distributed instances, this parameter is valid only for CNs. For primary/standby instances, this parameter is valid for all nodes. The parameter value is returned after an ECS is created.
- Example normal responseQuerying an instance list
{ "instances": [ { "id": "b331ed66cc3249f78bc20737308c01f4in14", "status": "ACTIVE", "name": "gauss-9e88", "port": 8000, "type": "Enterprise", "ha": { "consistency": "strong", "replication_mode": "sync" }, "region": "eu-de", "region": "aaa", "datastore": { "type": "GaussDB", "version": "1.3" }, "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" }, { "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", "charge_info": { "charge_mode": "prePaid" }, "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", "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": "1.3" }, "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 }, "charge_info": { "charge_mode": "prePaid" }, "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", "backup_used_space": "37846" }, { "id": "706c65c3dd7d497ab16f5b3a113690abin14", "status": "ACTIVE", "name": "UTS-gauss-7362", "port": 8000, "type": "Enterprise", "ha": { "consistency": "strong", "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", "private_ip": "192.168.26.70" }, { "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 }, "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", "backup_used_space": "37846" }, { "id": "4ad42d079a3948d88c28d6236211b21ein14", "status": "ACTIVE", "name": "UTS-gauss-4336", "port": 8000, "type": "Enterprise", "ha": { "consistency": "strong", "replication_mode": "sync" }, "region": "cn-xianhz-1", "datastore": { "type": "GaussDB", "version": "1.2" }, "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", "private_ip": "192.168.30.93" }, { "id": "dd64bdbc02a542d88823b1582f772d25no14", "name": "UTS-gauss-4336_gaussdbv5cn_1", "role": "master", "status": "ACTIVE", "availability_zone": "az1xahz", "private_ip": "192.168.29.232" }, { "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 }, "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", "backup_used_space": "37846" } ], "total_count": 4 }
- Querying instance details
{ "instances": [ { "id": "706c65c3dd7d497ab16f5b3a113690abin14", "status": "ACTIVE", "name": "UTS-gauss-7362", "port": 8000, "type": "Enterprise", "ha": { "consistency": "strong", "replication_mode": "sync" }, "region": "eu-de", "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", "availability_zone": "eu-de-01", }, { "id": "ad6f02f31744422fa8ce487e81c9e7afno14", "name": "UTS-gauss-7362_gaussdbv5cn_0", "role": "master", "status": "ACTIVE", "availability_zone": "eu-de-01", "private_ip": "192.168.26.70" }, { "id": "b30c56582bf44a548e3bb5b5af6c4773no14", "name": "UTS-gauss-7362_gaussdbv5dn1_1", "role": "slave", "status": "ACTIVE", "availability_zone": "eu-de-01", }, { "id": "f79ea0600cba42b2888bd9bd67e52a79no14", "name": "UTS-gauss-7362_gaussdbv5dn1_0", "role": "slave", "status": "ACTIVE", "availability_zone": "eu-de-01", } ], "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.m4.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", "backup_used_space": "37846" } ], "total_count": 1 }
- Abnormal response
For details, see Abnormal Request Results.
Status Code
- Normal
- Abnormal
For details, see Status Codes.
Error Code
For details, see Error Codes.