4.1 实例管理
4.1.4 查询数据库实例列表
● 异常响应
请参见异常请求结果。
状态码
请参见状态码。
错误码
请参见错误码。
4.1.4 查询数据库实例列表
功能介绍
根据指定条件查询实例列表。
● 调用接口前，您需要了解API 认证鉴权。
● 调用接口前，您需要提前获取到地区和终端节点，即下文中的Endpoint值。
调试
您可以在API Explorer中调试该接口。
URI
● URI格式
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}
● URI样例
– 查询所有实例列表
https://gaussdb-opengauss.cn-north-1.myhuaweicloud.com/
v3/97b026aa9cc4417888c14c84a1ad9860/instances – 根据指定条件查询实例列表
https://gaussdb-opengauss.cn-north-1.myhuaweicloud.com/
v3/97b026aa9cc4417888c14c84a1ad9860/instances?
id=ed7cc6166ec24360a5ed5c5c9c2ed726in14&name=hy&type=Enterprise
&datastore_type=GaussDB(for
openGauss)&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offs et=0&limit=10
● 参数说明
表4-24 参数说明
名称 参数类
型
是否 必选
说明
project_id String 是 租户在某一region下的project ID。
获取方法请参见获取项目ID。
id String 否 实例ID。
“*”为系统保留字符，如果id是以“*”起 始，表示按照*后面的值模糊匹配，否则，按 照id精确匹配查询。不能只传入“*”。
name String 否 实例名称。
“*”为系统保留字符，如果name是以“*”
起始，表示按照*后面的值模糊匹配，否则，
按照name精确匹配查询。不能只传入“*”。
type String 否 按照实例类型查询。目前仅支持取值
“Enterprise”（区分大小写），对应分布式 实例（企业版）。当前支持取值"Ha"（区分 大小写），对应主备式实例。
datastore_
type String 否 数据库类型，区分大小写。
GaussDB(for openGauss)
名称 参数类 型
是否 必选
说明
vpc_id String 否 虚拟私有云ID。
● 方法1：登录虚拟私有云服务的控制台界 面，在虚拟私有云的详情页面查找VPC ID。
● 方法2：通过虚拟私有云服务的API接口查 询，具体操作可参考查询VPC列表。
subnet_id String 否 子网的网络ID信息。
● 方法1：登录虚拟私有云服务的控制台界 面，单击VPC下的子网，进入子网详情页 面，查找网络ID。
● 方法2：通过虚拟私有云服务的API接口查 询，具体操作可参考查询子网列表。
offset Integer 否 索引位置，偏移量。从第一条数据偏移offset 条数据后开始查询，默认为0（偏移0条数 据，表示从第一条数据开始查询），必须为数 字，不能为负数。
limit Integer 否 查询记录数。默认为100，不能为负数，最小 值为1，最大值为100。
tags String 否 根据实例标签键值对进行查询。
● {key}表示标签键，最大长度127个unicode 字符。key不能为空或者空字符串，不能为 空格，使用之前先trim前后半角空格。不 能包含+/?#&=,%特殊字符。
● {value}表示标签值，可以为空。最大长度 255个unicode字符，使用之前先trim 前后 半角空格。不能包含+/?#&=,%特殊字符。
如果value为空，则表示any_value（查询 任意value）。
如果同时使用多个标签键值对进行查询，中间 使用逗号分隔开，最多包含10组。
请求消息
无。
响应消息
● 正常响应要素说明
表4-25 参数说明
名称 参数类型 说明
instances Array of objects 实例信息。
详情请参见表4-26。
total_count Integer 总记录数。
表4-26 instances 字段数据结构说明
名称 参数类型 说明
id String 实例ID。
name String 创建的实例名称。
status String 实例状态。
取值：
值为“BUILD”，表示实例正在创建。
值为“ACTIVE”，表示实例正常。
值为“FAILED”，表示实例异常。
值为“FROZEN”，表示实例冻结。
值为“EXPANDING”，表示实例正在 扩容CN或DN。
值为“REBOOTING”，表示实例正在 重启。
值为“UPGRADING”，表示实例正在 升级。
值为“RESTORING”，表示实例正在恢 复。
值为“BACKING UP”，表示实例正在 进行备份。
值为“REDUCING REPLICATION”，
表示实例正在降副本。
值为“STORAGE FULL”，表示实例磁 盘空间满。
private_ips List<String> 实例内网IP地址列表。分布式CN所在的 弹性云服务器创建成功后该值存在，主 备版DN所在的弹性云服务器创建成功 后该值存在，其他情况下为空字符串。
public_ips List<String> 实例外网IP地址列表。绑定弹性公网IP 后，该值不为空。
名称 参数类型 说明
port Integer 数据库端口号。GaussDB(for openGauss)数据库端口设置范围为 1024~39998（其中
2378,2379,2380,4999,5000,5999,6000, 6001,8097,8098,20049,20050,21731,2 1732被系统占用不可设置）。
当不传该参数时，默认端口如下：
8000。
type String 实例类型，取值为 "Enterprise"，对应 于分布式实例（企业版）。取值为
"Ha"，对应于主备版实例。区分大小 写。
ha Object 实例的高可用参数。
详情请参见表4-27。
replica_num Integer 实例副本数。
region String 实例所在区域。
datastore Object 数据库信息。
详情请参见表4-28。
created String 创建时间，格式为“yyyy-mm-dd hh:mm:ss timezone”。
其中timezone是指时区。
说明：创建时该值为实例下发创建的时 间，创建完成后，该值为创建完成时 间。
updated String 更新时间，格式与“created”字段对应 格式完全相同。
说明：创建时返回值为空，数据库实例 创建成功后该值不为空。
db_user_name String 默认用户名。
vpc_id String 虚拟私有云ID。
subnet_id String 子网的网络ID信息。
security_group_
id String 安全组ID。
flavor_ref String 规格码。参考表7-4中GaussDB(for openGauss)的“规格编码”列内容获 取。
flavor_info Object 规格信息。
详情请参见表4-29
名称 参数类型 说明
volume Object Volume信息。
详情请参见表4-30。
switch_strategy String 数据库切换策略。
取值为“reliability”或
“availability”，分别对应于可靠性优 先和可用性优先。
若创建时没有选择切换策略，则不予显 示。
backup_strateg
y Object 备份策略。
详情请参见表4-31。
maintenance_w
indow String 可维护时间窗，为UTC时间。
nodes Array of objects 实例节点信息。
详情请参见表4-32。
disk_encryption
_id String 磁盘加密密钥ID。只有创建磁盘加密实
例才会显示该参数。
enterprise_proje
ct_id String 企业项目标签ID。非企业项目账号的实
例，企业项目默认0。
instance_mode String standard为标准版，basic为基础版 ， enterprise为企业版。
time_zone String 时区。
charge_info Object 计费类型信息，支持按需和包周期。
详情请参见表4-33。
tags Array of objects 标签列表，没有标签不返回该参数。
详情请参见表4-34。
表4-27 ha 字段数据结构说明
名称 参数类型 说明
consistency String 事务一致性类型。取值为“strong”、
“eventual”，分别表示强一致性、最终 一致性。
replication_mo
de String 备机同步参数。
取值：非空。
GaussDB(for openGauss)为 “sync”
说明“sync”为同步模式。
表4-28 datastore 字段数据结构说明
名称 参数类型 说明
type String 数据库引擎。
version String 数据库版本。
表4-29 flavor_info 字段数据结构说明
名称 参数类型 说明
vcpu Integer cpu核数。
mem Integer 内存大小，单位GB。
表4-30 volume 字段数据结构说明
名称 参数类型 说明
type String 磁盘类型。
size Integer 磁盘大小。
表4-31 backup_strategy 字段数据结构说明
名称 参数类型 说明
start_time String 备份时间段。自动备份将在该时间段内触 发。
当前时间指UTC时间。
keep_days Integer 已生成的备份文件可以保存的天数。
取值范围：1～732。
表4-32 nodes 字段数据结构说明
名称 参数类型 说明
id String 节点ID。
name String 节点名称。
role String 节点类型，取值为“master”、
“slave”，分别对应于主节点、备节点。
status String 节点状态。
名称 参数类型 说明 availability_zon
e String 可用区。
表4-33 chargeInfo 字段数据结构说明
名称 是否
必选
参数类 型
说明
charge_mode 是 String 计费模式。
postPaid：后付费，即按需付费。
prePaid：预付费，即包年/包月。
表4-34 tags 字段数据结构说明
名称 参数类型 说明
key String 标签键。
value String 标签值。
● 正常响应样例 实例列表：
{ "instances": [ {
"id": "b331ed66cc3249f78bc20737308c01f4in14", "status": "ACTIVE",
"name": "gauss-9e88", "port": 8000,
"type": "enterprise", "ha": {
"consistency": "strong", "replication_mode": "sync"
},
"region": "cn-xianhz-1", "datastore": {
"type": "GaussDB(for openGauss)", "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"
"status": "ACTIVE",
"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": {
"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",
"created": "2021-01-08 09:18:27 UTC",
},
"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": {
"id": "706c65c3dd7d497ab16f5b3a113690abin14", "status": "ACTIVE",
"datastore": {
"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": {
"maintenance_window": "18:00-22:00",
"id": "4ad42d079a3948d88c28d6236211b21ein14", "status": "ACTIVE",
"private_ips": [
"192.168.30.93 / 192.168.29.232"
],
"public_ips": [],
"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": {
"id": "706c65c3dd7d497ab16f5b3a113690abin14", "status": "ACTIVE",
{
"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": {
错误码
请参见错误码。