Queries one or more ApsaraDB for RDS instances that meet the specified conditions.

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 ID of the region to which the instances belong. 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 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 the instances run. Valid values:

  • MySQL
  • SQLServer
  • PostgreSQL
  • PPAS
  • MariaDB

By default, the system returns instances that run all 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 state of the instances. For more information, see Instance status table.

Expired String No True

Specifies whether to query instances that have expired. Valid values:

  • True: specifies to query instances that have expired.
  • False: specifies to query instances that have not expired.
SearchKey String No rm-uf6w

The keywords that are used for a fuzzy search of instances. The keywords can be part of an instance ID or description.

DBInstanceId String No rm-uf6wjk5xxxxxxx

The ID of the single instance to query.
DBInstanceType String No Primary

The role of the instances. Valid values:

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

The system returns instances with all of the supported roles by default.
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, the system returns both instances in virtual private clouds (VPCs) and those in the classic network.

VpcId String No vpc-uf6f7l4fg90xxxxxxxxxx

The ID of the VPC to which the instances belong.
VSwitchId String No vsw-uf6adz52c2pxxxxxxxxxx

The ID of the VSwitch associated with the specified VPC.
DBInstanceClass String No rds.mys2.small

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

EngineVersion String No 5.7

The version of the database engine that the instances run.
PayType String No Postpaid

The billing method of the instances. Valid values:

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

The connection mode of the instances. Valid values:

  • Standard: the standard mode.
  • Safe: the proxy database mode.

By default, the system returns both instances in standard mode and those in database proxy mode.

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

The tags to which the instances are bound. Each tag is a key-value pair that consists of two parts: TagKey and TagValue. A maximum of five tags are allowed in a single request. Format: {"key1":"value1","key2":"value2"...}.

DedicatedHostGroupId String No dhg-7a9xxxxxxxx

The ID of the dedicated cluster to which the instances belong if the instances are created in a dedicated cluster.

DedicatedHostId String No i-bpxxxxxxx

The ID of the host to which the instances belong if the instances are created in a dedicated cluster.

InstanceLevel Integer No 0

Specifies whether to return the RDS edition (the Category parameter) of the instances. Valid values:

  • 0: specifies not to return the RDS edition of the instances.
  • 1: specifies to return the RDS edition of the instances.

Response parameters

Parameter Type Example Description
PageRecordCount Integer 10

The number of instances returned on the current page.
TotalRecordCount Integer 100

The total number of entries returned.
PageNumber Integer 1

The page number of the page returned.
RequestId String 1AD222E9-E606-4A42-BF6D-8A4442913CEF

The ID of the request.
Items Array

An array that consists of instances and their information.
DBInstance
DBInstanceId String rm-uf6wjk5xxxxxxxxxx

The ID of the instance.
DBInstanceDescription String testdatabase

The description of the instance.
PayType String Postpaid

The billing method of the instance. Valid values:

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

The role of the instance. Valid values:

  • Primary: the primary instance role.
  • ReadOnly: the read-only instance role.
  • Guard: the disaster recovery instance role.
  • Temp: the temporary instance role.
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 standard mode.
  • Safe: the database proxy mode.
RegionId String cn-hangzhou

The ID of the region where the instance belongs.
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-billed instances never expire.
DBInstanceStatus String Running

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

Engine String MySQL

The database engine that the instance runs.
DBInstanceNetType String Internet

The network connection type of 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 state of the instance. Valid values:

  • Unlock: The instance is not locked.
  • ManualLock: The instance has been manually locked.
  • LockByExpiration: The instance has been locked upon expiration.
  • LockByRestoration: The instance has been locked before a rollback.
  • LockByDiskQuota: The instance has been locked because its storage capacity is exhausted.
  • Released: The instance has been released. You cannot unlock an instance that has been released. After an instance is released, you can only use a backup to restore the data of the instance to a new instance. This process requires a long time.
LockReason String instance_expired

The reason why the instance is locked.
MasterInstanceId String rm-uf6wjk5xxxxxxxxxx

The ID of the primary instance to which the instance is attached. If no value is returned for this parameter (namely, the value of this parameter is null), the instance is a primary instance.

GuardDBInstanceId String rm-uf64zsuxxxxxxxxxx

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

TempDBInstanceId String rm-uf64zsuxxxxxxxxxx

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

AutoUpgradeMinorVersion String Auto

The method that is used to upgrade the minor engine version of the instance. Valid values:

  • Auto: automatic upgrade.
  • Manual: manual upgrade. The system forcibly upgrades the minor engine version only when the minor engine version is phased out.
Category String Basic

The RDS edition of the instance. Valid values:

  • Basic: the Basic Edition.
  • HighAvailability: the High-availability Edition.
  • Finance: the Enterprise Edition.
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 type of the instance. For more information, see Primary instance types.

DBInstanceStorageType String ModuleList.4.ModuleCode

The storage type of the instance.
DedicatedHostGroupId String dhg-7a9xxxxxxxx

The ID of the dedicated cluster to which the instance belongs.
DedicatedHostIdForLog String dh-bpxxxx

The ID of the host to which the log 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 log 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 ID of the zone to which the log instance belongs.
DedicatedHostZoneIdForMaster String cn-hangzhou-c

The ID of the zone to which the primary instance belongs.
DedicatedHostZoneIdForSlave String cn-hangzhou-d

The ID of the zone to which the secondary instance belongs.
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 the instance runs.
MutriORsignle Boolean true

Indicates whether the instance is deployed in multiple zones. Valid values:true and false.

ReadOnlyDBInstanceIds Array

An array that consists of the read-only instances attached to the instance if 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 read-only instance belongs.
VSwitchId String vsw-uf6adz52c2pxxxxxxx

The ID of the VSwitch associated with the specified VPC.
VpcCloudInstanceId String rm-uf6wjk5xxxxxxx

The ID of the read-only instance that resides in a VPC.
VpcId String vpc-uf6f7l4fg90xxxxxxx

The ID of the VPC to which the read-only instance belongs.
ZoneId String cn-hangzhou-a

The ID of the zone to which the read-only instance belongs.

Examples

Sample requests

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

Sample success responses

XML format 

<DescribeDBInstancesResponse>
  <Items>
		    <DBInstance>
			      <LockMode>Unlock</LockMode>
			      <DBInstanceNetType>Intranet</DBInstanceNetType>
			      <DBInstanceClass>ppas.x4.xlarge.2</DBInstanceClass>
			      <ResourceGroupId>rg-acfnt75uxxxxx</ResourceGroupId>
			      <DBInstanceId>rm-dj120j44xxxxx</DBInstanceId>
			      <VpcCloudInstanceId></VpcCloudInstanceId>
			      <ZoneId>cn-beijing-MAZ3(c,e)</ZoneId>
			      <ReadOnlyDBInstanceIds></ReadOnlyDBInstanceIds>
			      <ConnectionMode>Standard</ConnectionMode>
			      <InstanceNetworkType>Classic</InstanceNetworkType>
			      <Engine>PPAS</Engine>
			      <MutriORsignle>true</MutriORsignle>
			      <ExpireTime></ExpireTime>
			      <CreateTime>2019-03-20T02:18:02Z</CreateTime>
			      <DBInstanceType>Primary</DBInstanceType>
			      <RegionId>cn-beijing</RegionId>
			      <EngineVersion>10.0</EngineVersion>
			      <LockReason></LockReason>
			      <DBInstanceStatus>Running</DBInstanceStatus>
			      <PayType>Postpaid</PayType>
		    </DBInstance>
	  </Items>
	  <TotalRecordCount>1</TotalRecordCount>
	  <PageNumber>1</PageNumber>
	  <RequestId>0C2B0363-2707-4300-9900-0A65846CE48E</RequestId>
	  <PageRecordCount>1</PageRecordCount>
</DescribeDBInstancesResponse>

JSON format 

{
	"Items": {
		"DBInstance": [
			{
				"LockMode": "Unlock",
				"DBInstanceNetType": "Intranet",
				"DBInstanceClass": "ppas.x4.xlarge.2",
				"ResourceGroupId": "rg-acfnt75uxxxxx",
				"DBInstanceId": "rm-dj120j44xxxxx",
				"VpcCloudInstanceId": "",
				"ZoneId": "cn-beijing-MAZ3(c,e)",
				"ReadOnlyDBInstanceIds": {
					"ReadOnlyDBInstanceId": []
				},
				"ConnectionMode": "Standard",
				"InstanceNetworkType": "Classic",
				"Engine": "PPAS",
				"MutriORsignle": true,
				"ExpireTime": "",
				"CreateTime": "2019-03-20T02:18:02Z",
				"DBInstanceType": "Primary",
				"RegionId": "cn-beijing",
				"EngineVersion": "10.0",
				"LockReason": "",
				"DBInstanceStatus": "Running",
				"PayType": "Postpaid"
			}
		]
	},
	"TotalRecordCount": 1,
	"PageNumber": 1,
	"RequestId": "0C2B0363-2707-4300-9900-0A65846CE48E",
	"PageRecordCount": 1
}

Errors

HTTP status code Error code Error message Description
400 InvalidDBInstanceType.ValueNotSupport The specified parameter"DBInstanceType" is not valid. The error message returned because the specified DBInstanceType is invalid.

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