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 only to specify 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 PageSize 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.

RegionId String Yes cn-hangzhou

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

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 make sure 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 that is used on the instances.

Engine String No MySQL

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

  • MySQL
  • SQLServer
  • PostgreSQL
  • PPAS
  • MariaDB TX

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 where the instances reside.

ResourceGroupId String No rg-acfmyxxxxx

The zone ID of the instances.

DBInstanceStatus String No Running

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

Expired String No True

Specifies whether the instances are expired. Valid values:

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

The keywords that are part of the IDs or descriptions of the instances.

DBInstanceId String No rm-uf6wjk5xxxxxxx

The ID of the instance. Specify this parameter only when you want to query a single 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: The instances are primary instances.
  • Readonly: The instances are read-only instances.
  • Guard: The instances are disaster recovery instances.
  • Temp: The instances are temporary instances.

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

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: non-zero positive integers.

Default value: 1.

InstanceNetworkType String No Classic

The network type of the instance. Valid values:

  • VPC
  • Classic

By default, this operation returns the instances that reside in virtual private clouds (VPCs) and the instances that reside in the classic network.

VpcId String No vpc-uf6f7l4fg90xxxxxxxxxx

The ID of the VPC where the instances reside.

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 on the instances.

PayType String No Postpaid

The billing method of the instance. Valid values:

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

The connection mode of the instance. Valid values:

  • Standard: The instances are connected in standard mode.
  • Safe: The instances are connected in database proxy mode.

By default, this operation returns the instances that are connected in standard mode and the instances that are connected in database proxy mode.

Tags String No null

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 edition of the instances. The RDS edition is indicated by the Category parameter.

  • 0: specifies not to return the RDS edition of the instances.
  • 1: specifies to return the RDS edition of the instances.
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 returned entries 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
PageRecordCount Integer 10

The number of instances that are returned on the current page.

TotalRecordCount Integer 100

The total number of entries that are returned.

Note If you specify the MaxResults parameter or the NextToken parameter, only the number of entries on the current page is returned and can be ignored.
PageNumber Integer 1

The page number of the returned page.

Note If you specify the MaxResults parameter or the NextToken parameter, only the value 1 is returned and can be ignored.
Items Array of DBInstance

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

DBInstance
DBInstanceId String rm-uf6wjk5xxxxxxxxxx

The ID of the instance.

DBInstanceDescription String Test database

The description of the instance.

PayType String Postpaid

The billing method of the instance. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: subscription
DBInstanceType String Primary

The role of the instance. Valid values:

  • Primary: The instance is a primary instance.
  • ReadOnly: The instance is a read-only instance.
  • Guard: The instance is a disaster recovery instance.
  • Temp: The instance is a temporary instance.
InstanceNetworkType String Classic

The network type of the instance. Valid values:

  • Classic
  • VPC
ConnectionMode String Performance

The connection mode of the instance. Valid values:

  • Standard: The instance is connected in standard mode.
  • Safe: The instance is connected in database proxy mode.
RegionId String cn-hangzhou

The region ID of the instance.

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

The expiration time of the instance. 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.
DBInstanceStatus String Running

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

Engine String MySQL

The database engine that is run on the instance.

DBInstanceNetType String Internet

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

  • Internet: The instance is connected over the Internet.
  • Intranet: The instance is connected over an internal network.
LockMode String Unlock

The lock status of the instance. 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 the allocated storage is exhausted.
  • Released: The instance is released. After an instance is released, the instance cannot be unlocked. You can only restore the data of the instance to a new instance by using backup files. This process requires a long period of time.
LockReason String instance_expired

The reason why the instance is locked.

MasterInstanceId String rm-uf6wjk5xxxxxxxxxx

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

GuardDBInstanceId String rm-uf64zsuxxxxxxxxxx

The ID of the disaster recovery instance that is attached to the instance. This parameter is returned only when the instance is a primary instance to which a disaster recovery instance is attached.

TempDBInstanceId String rm-uf64zsuxxxxxxxxxx

The ID of the temporary instance that is attached to the instance. This parameter is returned only when the instance is a primary instance to which a temporary instance is attached.

Category String Basic

The RDS edition of the instance. Valid values:

  • Basic: Basic Edition
  • HighAvailability: High-availability Edition
  • Finance: Enterprise Edition
ConnectionString String rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com

The endpoint of the instance.

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.

DBInstanceClass String rds.mys2.small

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

DBInstanceStorageType String ModuleList.4.ModuleCode

The type of storage media that is used for the instance.

DedicatedHostGroupId String dhg-7a9xxxxxxxx

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

DedicatedHostGroupName String testhostgroup

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

DedicatedHostIdForLog String dh-bpxxxx

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

DedicatedHostIdForMaster String dh-bpxxxx

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

DedicatedHostIdForSlave String dh-bpxxxx

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

DedicatedHostNameForLog String testlog

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

DedicatedHostNameForMaster String testmaster

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

DedicatedHostNameForSlave String testslave

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

DedicatedHostZoneIdForLog String cn-hangzhou-b

The zone ID of the logger instance.

DedicatedHostZoneIdForMaster String cn-hangzhou-c

The zone ID of the primary instance.

DedicatedHostZoneIdForSlave String cn-hangzhou-d

The zone ID of the secondary instance.

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.

EngineVersion String 5.7

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

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.

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).
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.

ResourceGroupId String rg-acfmyxxxxxxx

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

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.
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.

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.
VSwitchId String vsw-uf6adz52c2pxxxxxxx

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

VpcCloudInstanceId String rm-uf6wjk5xxxxxxx

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

VpcId String vpc-uf6f7l4fg90xxxxxxx

The ID of the VPC where the instance resides.

VpcName String test-huadong

The name of the VPC where the instance resides.

ZoneId String cn-hangzhou-a

The zone ID of the instance.

RequestId String 1AD222E9-E606-4A42-BF6D-8A4442913CEF

The ID of the request.

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

<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>
              <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

{
    "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",
                "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.