文档

DescribeDBInstances - 查询实例列表

更新时间:

该接口用于查询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:DescribeDBInstancesRead
  • DBInstance
    acs:rds:{#regionId}:{#accountId}:dbinstance/{#dbinstanceId}
  • rds:ResourceTag

请求参数

名称类型必填描述示例值
ClientTokenstring

用于保证请求的幂等性,防止重复提交请求。由客户端生成该参数值,要保证在不同请求间唯一,最大值不超过 64 个 ASCII 字符,且该参数值中不能包含非 ASCII 字符。

ETnLKlblzczshOTUbOCz****
proxyIdstring

废弃参数,无需配置。

API
Enginestring

数据库类型,取值:

  • MySQL
  • SQLServer
  • PostgreSQL
  • MariaDB

默认返回所有数据库类型。

MySQL
ZoneIdstring

可用区 ID。

cn-hangzhou-a
ResourceGroupIdstring

资源组 ID。

rg-acfmy****
DBInstanceStatusstring

实例状态,详情请参见实例状态表

Running
Expiredstring

实例的过期状态,取值:

  • True:已过期
  • False:未过期
True
SearchKeystring

可基于实例 ID 或者实例备注模糊搜索。

rm-uf6w
DBInstanceIdstring

实例 ID。

rm-uf6wjk5****
DBInstanceTypestring

实例类型,取值:

  • Primary:主实例
  • Readonly:只读实例
  • Guard:灾备实例
  • Temp:临时实例

默认返回所有实例类型。

Primary
RegionIdstring

地域 ID。可调用 DescribeRegions 获取。

cn-hangzhou
PageSizeinteger

每页记录数,取值:1~100

默认值:30

30
PageNumberinteger

页码,取值:大于 0 且不超过 Integer 的最大值。

默认值:1

1
InstanceNetworkTypestring

实例的网络类型,取值:

  • VPC:专有网络下的实例
  • Classic:经典网络下的实例

默认返回所有网络类型下的实例。

Classic
VpcIdstring

VPC ID。

vpc-uf6f7l4fg90****
VSwitchIdstring

交换机 ID。

vsw-uf6adz52c2p****
DBInstanceClassstring

实例规格,详见实例规格表

rds.mys2.small
EngineVersionstring

数据库版本。

8.0
PayTypestring

付费类型,取值:

  • Postpaid:按量付费
  • Prepaid:包年包月
Postpaid
ConnectionModestring

实例的访问模式,取值:

  • Standard:标准访问模式
  • Safe:数据库代理模式

默认返回所有访问模式下的实例。

Standard
Tagsstring

查询绑定有该标签的实例,包括 TagKey 和 TagValue。单次最多支持传入 5 组值,格式:{"key1":"value1","key2":"value2"...}。

{"key1":"value1"}
DedicatedHostGroupIdstring

专属集群 ID。

dhg-7a9****
DedicatedHostIdstring

专属集群内的主机 ID。

i-bp****
InstanceLevelinteger

是否返回实例系列(Category)信息,取值:

  • 0:不返回
  • 1:返回
0
ConnectionStringstring

实例的连接地址。通过该连接地址查询对应的实例。

rm-uf6wjk5****.mysql.rds.aliyuncs.com
NextTokenstring

翻页凭证。取值为上一次调用 DescribeDBInstances 接口时返回的 NextToken 参数值。如果调用结果分多页展示,再次调用接口时传入该值便可以展示下一页的内容。

o7PORW5o2TJg****
MaxResultsinteger

每页记录数。取值:1~100

默认值:30

说明 传入该参数,则 PageSizePageNumber 参数不可用。
30
Filterstring

实例过滤条件参数及其值的 JSON 串

{"babelfishEnabled":"true"}
Categorystring

实例的系列。取值:

  • Basic:基础系列
  • HighAvailability:高可用系列
  • cluster:集群系列
  • serverless_basic:Serverless
cluster

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

  • 方式一:通过传入 MaxResults 参数设置每页的记录数,再通过 NextToken 参数设置翻页凭证来展示下一页的内容。NextToken 取值为上一次调用 DescribeDBInstances 接口返回的 NextToken 参数值。
说明 首次调用接口进行分页查询时,您只需设置 MaxResults 参数,接口会返回第一页的数据和 NextToken 参数值。
  • 方式二:通过 PageSize 参数设置每页的记录数,通过 PageNumber 参数进行翻页。
说明 上述两种方式只能任选其一。当返回的记录数较多时,推荐使用方式一,可以获得更快的查询速度。

返回参数

名称类型描述示例值
object

返回参数详情。

RequestIdstring

请求 ID。

1AD222E9-E606-4A42-BF6D-8A4442913CEF
PageNumberinteger

页码。

说明 若您传入了 MaxResultsNextToken 参数,则本返回值仅会返回 1,您可直接忽略。
1
PageRecordCountinteger

当前页实例个数。

10
TotalRecordCountinteger

总记录数。

说明 若您传入了 MaxResultsNextToken 参数,则本返回值仅会显示当前页的记录数,您可直接忽略。
100
Itemsobject []

实例信息列表。

VpcIdstring

VPC ID。

vpc-uf6f7l4fg90****
DedicatedHostIdForLogstring

Log 节点所在主机的 ID。

dh-bp****
CreateTimestring

创建时间。格式:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

2018-11-05T11:26:02Z
PayTypestring

实例的付费类型,取值:

  • Postpaid:按量付费
  • Prepaid:包年包月
Postpaid
DedicatedHostNameForLogstring

Log 节点所在主机的名称。

testlog
MutriORsignleboolean

是否是组合可用区。取值:

  • true
  • false
说明 组合可用区即带有 MAZ 字样的可用区。例如:cn-hangzhou-MAZ10(h,i)
true
DedicatedHostGroupNamestring

专属集群名称。

testhostgroup
EngineVersionstring

数据库版本。

5.7
DedicatedHostGroupIdstring

专属集群 ID。

dhg-7a9****
VpcNamestring

VPC 名称。

test-huadong
DedicatedHostZoneIdForMasterstring

Master 节点所在主机的可用区 ID。

cn-hangzhou-c
ConnectionStringstring

实例的连接地址。

rm-uf6wjk5****.mysql.rds.aliyuncs.com
InstanceNetworkTypestring

实例的网络类型,取值:

  • Classic:经典网络
  • VPC:VPC 网络
Classic
MasterInstanceIdstring

主实例的 ID,如果没有返回此参数(即为 null)则表示该实例是主实例。

rm-uf6wjk5****
ExpireTimestring

到期时间。格式:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

说明 按量付费实例无到期时间。
2019-02-27T16:00:00Z
DestroyTimestring

销毁时间。格式:yyyy-MM-ddTHH:mm:ssZ(UTC 时间)。

2018-11-05T11:26:02Z
GuardDBInstanceIdstring

主实例如果有灾备实例,该参数即为灾备实例的 ID。

rm-uf64zsu****
DedicatedHostNameForMasterstring

Master 节点所在主机的名称。

testmaster
ZoneIdstring

可用区 ID。

cn-hangzhou-a
TipsLevelinteger

专属集群 MySQL 通用版实例的异常提示等级。返回值:

  • 1:正常。
  • 2:只读实例和主实例规格不对齐,可能影响可用性,请按需调整实例规格。
1
DBInstanceIdstring

实例 ID。

rm-uf6wjk5****
DedicatedHostIdForMasterstring

Master 节点所在主机的 ID。

dh-bp****
TempDBInstanceIdstring

主实例如果有临时实例,该参数即为临时实例的 ID。

rm-uf64zsu****
DBInstanceStorageTypestring

实例储存类型。

ModuleList.4.ModuleCode
ConnectionModestring

实例的访问模式,取值:

  • Standard:标准访问模式
  • Safe:数据库代理模式
Standard
LockModestring

实例的锁定状态。取值:

  • Unlock:正常。
  • ManualLock:手动触发锁定。
  • LockByExpiration:实例过期自动锁定。
  • LockByRestoration:实例回滚前自动锁定。
  • LockByDiskQuota:实例空间满自动锁定。
  • Released:实例已释放。此时实例无法进行解锁,只能使用备份数据重新创建新实例,重建时间较长,请耐心等待。
Unlock
GeneralGroupNamestring

专属集群 MySQL 通用版实例所属的组名。

TestGroup
VpcCloudInstanceIdstring

专有网络实例 ID。

rm-uf6wjk5****
DedicatedHostZoneIdForSlavestring

Slave 节点所在主机的可用区 ID。

cn-hangzhou-d
Tipsstring

专属集群 MySQL 通用版实例的异常提示信息。

normal
DedicatedHostZoneIdForLogstring

Log 节点所在主机的可用区 ID。

cn-hangzhou-b
DedicatedHostNameForSlavestring

Slave 节点所在主机的名称。

testslave
DBInstanceDescriptionstring

实例描述。

testdb
DBInstanceNetTypestring

实例的网络连接类型,取值:

  • Internet:外网连接
  • Intranet:内网连接
Internet
DBInstanceTypestring

实例类型,取值:

  • Primary:主实例
  • Readonly:只读实例
  • Guard:灾备实例
  • Temp:临时实例
Primary
LockReasonstring

实例被锁定的原因。

instance_expired
DBInstanceStatusstring

实例状态,详情请参见实例状态表

Running
RegionIdstring

地域 ID。

cn-hangzhou
VSwitchIdstring

交换机 ID。

vsw-uf6adz52c2p****
DedicatedHostIdForSlavestring

Slave 节点所在主机的 ID。

dh-bp****
ResourceGroupIdstring

资源组 ID。

rg-acfmy****
Categorystring

实例系列:

  • Basic:基础系列
  • HighAvailability:高可用系列
  • Finance:三节点企业系列
说明 仅在 InstanceLevel 参数为 1 时返回。
Basic
Enginestring

数据库类型。

MySQL
DBInstanceClassstring

实例规格,详见实例规格表

rds.mys2.small
SwitchWeightinteger

当前专属集群 MySQL 通用版实例是否支持高可用权重切换。返回值:

  • 100:支持切换。
  • 0:不支持切换。
100
ReadOnlyDBInstanceIdsobject []

主实例下如果有只读实例,该参数为只读实例的 ID 列表。

DBInstanceIdstring

只读实例 ID。

rr-uf6wjk5****
DeletionProtectionboolean

是否已开启释放保护功能。取值:

  • true:已开启
  • false:未开启
false
BurstingEnabledboolean

是否已开启 IO 突发。取值:

  • true:已开启
  • false:未开启
false
BpeEnabledstring

弃用参数。

0
IoAccelerationEnabledstring

是否开启 IO 加速。取值含义如下:

  • 1:已开启
  • 0:未开启
0
ColdDataEnabledboolean

预留参数。

false
NextTokenstring

翻页凭证。如果调用结果分多页展示,再次调用接口时在 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",
        "IoAccelerationEnabled": "0",
        "ColdDataEnabled": false
      }
    ]
  },
  "NextToken": "o7PORW5o2TJg****"
}

错误码

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

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

变更历史

变更时间变更内容概要操作
2024-01-04OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
出参OpenAPI 返回结构发生变更
2023-05-26OpenAPI 错误码发生变更、OpenAPI 入参发生变更、OpenAPI 返回结构发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
入参OpenAPI 入参发生变更
    新增入参:Category
出参OpenAPI 返回结构发生变更
2023-05-15OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 400 变更
2023-05-11OpenAPI 错误码发生变更、OpenAPI 入参发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
入参OpenAPI 入参发生变更
    新增入参:Filter
2022-09-01OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    错误码 400 变更
2022-06-24OpenAPI 描述信息更新、OpenAPI 错误码发生变更看变更集
变更项变更内容
API 描述OpenAPI 描述信息更新
错误码OpenAPI 错误码发生变更
    删除错误码:400
2021-10-11OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
出参OpenAPI 返回结构发生变更
  • 本页导读 (1)
文档反馈