查询数据库实例列表
调试
您可以在API Explorer中调试该接口。
URI
- URI格式
GET /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}&tags={key}={value}
- 参数说明
表1 参数说明 名称
参数类型
是否必选
说明
project_id
String
是
参数解释：
租户在某一Region下的项目ID。
获取方法请参见获取项目ID。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
id
String
否
参数解释：
实例ID。
“*”为系统保留字符，如果id是以“*”起始，表示按照*后面的值模糊匹配，否则，按照id精确匹配查询。不能只传入“*”。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
name
String
否
参数解释：
实例名称。
“*”为系统保留字符，如果name是以“*”起始，表示按照*后面的值模糊匹配，否则，按照name精确匹配查询。不能只传入“*”。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
type
String
否
参数解释：
实例类型。
约束限制：
不涉及。
取值范围：
- Single：单机实例
- Ha：主备实例
- Replica：只读实例
- Enterprise：分布式实例（企业版）
默认取值：
不涉及。
datastore_type
String
否
参数解释：
数据库类型。
约束限制：
区分大小写。
取值范围：
- MySQL
- PostgreSQL
- SQLServer
默认取值：
不涉及。
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。
默认取值：
100
tags
Array of objects
否
参数解释：
根据实例标签键值对进行查询。
- {key}表示标签键，不可以为空或重复。
- {value}表示标签值，可以为空。
如果同时使用多个标签键值对进行查询，中间使用逗号分隔开，最多包含10组。
详情请参见表2。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
请求消息
- URI样例
- 查询所有实例列表
GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances
- 根据指定条件查询实例列表
GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&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
- 查询所有实例列表
响应消息
- 正常响应要素说明
表3 参数说明 名称
参数类型
说明
instances
Array of objects
参数解释：
实例信息。
详情请参见表4。
total_count
Integer
参数解释：
总记录数。
取值范围：
不涉及。
表4 instances字段数据结构说明 名称
参数类型
说明
id
String
参数解释：
实例ID。
取值范围：
不涉及。
name
String
参数解释：
创建的实例名称。
取值范围：
不涉及。
status
String
参数解释：
实例状态。
取值范围：
- BUILD：表示实例正在创建。
- CREATE FAIL：表示创建失败。
- ACTIVE：表示实例正常。
- FAILED：表示实例异常。
- FROZEN：表示实例冻结。
- MODIFYING：表示实例正在扩容。
- REBOOTING：表示实例正在重启。
- RESTORING：表示实例正在恢复。
- MODIFYING INSTANCE TYPE：表示实例正在转主备。
- SWITCHOVER：表示实例正在主备切换。
- MIGRATING：表示实例正在迁移。
- BACKING UP：表示实例正在进行备份。
- MODIFYING DATABASE PORT：表示实例正在修改数据库端口。
- STORAGE FULL：表示实例磁盘空间满。
alias
String
参数解释：
实例的备注信息。
取值范围：
不涉及。
private_ips
List<String>
参数解释：
实例内网IP地址列表。弹性云服务器创建成功后该值存在，其他情况下为空字符串。
取值范围：
不涉及。
private_dns_names
List<String>
参数解释：
实例内网域名列表。实例创建成功后，需要手动申请内网域名，否则查询内网域名为空。
取值范围：
不涉及。
public_dns_names
List<String>
参数解释：
实例公网域名列表，目前仅RDS for SQL Server支持公网域名。实例创建成功后，需要手动申请公网域名，否则查询公网域名为空。
取值范围：
不涉及。
public_ips
List<String>
参数解释：
实例外网IP地址列表。
取值范围：
不涉及。
port
Integer
参数解释：
数据库端口号。
取值范围：
- RDS for MySQL数据库端口设置范围为1024～65535（其中12017和33071被RDS系统占用不可设置）。
- RDS for PostgreSQL数据库端口修改范围为2100～9500。
- 对于RDS for SQL Server 2022 EE、2022 SE、2022 Web版、2019 EE、2019 SE、2019 Web版、2017 EE、2017 SE、2017 Web版：端口设置范围为1433和2100~9500（其中5050、5353、5355、5985和5986不可设置）。
当不传该参数时，默认端口如下：
- RDS for MySQL默认3306。
- RDS for PostgreSQL默认5432。
- RDS for SQL Server默认1433。
enable_ssl
Boolean
参数解释：
实例开启SSL标志。
取值范围：
- true：表示实例已开启SSL。
- false：表示实例未开启SSL。
type
String
参数解释：
实例类型。
取值范围：
- Single：单机实例
- Ha：主备实例
- Replica：只读实例
- Enterprise：分布式实例（企业版）
ha
Object
参数解释：
HA信息，获取HA实例时返回。
详情请参见表5。
region
String
参数解释：
实例所在区域。
取值范围：
不涉及。
datastore
Object
参数解释：
数据库信息。
详情请参见表6。
created
String
参数解释：
创建时间。
取值范围：
格式为“yyyy-mm-ddThh:mm:ssZ”。
其中，T指某个时间的开始；Z指时区偏移量，例如偏移1个小时显示为+0100。
创建时返回值为空，数据库实例创建成功后该值不为空。
updated
String
参数解释：
更新时间。
取值范围：
格式与“created”字段对应格式完全相同。
创建时返回值为空，数据库实例创建成功后该值不为空。
db_user_name
String
参数解释：
默认用户名。
取值范围：
不涉及。
vpc_id
String
参数解释：
虚拟私有云ID。
取值范围：
不涉及。
subnet_id
String
参数解释：
子网的网络ID信息。
取值范围：
不涉及。
security_group_id
String
参数解释：
安全组ID。
取值范围：
不涉及。
flavor_ref
String
参数解释：
规格码。
取值范围：
不涉及。
cpu
String
参数解释：
CPU大小。例如，1表示1U。
取值范围：
不涉及。
mem
String
参数解释：
内存大小（单位：GB）。
取值范围：
不涉及。
volume
Object
参数解释：
实例存储信息。
详情请参见表7。
switch_strategy
String
参数解释：
数据库切换策略。
取值范围：
- reliability：可靠性优先。
- availability：可用性优先。
read_only_by_user
Boolean
参数解释：
用户设置的实例只读状态。仅支持RDS for MySQL引擎。
取值范围：
- true：表示该实例被设置为只读状态。
- false：表示该实例未被设置为只读状态。
backup_strategy
Object
参数解释：
备份策略。
详情请参见表8。
maintenance_window
String
参数解释：
可维护时间窗，为UTC时间。
取值范围：
不涉及。
nodes
Array of objects
参数解释：
主备实例信息。
详情请参见表9。
related_instance
Array of objects
参数解释：
所关联的数据库实例列表。
详情请参见表10。
disk_encryption_id
String
参数解释：
磁盘加密密钥ID。
取值范围：
不涉及。
enterprise_project_id
String
参数解释：
企业项目标签ID。
取值范围：
不涉及。
time_zone
String
参数解释：
时区。
取值范围：
不涉及。
charge_info
Object
参数解释：
计费类型信息，支持包年包月和按需，默认为按需。
详情请参见表11。
tags
Array of objects
参数解释：
标签列表，没有标签默认为空数组。
详情请参见表13。
backup_used_space
Double
参数解释：
备份空间使用量，单位GB。
该字段仅用于查询指定RDS for PostgreSQL和RDS for SQL Server单个实例信息时返回。
取值范围：
不涉及。
storage_used_space
Double
参数解释：
磁盘空间使用量，单位GB。
该字段仅用于查询指定RDS for PostgreSQL和RDS for SQL Server单个实例信息时返回。
取值范围：
不涉及。
order_id
String
参数解释：
订单ID，仅包周期场景返回。
取值范围：
不涉及。
associated_with_ddm
Boolean
参数解释：
是否已被DDM实例关联。
取值范围：
不涉及。
max_iops
Long
参数解释：
实例磁盘的最大IOPS值。
当前该字段仅对于SQL Server引擎实例返回。
取值范围：
不涉及。
expiration_time
String
参数解释：
实例的到期时间，格式为“yyyy-mm-ddThh:mm:ssZ”。
仅包周期场景返回。
取值范围：
不涉及。
serverless_info
Object
参数解释：
Serverless型实例的算力区间，单位RCU。
详情请参见表12。
表5 ha字段数据结构说明 名称
参数类型
说明
replication_mode
String
参数解释：
备机同步参数。
取值范围：
- RDS for MySQL为“async”或“semisync”。
- RDS for PostgreSQL为“async”或“sync”。
- RDS for Microsoft SQL Server为“sync”。
说明：- “async”为异步模式。
- “semisync”为半同步模式。
- “sync”为同步模式。
表6 datastore字段数据结构说明 名称
参数类型
说明
type
String
参数解释：
数据库引擎，不区分大小写。
取值范围：
- MySQL
- PostgreSQL
- SQLServer
version
String
参数解释：
数据库版本。
取值范围：
不涉及。
complete_version
String
参数解释：
数据库完整版本号。仅在数据库引擎是“MySQL”和“PostgreSQL”时返回。
取值范围：
不涉及。
表7 volume字段数据结构说明 名称
参数类型
说明
type
String
参数解释：
磁盘类型。区分大小写。
取值范围：- COMMON，表示SATA。
- HIGH，表示SAS。
- ULTRAHIGH，表示超高IO型磁盘。
- ULTRAHIGHPRO，表示SSD尊享版，仅支持超高性能型尊享版。
- CLOUDSSD，表示SSD云盘，仅支持通用型和独享型规格实例。
- LOCALSSD，表示本地SSD盘。
- ESSD，表示极速型SSD，仅支持独享型规格实例。
size
Integer
参数解释：
磁盘大小，单位为GB。
取值范围：
不涉及。
表8 backup_strategy字段数据结构说明 名称
参数类型
说明
start_time
String
参数解释：
备份时间段。自动备份将在该时间段内触发。
当前时间指UTC时间。
取值范围：
不涉及。
keep_days
Integer
参数解释：
已生成的备份文件可以保存的天数。
取值范围：
0～732。为0时，表示未设置自动备份策略或备份策略已关闭。如果需要延长保留时间请联系客服人员申请，自动备份最长可以保留2562天。
表9 nodes字段数据结构说明 名称
参数类型
说明
id
String
参数解释：
节点ID。
取值范围：
不涉及。
name
String
参数解释：
节点名称。
取值范围：
不涉及。
role
String
参数解释：
节点类型。
取值范围：
- master：主节点。
- slave：备节点。
- readreplica：只读节点。
status
String
参数解释：
节点状态。
availability_zone
String
参数解释：
可用区。
取值范围：
不涉及。
表10 related_instance字段数据结构说明 名称
参数类型
说明
id
String
参数解释：
关联实例ID。
取值范围：
不涉及。
type
String
参数解释：
关联实例类型。
取值范围：
- replica_of：表示主实例。
- replica：表示只读实例。
表11 chargeInfo字段数据结构说明 名称
是否必选
参数类型
说明
charge_mode
是
String
参数解释：
计费模式。
取值范围：
- prePaid：预付费，即包年/包月。
- postPaid：后付费，即按需付费。
表12 serverless_info字段数据结构说明 名称
是否必选
参数类型
说明
min_compute_unit
是
String
参数解释：
Serverless型实例的算力范围最小值。
取值范围：
0.5 ~ 8，单位：RCU。
max_compute_unit
是
String
参数解释：
Serverless型实例的算力范围最大值。
取值范围：
0.5 ~ 8，单位：RCU。
响应样例中，“region”和 “availability_zone”的值为示例值。
- 正常响应样例
{ "instances": [{ "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01", "status": "ACTIVE", "name": "mysql-0820-022709-01", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2018-08-20T02:33:49+0800", "updated": "2018-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"], "public_dns_names": [], "public_ips": [], "enable_ssl": false, "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "cpu": "2", "mem": "4", "switch_strategy": "", "read_only_by_user": false, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "enterprise_project_id": "0", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ], "associated_with_ddm": false }], "total_count": 1 }
- 查询所有实例列表：
{ "instances": [{ "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01", "status": "ACTIVE", "name": "mysql-0820-022709-01", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2018-08-20T02:33:49+0800", "updated": "2018-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "enable_ssl": false, "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"], "public_dns_names": [], "public_ips": [], "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "cpu": "2", "mem": "4", "switch_strategy": "", "read_only_by_user": false, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "enterprise_project_id": "0", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ], "associated_with_ddm": false }, { "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in02", "status": "ACTIVE", "name": "mysql-0820-022709-02", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2018-08-20T02:33:49+0800", "updated": "2018-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"], "public_dns_names": [], "public_ips": [], "enable_ssl": false, "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "cpu": "2", "mem": "4", "switch_strategy": "", "read_only_by_user": false, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "enterprise_project_id": "0", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ], "associated_with_ddm": false }], "total_count": 2 } - 查询Serverless型实例：
{ "instances": [ { "id": "06f4bde8fec442d7bb122f742c9e51dein01", "status": "ACTIVE", "name": "rds-4961", "port": 3306, "type": "Ha", "ha": { "replication_mode": "semisync" }, "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2023-10-24T03:10:28+0000", "updated": "2023-10-24T03:10:28+0000", "volume": { "type": "CLOUDSSD", "size": 40 }, "nodes": [ { "id": "0c4844b1323e4f30a7a49b021a047e36no01", "name": "rds-4961_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }, { "id": "62bb9a79e2c34c369845ede701a4cf34no01", "name": "rds-4961_node1", "role": "slave", "status": "ACTIVE", "availability_zone": "bbb" } ], "tags": [], "bpDomainId": "", "bpType": "Default", "alias": "", "private_ips": [], "private_dns_names": [ "0aabbcc.mysql.rds.myhuaweicloud.com" ], "public_dns_names": [], "public_ips": [], "enable_ssl": false, "db_user_name": "root", "vpc_id": "a70b5818-a306-426d-a53e-11b6b57c31af", "subnet_id": "7cac9cc5-7b87-414e-9913-cbbc5051347e", "security_group_id": "89f258c5-4b81-4ef0-be30-34f2ee07dd1c", "flavor_ref": "rds.mysql.serverless.ha", "switch_strategy": "reliability", "read_only_by_user": false, "charge_info": { "charge_mode": "postPaid" }, "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "18:00-22:00", "related_instance": [], "disk_encryption_id": "", "enterprise_project_id": "0", "time_zone": "UTC+08:00", "order_id": "", "associated_with_ddm": false, "serverless_info": { "max_compute_unit": "0.5", "min_compute_unit": "8" } } ], "total_count": 1 } - 异常响应
请参见异常请求结果。
状态码
- 正常
- 异常
请参见状态码。
错误码
请参见错误码。
