Query instances - API Reference| Alibaba Cloud Documentation Center

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.