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 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 is run on the instances. 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 status table.
Expired	String	No	True	Specifies whether to query the 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 match 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. 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 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 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, 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 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 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 that are added to the instances. 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.
ConnectionString	String	No	rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com	The endpoint of the single instance to query. You can query a specific instance based on an endpoint.

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: pay-as-you-go Prepaid: subscription
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. Specify the time in 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 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 locked upon expiration. LockByRestoration: The instance is locked before a rollback. LockByDiskQuota: The instance is automatically locked because its storage capacity is exhausted. Released: The instance is released. You cannot unlock an instance that is 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 based on which 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: ApsaraDB RDS automatically updates the minor engine version. Manual: A forcible update is triggered 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
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 more information, see Primary 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 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 is run on the instance.
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


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

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