调用DescribeDBInstances查询实例列表_云数据库 RDS-阿里云帮助中心

该接口用于查询RDS的实例列表。

接口说明

适用引擎

RDS MySQL
RDS PostgreSQL
RDS SQL Server
RDS MariaDB

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
rds:DescribeDBInstances	READ	DBInstance acs:rds:{#regionId}:{#accountId}:dbinstance/{#dbinstanceId}	rds:ResourceTag	无

请求参数

名称	类型	必填	描述	示例值
ClientToken	string	否	用于保证请求的幂等性，防止重复提交请求。由客户端生成该参数值，要保证在不同请求间唯一，最大值不超过64个ASCII字符，且该参数值中不能包含非ASCII字符。	ETnLKlblzczshOTUbOCz****
proxyId	string	否	废弃参数，无需配置。	API
Engine	string	否	数据库类型，取值： MySQL SQLServer PostgreSQL MariaDB 默认返回所有数据库类型。	MySQL
ZoneId	string	否	可用区ID。	cn-hangzhou-a
ResourceGroupId	string	否	资源组ID。	rg-acfmy****
DBInstanceStatus	string	否	实例状态，详情请参见实例状态表。	Running
Expired	string	否	实例的过期状态，取值： True：已过期 False：未过期	True
SearchKey	string	否	可基于实例ID或者实例备注模糊搜索。	rm-uf6w
DBInstanceId	string	否	实例ID。	rm-uf6wjk5****
DBInstanceType	string	否	实例类型，取值： Primary：主实例 Readonly：只读实例 Guard：灾备实例 Temp：临时实例默认返回所有实例类型。	Primary
RegionId	string	是	地域ID。可调用DescribeRegions获取。	cn-hangzhou
PageSize	integer	否	每页记录数，取值：1~100。默认值：30。	30
PageNumber	integer	否	页码，取值：大于0且不超过Integer的最大值。默认值：1。	1
InstanceNetworkType	string	否	实例的网络类型，取值： VPC：专有网络下的实例 Classic：经典网络下的实例默认返回所有网络类型下的实例。	Classic
VpcId	string	否	VPC ID。	vpc-uf6f7l4fg90****
VSwitchId	string	否	交换机ID。	vsw-uf6adz52c2p****
DBInstanceClass	string	否	实例规格，详见实例规格表。	rds.mys2.small
EngineVersion	string	否	数据库版本。	8.0
PayType	string	否	付费类型，取值： Postpaid：按量付费 Prepaid：包年包月	Postpaid
ConnectionMode	string	否	实例的访问模式，取值： Standard：标准访问模式 Safe：数据库代理模式默认返回所有访问模式下的实例。	Standard
Tags	string	否	查询绑定有该标签的实例，包括TagKey和TagValue。单次最多支持传入5组值，格式：{"key1":"value1","key2":"value2"...}。	{"key1":"value1"}
DedicatedHostGroupId	string	否	专属集群ID。	dhg-7a9****
DedicatedHostId	string	否	专属集群内的主机ID。	i-bp****
InstanceLevel	integer	否	是否返回实例系列（Category）信息，取值： 0：不返回 1：返回	0
ConnectionString	string	否	实例的连接地址。通过该连接地址查询对应的实例。	rm-uf6wjk5****.mysql.rds.aliyuncs.com
NextToken	string	否	翻页凭证。取值为上一次调用DescribeDBInstances接口时返回的NextToken参数值。如果调用结果分多页展示，再次调用接口时传入该值便可以展示下一页的内容。	o7PORW5o2TJg****
MaxResults	integer	否	每页记录数。取值：1~100。默认值：30。说明传入该参数，则PageSize和PageNumber参数不可用。	30
Filter	string	否	实例过滤条件参数及其值的JSON串	{"babelfishEnabled":"true"}
Category	string	否	实例的系列。取值： Basic：基础版 HighAvailability：高可用 cluster：集群版 serverless_basic：Serverless	cluster

本接口支持如下两种方式查看返回数据：

方式一：通过传入MaxResults参数设置每页的记录数，再通过NextToken参数设置翻页凭证来展示下一页的内容。NextToken取值为上一次调用DescribeDBInstances接口返回的NextToken参数值。

说明首次调用接口进行分页查询时，您只需设置MaxResults参数，接口会返回第一页的数据和NextToken参数值。

方式二：通过PageSize参数设置每页的记录数，通过PageNumber参数进行翻页。

说明上述两种方式只能任选其一。当返回的记录数较多时，推荐使用方式一，可以获得更快的查询速度。

返回参数

名称	类型	描述	示例值
	object	返回参数详情。
RequestId	string	请求ID。	1AD222E9-E606-4A42-BF6D-8A4442913CEF
PageNumber	integer	页码。说明若您传入了MaxResults或NextToken参数，则本返回值仅会返回1，您可直接忽略。	1
PageRecordCount	integer	当前页实例个数。	10
TotalRecordCount	integer	总记录数。说明若您传入了MaxResults或NextToken参数，则本返回值仅会显示当前页的记录数，您可直接忽略。	100
Items	object []	实例信息列表。
VpcId	string	VPC ID。	vpc-uf6f7l4fg90****
DedicatedHostIdForLog	string	Log节点所在主机的ID。	dh-bp****
CreateTime	string	创建时间。格式：yyyy-MM-ddTHH:mm:ssZ（UTC时间）。	2018-11-05T11:26:02Z
PayType	string	实例的付费类型，取值： Postpaid：按量付费 Prepaid：包年包月	Postpaid
DedicatedHostNameForLog	string	Log节点所在主机的名称。	testlog
MutriORsignle	boolean	是否是组合可用区。取值： true false 说明组合可用区即带有MAZ字样的可用区。例如：`cn-hangzhou-MAZ10(h,i)`。	true
DedicatedHostGroupName	string	专属集群名称。	testhostgroup
EngineVersion	string	数据库版本。	5.7
DedicatedHostGroupId	string	专属集群ID。	dhg-7a9****
VpcName	string	VPC名称。	test-huadong
DedicatedHostZoneIdForMaster	string	Master节点所在主机的可用区ID。	cn-hangzhou-c
ConnectionString	string	实例的连接地址。	rm-uf6wjk5****.mysql.rds.aliyuncs.com
InstanceNetworkType	string	实例的网络类型，取值： Classic：经典网络 VPC：VPC网络	Classic
MasterInstanceId	string	主实例的ID，如果没有返回此参数（即为null）则表示该实例是主实例。	rm-uf6wjk5****
ExpireTime	string	到期时间。格式：yyyy-MM-ddTHH:mm:ssZ（UTC时间）。说明按量付费实例无到期时间。	2019-02-27T16:00:00Z
DestroyTime	string	销毁时间。格式：yyyy-MM-ddTHH:mm:ssZ（UTC时间）。	2018-11-05T11:26:02Z
GuardDBInstanceId	string	主实例如果有灾备实例，该参数即为灾备实例的ID。	rm-uf64zsu****
DedicatedHostNameForMaster	string	Master节点所在主机的名称。	testmaster
ZoneId	string	可用区ID。	cn-hangzhou-a
TipsLevel	integer	专属集群MySQL通用版实例的异常提示等级。返回值： 1：正常。 2：只读实例和主实例规格不对齐，可能影响可用性，请按需调整实例规格。	1
DBInstanceId	string	实例ID。	rm-uf6wjk5****
DedicatedHostIdForMaster	string	Master节点所在主机的ID。	dh-bp****
TempDBInstanceId	string	主实例如果有临时实例，该参数即为临时实例的ID。	rm-uf64zsu****
DBInstanceStorageType	string	实例储存类型。	ModuleList.4.ModuleCode
ConnectionMode	string	实例的访问模式，取值： Standard：标准访问模式 Safe：数据库代理模式	Standard
LockMode	string	实例的锁定状态。取值： Unlock：正常。 ManualLock：手动触发锁定。 LockByExpiration：实例过期自动锁定。 LockByRestoration：实例回滚前自动锁定。 LockByDiskQuota：实例空间满自动锁定。 Released：实例已释放。此时实例无法进行解锁，只能使用备份数据重新创建新实例，重建时间较长，请耐心等待。	Unlock
GeneralGroupName	string	专属集群MySQL通用版实例所属的组名。	TestGroup
VpcCloudInstanceId	string	专有网络实例ID。	rm-uf6wjk5****
DedicatedHostZoneIdForSlave	string	Slave节点所在主机的可用区ID。	cn-hangzhou-d
Tips	string	专属集群MySQL通用版实例的异常提示信息。	normal
DedicatedHostZoneIdForLog	string	Log节点所在主机的可用区ID。	cn-hangzhou-b
DedicatedHostNameForSlave	string	Slave节点所在主机的名称。	testslave
DBInstanceDescription	string	实例描述。	testdb
DBInstanceNetType	string	实例的网络连接类型，取值： Internet：外网连接 Intranet：内网连接	Internet
DBInstanceType	string	实例类型，取值： Primary：主实例 Readonly：只读实例 Guard：灾备实例 Temp：临时实例	Primary
LockReason	string	实例被锁定的原因。	instance_expired
DBInstanceStatus	string	实例状态，详情请参见实例状态表。	Running
RegionId	string	地域ID。	cn-hangzhou
VSwitchId	string	交换机ID。	vsw-uf6adz52c2p****
DedicatedHostIdForSlave	string	Slave节点所在主机的ID。	dh-bp****
ResourceGroupId	string	资源组ID。	rg-acfmy****
Category	string	实例系列： Basic：基础版 HighAvailability：高可用版 Finance：三节点企业版说明仅在InstanceLevel参数为1时返回。	Basic
Engine	string	数据库类型。	MySQL
DBInstanceClass	string	实例规格，详见实例规格表。	rds.mys2.small
SwitchWeight	integer	当前专属集群MySQL通用版实例是否支持高可用权重切换。返回值： 100：支持切换。 0：不支持切换。	100
ReadOnlyDBInstanceIds	object []	主实例下如果有只读实例，该参数为只读实例的ID列表。
DBInstanceId	string	只读实例ID。	rr-uf6wjk5****
DeletionProtection	boolean	是否已开启释放保护功能。取值： true：已开启 false：未开启	false
BurstingEnabled	boolean	是否已开启IO突发。取值： true：已开启 false：未开启	false
BpeEnabled	string	是否已开启BPE。取值： 1：已开启 0：未开启	0
NextToken	string	翻页凭证。如果调用结果分多页展示，再次调用接口时在NextToken处传入该值便可以展示下一页的内容。	o7PORW5o2TJg****

示例

正常返回示例

JSON格式

{
  "RequestId": "1AD222E9-E606-4A42-BF6D-8A4442913CEF",
  "PageNumber": 1,
  "PageRecordCount": 10,
  "TotalRecordCount": 100,
  "Items": {
    "DBInstance": [
      {
        "VpcId": "vpc-uf6f7l4fg90****",
        "DedicatedHostIdForLog": "dh-bp****",
        "CreateTime": "2018-11-05T11:26:02Z",
        "PayType": "Postpaid",
        "DedicatedHostNameForLog": "testlog",
        "MutriORsignle": true,
        "DedicatedHostGroupName": "testhostgroup",
        "EngineVersion": "5.7",
        "DedicatedHostGroupId": "dhg-7a9****",
        "VpcName": "test-huadong",
        "DedicatedHostZoneIdForMaster": "cn-hangzhou-c",
        "ConnectionString": "rm-uf6wjk5****.mysql.rds.aliyuncs.com",
        "InstanceNetworkType": "Classic",
        "MasterInstanceId": "rm-uf6wjk5****",
        "ExpireTime": "2019-02-27T16:00:00Z",
        "DestroyTime": "2018-11-05T11:26:02Z",
        "GuardDBInstanceId": "rm-uf64zsu****",
        "DedicatedHostNameForMaster": "testmaster",
        "ZoneId": "cn-hangzhou-a",
        "TipsLevel": 1,
        "DBInstanceId": "rm-uf6wjk5****",
        "DedicatedHostIdForMaster": "dh-bp****",
        "TempDBInstanceId": "rm-uf64zsu****",
        "DBInstanceStorageType": "ModuleList.4.ModuleCode",
        "ConnectionMode": "Standard",
        "LockMode": "Unlock",
        "GeneralGroupName": "TestGroup",
        "VpcCloudInstanceId": "rm-uf6wjk5****",
        "DedicatedHostZoneIdForSlave": "cn-hangzhou-d",
        "Tips": "normal",
        "DedicatedHostZoneIdForLog": "cn-hangzhou-b",
        "DedicatedHostNameForSlave": "testslave",
        "DBInstanceDescription": "testdb",
        "DBInstanceNetType": "Internet",
        "DBInstanceType": "Primary",
        "LockReason": "instance_expired",
        "DBInstanceStatus": "Running",
        "RegionId": "cn-hangzhou",
        "VSwitchId": "vsw-uf6adz52c2p****",
        "DedicatedHostIdForSlave": "dh-bp****",
        "ResourceGroupId": "rg-acfmy****",
        "Category": "Basic",
        "Engine": "MySQL",
        "DBInstanceClass": "rds.mys2.small",
        "SwitchWeight": 100,
        "ReadOnlyDBInstanceIds": {
          "ReadOnlyDBInstanceId": [
            {
              "DBInstanceId": "rr-uf6wjk5****"
            }
          ]
        },
        "DeletionProtection": false,
        "BurstingEnabled": false,
        "BpeEnabled": "0"
      }
    ]
  },
  "NextToken": "o7PORW5o2TJg****"
}

错误码

HTTP status code	错误码	错误信息	描述
400	Invalid.NextToken	The parameter NextToken is invalid.	参数NextToken无效。
400	InvalidDBInstanceType.ValueNotSupport	The specified parameter DBInstanceType is not valid.	-
400	InvalidParameter.OwnerAccount	The specified parameter OwnerAccount is not valid.	操作失败，参数OwnerAccount不合法，请检查。
400	TimeoutRetryLater	Timeout, Please retry later.	-
400	InvalidExpired.Format	The instance expiration status parameter is incorrect.	实例过期状态参数有误。

访问错误中心查看更多错误码。

变更历史

变更时间

变更内容概要

操作

2023-05-26

OpenAPI 错误码发生变更，OpenAPI 入参发生变更，OpenAPI 返回结构发生变更

看变更集

变更项	变更内容
错误码	OpenAPI 错误码发生变更
	删除错误码：400
入参	OpenAPI 入参发生变更
	新增入参：Category
出参	OpenAPI 返回结构发生变更

2023-05-15

OpenAPI 错误码发生变更

看变更集

变更项	变更内容
错误码	OpenAPI 错误码发生变更
	错误码 400 变更

2023-05-11

OpenAPI 错误码发生变更，OpenAPI 入参发生变更

看变更集

变更项	变更内容
错误码	OpenAPI 错误码发生变更
	删除错误码：400
入参	OpenAPI 入参发生变更
	新增入参：Filter

2022-09-01

OpenAPI 错误码发生变更

看变更集

变更项	变更内容
错误码	OpenAPI 错误码发生变更
	错误码 400 变更

2022-06-24

OpenAPI 描述信息更新，OpenAPI 错误码发生变更

看变更集

变更项	变更内容
API 描述	OpenAPI 描述信息更新
错误码	OpenAPI 错误码发生变更
	删除错误码：400

2021-10-11

OpenAPI 错误码发生变更，OpenAPI 返回结构发生变更

看变更集

变更项	变更内容
错误码	OpenAPI 错误码发生变更
	删除错误码：400
出参	OpenAPI 返回结构发生变更