You can call the DescribeDBInstances operation to query one or more ApsaraDB RDS instances that meet the specified conditions.

You can use one of the following methods to check the response:

  • Method 1: Use the MaxResults parameter to specify the number of entries per page. Then, use the NextToken parameter to specify the token that is used to display the next page. The NextToken parameter is set to the value that is returned from the most recent call of the DescribeDBInstances operation for the NextToken parameter.
    Note The first time you call the DescribeDBInstances operation to perform a paged query, you need to specify only the MaxResults parameter. In this case, the operation returns the data of the first page and the value of the NextToken parameter.
  • Method 2: Use the PageSize parameter to specify the number of entries per page. Then, use the PageNumber parameter to display the next page.
Note You can use only one of the preceding methods. If a large number of entries are returned, we recommend that you use Method 1 to increase the query speed.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeDBInstances

The operation that you want to perform. Set the value to DescribeDBInstances.

ClientToken String No ETnLKlblzczshOTUbOCzxxxxxxx

The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The token can only contain ASCII characters and cannot exceed 64 characters in length.

proxyId String No API

The ID of the proxy mode.

Engine String No MySQL

The database engine that is run by the instances. Valid values:

  • MySQL
  • SQLServer
  • PostgreSQL
  • MariaDB

By default, this operation returns the instances that run any of the supported database engines.

ZoneId String No cn-hangzhou-a

The ID of the zone to which the instances belong.

ResourceGroupId String No rg-acfmyxxxxx

The ID of the resource group to which the instances belong.

DBInstanceStatus String No Running

The status of the instances. For more information, see Instance state table.

Expired String No True

Specifies whether the instances have expired. Valid values:

  • True: The instances have expired.
  • False: The instances have not expired.
SearchKey String No rm-uf6w

The keywords that are contained in the IDs or descriptions of the instances.

DBInstanceId String No rm-uf6wjk5xxxxxxx

The ID of the instance. You can call the DescribeDBInstances operation to query the IDs of instances.

DBInstanceType String No Primary

The role of the instances. Valid values:

  • Primary: primary instance
  • Readonly: read-only instance
  • Guard: disaster recovery instance
  • Temp: temporary instance

By default, this operation returns the instances that assume any of the supported roles.

RegionId String Yes cn-hangzhou

The ID of the region in which the instances reside. You can call the DescribeRegions operation to query the most recent region list.

PageSize Integer No 30

The number of entries to return on each page. Valid values: 1 to 100.

Default value: 30.

PageNumber Integer No 1

The number of the page to return. Valid values: any non-zero positive integer.

Default value: 1.

InstanceNetworkType String No Classic

The network type of the instances. Valid values:

  • VPC
  • Classic

By default, this operation returns the instances that reside in any of the supported types of networks.

VpcId String No vpc-uf6f7l4fg90xxxxxxxxxx

The ID of the virtual private cloud (VPC) to which the instances belong.

VSwitchId String No vsw-uf6adz52c2pxxxxxxxxxx

The ID of the vSwitch that is associated with the specified VPC.

DBInstanceClass String No rds.mys2.small

The instance type of the instances. For information, see Primary ApsaraDB RDS instance types.

EngineVersion String No 5.7

The version of the database engine that is run by the instances.

PayType String No Postpaid

The billing method of the instances. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: subscription
ConnectionMode String No Standard

The connection mode of the instance. Valid values:

  • Standard: standard mode
  • Safe: database proxy mode

By default, this operation returns the instances that run in any of the supported connection modes.

Tags String No {"key1":"value1"}

The tags that are added to the instances. Each tag is a key-value pair that consists of two parts: TagKey and TagValue. You can specify a maximum of five tags in the following format for each request: {"key1":"value1","key2":"value2"...}.

DedicatedHostGroupId String No dhg-7a9xxxxxxxx

The ID of the dedicated cluster to which the instances belong.

DedicatedHostId String No i-bpxxxxxxx

The ID of the host to which the instances belong in the specified dedicated cluster.

InstanceLevel Integer No 0

Specifies whether to return the RDS editions of the instances by using the Category parameter. Valid values:

  • 0: You want the RDS editions of the instances to be returned.
  • 1: You do not want the RDS editions of the instances to be returned.
ConnectionString String No rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com

The endpoint of the instance. Specify this parameter only when you want to query a single instance.

NextToken String No o7PORW5o2TJg**********

The token that is used to display the next page. This parameter is set to the value that is returned from the most recent call of the DescribeDBInstances operation for the NextToken parameter. If the returned entries are displayed on multiple pages, the next page can be displayed when you call this operation again with this parameter specified.

MaxResults Integer No 30

The number of entries to return on each page. Valid values: 1 to 100.

Default value: 30.

Note If you specify this parameter, the PageSize parameter and the PageNumber parameter are unavailable.

Response parameters

Parameter Type Example Description
RequestId String 1AD222E9-E606-4A42-BF6D-8A4442913CEF

The ID of the request.

PageNumber Integer 1

The number of the returned page.

Note If you specify the MaxResults parameter or the NextToken parameter, only the value 1 is returned. You can ignore the value 1.
PageRecordCount Integer 10

The number of instances returned on the current page.

TotalRecordCount Integer 100

The total number of entries.

Note If you specify the MaxResults parameter or the NextToken parameter, only the number of entries on the current page is returned. You can ignore the number.
Items Array of DBInstance

An array that consists of the information about the instances that are returned.

DBInstance
VpcId String vpc-uf6f7l4fg90xxxxxxx

The ID of the VPC to which the instance belongs.

DedicatedHostIdForLog String dh-bpxxxx

The ID of the host on which the logger instance resides.

CreateTime String 2018-11-05T11:26:02Z

The time when the instance was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

PayType String Postpaid

The billing method of the instance. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: subscription
DedicatedHostNameForLog String testlog

The name of the host on which the logger instance resides.

MutriORsignle Boolean true

Indicates whether the multi-zone deployment method is used for the instance. Valid values: true and false.

Note If the multi-zone deployment method is used for the instance, the zone ID of the instance contains MAZ. Example: cn-hangzhou-MAZ10(h,i).
DedicatedHostGroupName String testhostgroup

The name of the dedicated cluster to which the instance belongs.

EngineVersion String 5.7

The version of the database engine that is run by the instance.

DedicatedHostGroupId String dhg-7a9xxxxxxxx

The ID of the dedicated cluster to which the instance belongs.

VpcName String test-huadong

The name of the VPC to which the instance belongs.

DedicatedHostZoneIdForMaster String cn-hangzhou-c

The ID of the zone to which the primary instance belongs.

ConnectionString String rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com

The endpoint of the instance.

InstanceNetworkType String Classic

The network type of the instance. Valid values:

  • Classic
  • VPC
MasterInstanceId String rm-uf6wjk5xxxxxxxxxx

The ID of the primary instance. If the value of this parameter is null, the instance is a primary instance.

ExpireTime String 2019-02-27T16:00:00Z

The time at which the instance expires. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Note Pay-as-you-go instances never expire.
DestroyTime String 2018-11-05T11:26:02Z

The time when the instance was destroyed. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

GuardDBInstanceId String rm-uf64zsuxxxxxxxxxx

The ID of the disaster recovery instance. This parameter is returned only when the instance is a primary instance and has a disaster recovery instance.

DedicatedHostNameForMaster String testmaster

The name of the host on which the primary instance resides.

ZoneId String cn-hangzhou-a

The ID of the zone to which the instance belongs.

TipsLevel Integer 1

The severity level of the exception that is detected on the instance. This parameter is returned only when the instance runs MySQL on RDS Standard Edition and is created in a dedicated cluster. Valid values:

  • 1: The instance is normal.
  • 2: The specifications of the read-only instances do not match the specifications of the primary instance. You must adjust the specifications of these instances based on your business requirements.
DBInstanceId String rm-uf6wjk5xxxxxxxxxx

The ID of the instance.

DedicatedHostIdForMaster String dh-bpxxxx

The ID of the host on which the primary instance resides.

TempDBInstanceId String rm-uf64zsuxxxxxxxxxx

The ID of the temporary instance. This parameter is returned only when the instance is a primary instance and has a temporary instance.

DBInstanceStorageType String ModuleList.4.ModuleCode

The storage type of the instance.

ConnectionMode String Standard

The connection mode of the instance. Valid values:

  • Standard: standard mode
  • Safe: database proxy mode
LockMode String Unlock

Indicates whether the instance is locked. Valid values:

  • Unlock: The instance is not locked.
  • ManualLock: The instance is manually locked.
  • LockByExpiration: The instance is automatically locked after it expires.
  • LockByRestoration: The instance is automatically locked before it is rolled back.
  • LockByDiskQuota: The instance is automatically locked after its storage capacity is exhausted.
  • Released: The instance is released. After an instance is released, the instance cannot be unlocked. You can only restore the backup data of the instance to a new instance. This process requires a long period of time.
GeneralGroupName String TestGroup

The name of the dedicated cluster to which the instance belongs. This parameter is returned only when the instance runs MySQL on RDS Standard Edition and is created in a dedicated cluster.

VpcCloudInstanceId String rm-uf6wjk5xxxxxxx

The ID of the instance. This parameter is returned only when the instance resides in a VPC.

DedicatedHostZoneIdForSlave String cn-hangzhou-d

The ID of the zone to which the secondary instance belongs.

Tips String everything is fine.

The information about the exception that is detected on the instance. This parameter is returned only when the instance runs MySQL on RDS Standard Edition and is created in a dedicated cluster.

DedicatedHostZoneIdForLog String cn-hangzhou-b

The ID of the zone to which the logger instance belongs.

DedicatedHostNameForSlave String testslave

The name of the host to which the secondary instance belongs.

DBInstanceDescription String testdatabase

The description of the instance.

DBInstanceNetType String Internet

The type of network connection to the instance. Valid values:

  • Internet: Internet
  • Intranet: internal network
DBInstanceType String Primary

The role of the instance. Valid values:

  • Primary: primary instance
  • ReadOnly: read-only instance
  • Guard: disaster recovery instance
  • Temp: temporary instance
LockReason String instance_expired

The reason why the instance is locked.

DBInstanceStatus String Running

The status of the instance. For more information, see Instance state table.

RegionId String cn-hangzhou

The ID of the region where the instance resides.

VSwitchId String vsw-uf6adz52c2pxxxxxxx

The ID of the vSwitch that is associated with the specified VPC.

DedicatedHostIdForSlave String dh-bpxxxx

The ID of the host on which the secondary instance resides.

ResourceGroupId String rg-acfmyxxxxxxx

The ID of the resource group to which the instance belongs.

Category String Basic

The RDS edition of the instance. Valid values:

  • Basic: Basic Edition
  • HighAvailability: High-availability Edition
  • Finance: Enterprise Edition
Engine String MySQL

The database engine that is run by the instance.

DBInstanceClass String rds.mys2.small

The instance type of the instance. For information, see Primary ApsaraDB RDS instance types.

SwitchWeight Integer 100

Indicates whether the instance supports weight-based switchovers for high availability. This parameter is returned only when the instance runs MySQL on RDS Standard Edition and is created in a dedicated cluster. Valid values:

  • 100: The instance supports weight-based switchovers for high availability.
  • 0: The instance does not support weight-based switchovers for high availability.
ReadOnlyDBInstanceIds Array of ReadOnlyDBInstanceId

An array that consists of the IDs of the read-only instances that are attached to the instance. This parameter is returned only when the instance is a primary instance.

ReadOnlyDBInstanceId
DBInstanceId String rr-uf6wjk5xxxxxxx

The ID of the read-only instance.

DeletionProtection Boolean false

Indicates whether the release protection feature is enabled for the read-only instance. Valid values:

  • true: The release protection feature is enabled.
  • false: The release protection feature is disabled.
NextToken String o7PORW5o2TJg**********

The token that is used to display the next page. If the returned entries are displayed on multiple pages, the next page can be displayed when you call this operation again with the NextToken parameter specified.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=DescribeDBInstances
&RegionId=cn-hangzhou
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeDBInstancesResponse>
    <TotalRecordCount>1</TotalRecordCount>
    <PageRecordCount>1</PageRecordCount>
    <RequestId>A436D75C-30B0-1F34-8544-4B46F4407CC1</RequestId>
    <NextToken>o7PORW5owHNg**********</NextToken>
    <PageNumber>1</PageNumber>
    <Items>
        <DBInstance>
            <EngineVersion>10.0</EngineVersion>
            <ZoneId>cn-hangzhou-h</ZoneId>
            <DBInstanceStatus>Running</DBInstanceStatus>
            <ResourceGroupId>rg-acfmyiu********</ResourceGroupId>
            <DBInstanceNetType>Intranet</DBInstanceNetType>
            <DBInstanceClass>pg.n2.small.2c</DBInstanceClass>
            <CreateTime>2021-02-02T09:14:48Z</CreateTime>
            <VSwitchId>vsw-bp10aqj6o4lcl********</VSwitchId>
            <TipsLevel>0</TipsLevel>
            <DBInstanceType>Primary</DBInstanceType>
            <PayType>Prepaid</PayType>
            <LockMode>Unlock</LockMode>
            <DeletionProtection>false</DeletionProtection>
            <MutriORsignle>false</MutriORsignle>
            <InstanceNetworkType>VPC</InstanceNetworkType>
            <InsId>1</InsId>
            <VpcId>vpc-bp1opxu1zkhn0********</VpcId>
            <DBInstanceId>pgm-bp10re7n********</DBInstanceId>
            <ConnectionMode>Standard</ConnectionMode>
            <ReadOnlyDBInstanceIds>
            </ReadOnlyDBInstanceIds>
            <VpcCloudInstanceId>pgm-bp10re7n********</VpcCloudInstanceId>
            <RegionId>cn-hangzhou</RegionId>
            <ConnectionString>pgm-bp10re7n**************.pg.rds.aliyuncs.com</ConnectionString>
            <ExpireTime>2021-02-03T09:14:48Z</ExpireTime>
            <Engine>PostgreSQL</Engine>
        </DBInstance>
    </Items>
</DescribeDBInstancesResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "TotalRecordCount" : 1,
  "PageRecordCount" : 1,
  "RequestId" : "A436D75C-30B0-1F34-8544-4B46F4407CC1",
  "NextToken" : "o7PORW5owHNg**********",
  "PageNumber" : 1,
  "Items" : {
    "DBInstance" : [ {
      "EngineVersion" : "10.0",
      "ZoneId" : "cn-hangzhou-h",
      "DBInstanceStatus" : "Running",
      "ResourceGroupId" : "rg-acfmyiu********",
      "DBInstanceNetType" : "Intranet",
      "DBInstanceClass" : "pg.n2.small.2c",
      "CreateTime" : "2021-02-02T09:14:48Z",
      "VSwitchId" : "vsw-bp10aqj6o4lcl********",
      "TipsLevel" : 0,
      "DBInstanceType" : "Primary",
      "PayType" : "Prepaid",
      "LockMode" : "Unlock",
      "DeletionProtection" : false,
      "MutriORsignle" : false,
      "InstanceNetworkType" : "VPC",
      "InsId" : 1,
      "VpcId" : "vpc-bp1opxu1zkhn0********",
      "DBInstanceId" : "pgm-bp10re7n********",
      "ConnectionMode" : "Standard",
      "ReadOnlyDBInstanceIds" : {
        "ReadOnlyDBInstanceId" : [ ]
      },
      "VpcCloudInstanceId" : "pgm-bp10re7n********",
      "RegionId" : "cn-hangzhou",
      "ConnectionString" : "pgm-bp10re7n**************.pg.rds.aliyuncs.com",
      "ExpireTime" : "2021-02-03T09:14:48Z",
      "Engine" : "PostgreSQL"
    } ]
  }
}

Error codes

HTTP status code Error code Error message Description
400 Invalid.NextToken The parameter NextToken is invalid. The error message returned because the value of the NextToken parameter is invalid.
400 InvalidDBInstanceType.ValueNotSupport The specified parameter"DBInstanceType" is not valid. The error message returned because the specified instance type is invalid. Specify a valid instance type.

For a list of error codes, visit the API Error Center.