Queries the ApsaraDB for RDS instances that are created in a region or those that are authorized by using RAM.

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 pattern.
Engine String No MySQL

The database engine that the instances are running. Valid values:

  • MySQL
  • SQLServer
  • PostgreSQL
  • PPAS
  • MariaDB

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

Expired String No True

Specifies whether to query expired instances. 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 key to use for a fuzzy search based on an instance ID or description.
DBInstanceId String No rm-uf6wjk5xxxxxxx

The instance ID to use for a fuzzy search.
DBInstanceType String No Primary

The role of the instances. Valid values:

  • Primary: specifies to query primary instances.
  • Readonly: specifies to query read-only instances.
  • Guard: specifies to query disaster recovery instances.
  • Temp: specifies to query temporary instances.

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. Pages start from page 1.

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 VPCs and those in classic networks.
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 are running.
PayType String No Postpaid

The billing method of the instances. Valid values:

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

The connection mode of the instances. Valid values:

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

The system returns both instances in standard mode and those in database proxy mode by default.

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. You can enter up to five tags 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.
DedicatedHostId String No i-bpxxxxxxx

The ID of the host to which the instances belong.

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 current page.
RequestId String 1AD222E9-E606-4A42-BF6D-8A4442913CEF

The ID of the request.
Items Array

An array that consists of instances.
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: The instance uses pay-as-you-go billing.
  • Prepaid: The instance uses subscription billing.
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 ID of the region to which 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 status of the instance. For more information, see Instance status table.

Engine String MySQL

The database engine that the instance is running.
DBInstanceNetType String Internet

The network 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 status 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 this parameter is not returned, 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 update the kernel version of the instance. Valid values:

  • Auto: The system automatically updates the kernel version of the instance.
  • Manual: The system does not automatically update the kernel version of the instance. The kernel version of the instance is forcibly updated only when the current kernel version is phased out.
Category String Basic

The RDS edition of the instance. Valid values:

  • Basic: The instance is running the Basic Edition.
  • HighAvailability: The system is running the High-availability Edition.
  • Finance: The system is running 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.
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 is running.
MutriORsignle Boolean true

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

ReadOnlyDBInstanceIds Array

An array that consists of read-only instances if the primary instance is attached with the read-only instances.

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>
                  <InsId>1</InsId>
                  <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,
                "InsId": 1,
                "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
}

Error codes

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.