You can call the DescribeDBInstances operation to query one or more ApsaraDB 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 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 ensure that it is unique among different requests. The token can contain only 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, this operation returns the instances that run all 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 to query instances that have expired. Valid values:

  • True: specifies to query the instances that have expired.
  • False: specifies to query the 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

By default, this operation returns the instances of all 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 page number of the returned page. 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 both the 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 instance 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: the pay-as-you-go billing method
  • Prepaid: the subscription billing method
ConnectionMode String No Standard

The connection mode of the instances. Valid values:

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

By default, this operation returns both the 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 returned page.

Items Array of DBInstance

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: the pay-as-you-go billing method
  • Prepaid: the subscription billing method
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 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 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 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 automatically 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 period of 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 that is 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 that is 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 minor engine version of the instance. Valid values:

  • Auto: automatic upgrade.
  • Manual: manual upgrade. ApsaraDB RDS forcibly updates the current 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 instance 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 if the instance is created in a dedicated cluster.

DedicatedHostGroupName String testhostgroup

The name of the dedicated cluster to which the instance belongs if the instance is created in a dedicated cluster.

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 ID of the zone to which the logger 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 of ReadOnlyDBInstanceId

An array that consists of the read-only instances that are 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.

VpcName String test-huadong

The name of the VPC.

ZoneId String cn-hangzhou-a

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

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

The ID of the request.

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>B4309486-26EF-47B3-ADDE-6140B4C1109D</RequestId>
  <PageNumber>1</PageNumber>
  <Items>
        <DBInstance>
              <ResourceGroupId>rg-acxxxxx</ResourceGroupId>
              <DBInstanceNetType>Intranet</DBInstanceNetType>
              <DBInstanceType>Primary</DBInstanceType>
              <MutriORsignle>false</MutriORsignle>
              <InstanceNetworkType>VPC</InstanceNetworkType>
              <DBInstanceId>rm-bpxxxxx</DBInstanceId>
              <ReadOnlyDBInstanceIds>
        </ReadOnlyDBInstanceIds>
              <LockReason></LockReason>
              <DBInstanceDescription>test</DBInstanceDescription>
              <Engine>MySQL</Engine>
              <EngineVersion>8.0</EngineVersion>
              <DBInstanceStatus>Running</DBInstanceStatus>
              <ZoneId>cn-hangzhou-h</ZoneId>
              <DBInstanceClass>rds.mysql.s3.large</DBInstanceClass>
              <CreateTime>2020-06-17T09:03:57Z</CreateTime>
              <VSwitchId>vsw-bpxxxxx</VSwitchId>
              <PayType>Prepaid</PayType>
              <LockMode>Unlock</LockMode>
              <GuardDBInstanceId>rm-m5xxxxx</GuardDBInstanceId>
              <InsId>1</InsId>
              <VpcId>vpc-bpxxxxx</VpcId>
              <VpcName>test-huadong</VpcName>
              <ConnectionMode>Standard</ConnectionMode>
              <VpcCloudInstanceId>rm-bpxxxxx-1</VpcCloudInstanceId>
              <RegionId>cn-hangzhou</RegionId>
              <ExpireTime>2021-06-17T16:00:00Z</ExpireTime>
        </DBInstance>
  </Items>
</DescribeDBInstancesResponse>

JSON format

{
    "TotalRecordCount": 1,
    "PageRecordCount": 1,
    "RequestId": "B4309486-26EF-47B3-ADDE-6140B4C1109D",
    "PageNumber": 1,
    "Items": {
        "DBInstance": [
            {
                "ResourceGroupId": "rg-acxxxxx",
                "DBInstanceNetType": "Intranet",
                "DBInstanceType": "Primary",
                "MutriORsignle": false,
                "InstanceNetworkType": "VPC",
                "DBInstanceId": "rm-bpxxxxx",
                "ReadOnlyDBInstanceIds": {
                    "ReadOnlyDBInstanceId": []
                },
                "LockReason": "",
                "DBInstanceDescription": "test",
                "Engine": "MySQL",
                "EngineVersion": "8.0",
                "DBInstanceStatus": "Running",
                "ZoneId": "cn-hangzhou-h",
                "DBInstanceClass": "rds.mysql.s3.large",
                "CreateTime": "2020-06-17T09:03:57Z",
                "VSwitchId": "vsw-bpxxxxx",
                "PayType": "Prepaid",
                "LockMode": "Unlock",
                "GuardDBInstanceId": "rm-m5xxxxx",
                "InsId": 1,
                "VpcId": "vpc-bpxxxxx",
                "VpcName": "test-huadong",
                "ConnectionMode": "Standard",
                "VpcCloudInstanceId": "rm-bpxxxxx-1",
                "RegionId": "cn-hangzhou",
                "ExpireTime": "2021-06-17T16:00:00Z"
            }
        ]
    }
}

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.