文档首页/ 云数据库 RDS/ API参考（巴黎区域）/ API v3（推荐）/ 实例管理/ 查询数据库实例列表

更新时间：2024-07-04 GMT+08:00

查看PDF

查询数据库实例列表

功能介绍

根据指定条件查询实例列表。

调用接口前，您需要了解API 认证鉴权。
调用接口前，您需要提前获取到地区和终端节点，即下文中的Endpoint值。

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}&tags={key}={value}
URI样例
- 查询所有实例列表
   https://{Endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances
- 根据指定条件查询实例列表
   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

参数说明

表1 参数说明
名称	参数类型	是否必选	说明
project_id	String	是	租户在某一region下的project 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。
tags	Array of objects	否	根据实例标签键值对进行查询。 {key}表示标签键，不可以为空或重复。 {value}表示标签值，可以为空。如果同时使用多个标签键值对进行查询，中间使用逗号分隔开，最多包含10组。详情请参见表2。

表2 tags字段数据结构说明
名称	参数类型	是否必选	说明
key	String	是	键。最大长度127个unicode字符。key不能为空或者空字符串，不能为空格，使用之前先trim前后半角空格。不能包含+/?#&=,%特殊字符。
value	String	否	值。最大长度255个unicode字符，使用之前先trim 前后半角空格。不能包含+/?#&=,%特殊字符。如果value为空，则表示any_value（查询任意value）。

请求消息

无。

响应消息

正常响应要素说明

表3 参数说明
名称	参数类型	说明
instances	Array of objects	实例信息。详情请参见表4。
total_count	Integer	总记录数。

表4 instances字段数据结构说明
名称	参数类型	说明
id	String	实例ID。
name	String	创建的实例名称。
status	String	实例状态。取值：值为“BUILD”，表示实例正在创建。值为“ACTIVE”，表示实例正常。值为“FAILED”，表示实例异常。值为“MODIFYING”，表示实例正在扩容。值为“REBOOTING”，表示实例正在重启。值为“RESTORING”，表示实例正在恢复。值为“MODIFYING INSTANCE TYPE”，表示实例正在转主备。值为“SWITCHOVER”，表示实例正在主备切换。值为“MIGRATING”，表示实例正在迁移。值为“BACKING UP”，表示实例正在进行备份。值为“MODIFYING DATABASE PORT”，表示实例正在修改数据库端口。
private_ips	List<String>	实例内网IP地址列表。弹性云服务器创建成功后该值存在，其他情况下为空字符串。
private_dns_names	List<String>	实例内网域名列表。实例创建成功后，需要手动申请内网域名，否则查询内网域名为空。
public_ips	List<String>	实例外网IP地址列表。
port	Integer	数据库端口号。 MySQL数据库端口设置范围为1024～65535（其中12017和33071被RDS系统占用不可设置）。 PostgreSQL数据库端口修改范围为2100～9500。 Microsoft SQL Server实例的端口设置范围为1433和2100~9500（其中5355和5985不可设置）。当不传该参数时，默认端口如下： MySQL默认3306。 PostgreSQL默认5432。 Microsoft SQL Server默认1433。
type	String	实例类型，取值为“Single”，“Ha”或“Replica”, "Enterprise"，分别对应于单机实例、主备实例、只读实例、分布式实例（企业版）。
ha	Object	HA信息，获取HA实例时返回。详情请参见表4。
region	String	实例所在区域。
datastore	Object	数据库信息。详情请参见表5。
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	规格码。
volume	Object	Volume信息。详情请参见表6。
switch_strategy	String	数据库切换策略。取值为“reliability”或“availability”，分别对应于可靠性优先和可用性优先。
backup_strategy	Object	备份策略。详情请参见表7。
maintenance_window	String	可维护时间窗，为UTC时间。
nodes	Array of objects	主备实例信息。详情请参见表8。
related_instance	Array of objects	所关联的数据库实例列表。详情请参见表9。
time_zone	String	时区。
tags	Array of objects	标签列表，没有标签默认为空数组。详情请参见表11。

表5 ha字段数据结构说明
名称	参数类型	说明
replication_mode	String	备机同步参数。取值：非空。 MySQL为“async”或“semisync”。 PostgreSQL为“async”或“sync”。 Microsoft SQL Server为“sync”。说明： “async”为异步模式。 “semisync”为半同步模式。 “sync”为同步模式。

表6 datastore字段数据结构说明
名称	参数类型	说明
type	String	数据库引擎。
version	String	数据库版本。

表7 volume字段数据结构说明
名称	参数类型	说明
type	String	磁盘类型。
size	Integer	磁盘大小。

表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** tags字段数据结构说明
名称	参数类型	说明
key	String	标签键。
value	String	标签值。

响应样例中，“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"
	}],
	"private_ips": ["192.168.0.142"],
	"public_ips": ["10.154.219.187", "10.154.219.186"],
	"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",
	"switch_strategy": "",
	"backup_strategy": {
		"start_time": "19:00-20:00",
		"keep_days": 7
	},
	"maintenance_window": "02:00-06:00",
	"related_instance": [],
	"time_zone": ""，
        "tags" [
            {
                "key": "rds001",
                "value": "001"
            },
            {
                "key": "rds002",
                "value": "002"
            }
         ]
}], "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"
		}],
		"private_ips": ["192.168.0.142"],
		"public_ips": ["10.154.219.187", "10.154.219.186"],
		"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",
		"switch_strategy": "",
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"time_zone": ""，
    		        "tags" [
     	       {
       		         "key": "rds001",
       		         "value": "001"
      		      },
     		       {
      		          "key": "rds002",
      		          "value": "002"
     		       }
   		      ]
	}, {
		"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"
		}],
		"private_ips": ["192.168.0.142"],
		"public_ips": ["10.154.219.187", "10.154.219.186"],
		"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",
		"switch_strategy": "",
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"time_zone": ""，
    		        "tags" [
     	       {
       		         "key": "rds001",
       		         "value": "001"
      		      },
     		       {
      		          "key": "rds002",
      		          "value": "002"
     		       }
   		      ]
	}],
	"total_count": 2
}

异常响应
 请参见异常请求结果。

状态码

请参见状态码。

错误码

请参见错误码。

父主题： 实例管理

上一篇：删除数据库实例

下一篇：参数配置

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消