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

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 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 are expired. Valid values:

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

The keywords that are parts 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 instances. 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 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 instances. Valid values:

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

The connection mode of the instances. 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 (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.
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.

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.

PageNumber Integer 1

The page number of the returned page.

Items Array of DBInstance

An array that consists of the instances returned and their information.

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

AutoUpgradeMinorVersion String Auto

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

  • Auto: When a new minor engine version is released, ApsaraDB RDS automatically updates the minor engine version of the instance.
  • Manual: When a new minor engine version is released, you must manually update the minor engine version of the instance based on your business requirements. ApsaraDB RDS automatically updates the current minor engine version of the instance only when the current minor engine version is phased out.
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 ID of the zone where the logger instance resides.

DedicatedHostZoneIdForMaster String cn-hangzhou-c

The ID of the zone where the primary instance resides.

DedicatedHostZoneIdForSlave String cn-hangzhou-d

The ID of the zone where the secondary instance resides.

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.

ReadOnlyDBInstanceIds Array of ReadOnlyDBInstanceId

An array that consists of the IDs of the read-only instances 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 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 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 ID of the zone where the instance resides.

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 codes Error message Description
400 InvalidDBInstanceType.ValueNotSupport The specified parameter"DBInstanceType" is not valid. The error message returned because the instance type that you specified is invalid. Specify a valid instance type.

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