You can call the DescribeDBInstances operation to query one or more ApsaraDB RDS instances that meet the specified conditions.
You can use one of the following methods to check the response:
-
Method 1: Use the MaxResults parameter to specify the number of entries per page. Then, use the NextToken parameter to specify the token that is used to display the next page. The NextToken parameter is set to the value that is returned from the most recent call of the DescribeDBInstances operation for the NextToken parameter.Note The first time you call the DescribeDBInstances operation to perform a paged query, you need to only specify the MaxResults parameter. In this case, the operation returns the data of the first page and the value of the NextToken parameter.
- Method 2: Use the PageSize parameter to specify the number of entries per page. Then, use the PageNumber parameter to display the next page.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | DescribeDBInstances |
The operation that you want to perform. Set the value to DescribeDBInstances. |
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 by the instances. Valid values:
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 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 the instances have expired. Valid values:
|
SearchKey | String | No | rm-uf6w |
The keywords that are contained in the IDs or descriptions of the instances. |
DBInstanceId | String | No | rm-uf6wjk5xxxxxxx |
The ID of the instance. You can call the DescribeDBInstances operation to query the IDs of instances. |
DBInstanceType | String | No | Primary |
The role of the instances. Valid values:
By default, this operation returns the instances that assume any of the supported roles. |
RegionId | String | Yes | cn-hangzhou |
The ID of the region in which the instances reside. You can call the DescribeRegions operation to query the most recent region list. |
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: any non-zero positive integer. Default value: 1. |
InstanceNetworkType | String | No | Classic |
The network type of the instances. Valid values:
By default, this operation returns the instances that reside in any of the supported types of networks. |
VpcId | String | No | vpc-uf6f7l4fg90xxxxxxxxxx |
The ID of the virtual private cloud (VPC) to which the instances belong. |
VSwitchId | String | No | vsw-uf6adz52c2pxxxxxxxxxx |
The ID of the vSwitch. |
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 by the instances. |
PayType | String | No | Postpaid |
The billing method of the instances. Valid values:
|
ConnectionMode | String | No | Standard |
The connection mode of the instances. Valid values:
By default, this operation returns the instances that run in any of the supported connection modes. |
Tags | String | No | {"key1":"value1"} |
The tags that are added to the instance. 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 on which the instances reside in the specified dedicated cluster. |
InstanceLevel | Integer | No | 0 |
Specifies whether to return the RDS editions of the instances by using the Category parameter. Valid values:
|
ConnectionString | String | No | rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com |
The endpoint of the instance. You need to specify this parameter only when you want to query a single instance. |
NextToken | String | No | o7PORW5o2TJg********** |
The token that is used to display the next page. You must set this parameter to the value that is returned from the most recent call of the DescribeDBInstances operation for the NextToken parameter. If the returned entries are displayed on multiple pages, the next page can be displayed when you call this operation again with this parameter specified. |
MaxResults | Integer | No | 30 |
The number of entries to return on each page. Valid values: 1 to 100. Default value: 30. Note If you specify this parameter, the PageSize parameter and the PageNumber parameter are unavailable.
|
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
RequestId | String | 1AD222E9-E606-4A42-BF6D-8A4442913CEF |
The ID of the request. |
PageNumber | Integer | 1 |
The page number of the returned page. Note If you specify the MaxResults parameter or the NextToken parameter, only the value 1 is returned. You can ignore the value 1.
|
PageRecordCount | Integer | 10 |
The number of entries returned on the current page. |
TotalRecordCount | Integer | 100 |
The total number of entries returned. Note If you specify the MaxResults parameter or the NextToken parameter, only the number of entries on the current page is returned. You can ignore
the number.
|
Items | Array of DBInstance |
Details of the instances. |
|
DBInstance | |||
VpcId | String | vpc-uf6f7l4fg90xxxxxxx |
The ID of the VPC to which the instance belongs. |
DedicatedHostIdForLog | String | dh-bpxxxx |
The ID of the host on which the logger instance resides. |
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. |
PayType | String | Postpaid |
The billing method of the instance. Valid values:
|
DedicatedHostNameForLog | String | testlog |
The name of the host on which the logger instance resides. |
MutriORsignle | Boolean | true |
Indicates whether the multi-zone deployment method is used for the instance. Valid values: true and false. Note If the multi-zone deployment method is used for the instance, the zone ID of the instance
contains MAZ. Example:
cn-hangzhou-MAZ10(h,i) .
|
DedicatedHostGroupName | String | testhostgroup |
The name of the dedicated cluster to which the instance belongs. |
EngineVersion | String | 5.7 |
The version of the database engine that is run by the instance. |
DedicatedHostGroupId | String | dhg-7a9xxxxxxxx |
The ID of the dedicated cluster to which the instance belongs. |
VpcName | String | test-huadong |
The name of the VPC to which the instance belongs. |
DedicatedHostZoneIdForMaster | String | cn-hangzhou-c |
The ID of the zone to which the primary instance belongs. |
ConnectionString | String | rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com |
The endpoint of the instance. |
InstanceNetworkType | String | Classic |
The network type of the instance. Valid values:
|
MasterInstanceId | String | rm-uf6wjk5xxxxxxxxxx |
The ID of the primary instance. If the value of this parameter is null, the instance is a primary instance. |
ExpireTime | String | 2019-02-27T16:00:00Z |
The time at which the instance expires. 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.
|
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. |
GuardDBInstanceId | String | rm-uf64zsuxxxxxxxxxx |
The ID of the disaster recovery instance. This parameter is returned only when the instance is a primary instance and has a disaster recovery instance. |
DedicatedHostNameForMaster | String | testmaster |
The name of the host on which the primary instance resides. |
ZoneId | String | cn-hangzhou-a |
The ID of the zone to which the instance belongs. |
DBInstanceId | String | rm-uf6wjk5xxxxxxxxxx |
The ID of the instance. |
DedicatedHostIdForMaster | String | dh-bpxxxx |
The ID of the host on which the primary instance resides. |
TempDBInstanceId | String | rm-uf64zsuxxxxxxxxxx |
The ID of the temporary instance. This parameter is returned only when the instance is a primary instance and has a temporary instance. |
DBInstanceStorageType | String | ModuleList.4.ModuleCode |
The storage type of the instance. |
ConnectionMode | String | Standard |
The connection mode of the instance. Valid values:
|
LockMode | String | Unlock |
Indicates whether the instance is locked. Valid values:
|
VpcCloudInstanceId | String | rm-uf6wjk5xxxxxxx |
The ID of the instance. This parameter is returned only when the instance resides in a VPC. |
DedicatedHostZoneIdForSlave | String | cn-hangzhou-d |
The ID of the zone to which the secondary instance belongs. |
DedicatedHostZoneIdForLog | String | cn-hangzhou-b |
The zone ID of the host on which the logger instance resides. |
DedicatedHostNameForSlave | String | testslave |
The name of the host on which the secondary instance resides. |
DBInstanceDescription | String | testdatabase |
The description of the instance. |
DBInstanceNetType | String | Internet |
The type of network connection to the instance. Valid values:
|
DBInstanceType | String | Primary |
The role of the instance. Valid values:
|
LockReason | String | instance_expired |
The reason why the instance is locked. |
DBInstanceStatus | String | Running |
The status of the instance. For more information, see Instance state table. |
RegionId | String | cn-hangzhou |
The region ID of the instance. |
VSwitchId | String | vsw-uf6adz52c2pxxxxxxx |
The ID of the vSwitch. |
DedicatedHostIdForSlave | String | dh-bpxxxx |
The ID of the host on which the secondary instance resides. |
ResourceGroupId | String | rg-acfmyxxxxxxx |
The ID of the resource group to which the instance belongs. |
Category | String | Basic |
The RDS edition of the instance. Valid values:
|
Engine | String | MySQL |
The database engine that is run by the instance. |
DBInstanceClass | String | rds.mys2.small |
The instance type of the instance. For information, see Primary ApsaraDB RDS instance types. |
ReadOnlyDBInstanceIds | Array of ReadOnlyDBInstanceId |
An array that consists of the IDs of the read-only instances that are attached to the instance. This parameter is returned only when the instance is a primary instance and has read-only instances. |
|
ReadOnlyDBInstanceId | |||
DBInstanceId | String | rr-uf6wjk5xxxxxxx |
The ID of the read-only instance. |
DeletionProtection | Boolean | false |
Indicates whether the release protection feature is enabled for the read-only instance. Valid values:
|
NextToken | String | o7PORW5o2TJg********** |
The token that is used to display the next page. If the returned entries are displayed on multiple pages, the next page can be displayed when you call this operation again with the NextToken parameter specified. |
Examples
Sample requests
http(s)://rds.aliyuncs.com/?Action=DescribeDBInstances
&RegionId=cn-hangzhou
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<DescribeDBInstancesResponse>
<TotalRecordCount>1</TotalRecordCount>
<PageRecordCount>1</PageRecordCount>
<RequestId>A436D75C-30B0-1F34-8544-4B46F4407CC1</RequestId>
<NextToken>o7PORW5owHNg**********</NextToken>
<PageNumber>1</PageNumber>
<Items>
<DBInstance>
<EngineVersion>10.0</EngineVersion>
<ZoneId>cn-hangzhou-h</ZoneId>
<DBInstanceStatus>Running</DBInstanceStatus>
<ResourceGroupId>rg-acfmyiu********</ResourceGroupId>
<DBInstanceNetType>Intranet</DBInstanceNetType>
<DBInstanceClass>pg.n2.small.2c</DBInstanceClass>
<CreateTime>2021-02-02T09:14:48Z</CreateTime>
<VSwitchId>vsw-bp10aqj6o4lcl********</VSwitchId>
<TipsLevel>0</TipsLevel>
<DBInstanceType>Primary</DBInstanceType>
<PayType>Prepaid</PayType>
<LockMode>Unlock</LockMode>
<DeletionProtection>false</DeletionProtection>
<MutriORsignle>false</MutriORsignle>
<InstanceNetworkType>VPC</InstanceNetworkType>
<InsId>1</InsId>
<VpcId>vpc-bp1opxu1zkhn0********</VpcId>
<DBInstanceId>pgm-bp10re7n********</DBInstanceId>
<ConnectionMode>Standard</ConnectionMode>
<ReadOnlyDBInstanceIds>
</ReadOnlyDBInstanceIds>
<VpcCloudInstanceId>pgm-bp10re7n********</VpcCloudInstanceId>
<RegionId>cn-hangzhou</RegionId>
<ConnectionString>pgm-bp10re7n**************.pg.rds.aliyuncs.com</ConnectionString>
<ExpireTime>2021-02-03T09:14:48Z</ExpireTime>
<Engine>PostgreSQL</Engine>
</DBInstance>
</Items>
</DescribeDBInstancesResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"TotalRecordCount" : 1,
"PageRecordCount" : 1,
"RequestId" : "A436D75C-30B0-1F34-8544-4B46F4407CC1",
"NextToken" : "o7PORW5owHNg**********",
"PageNumber" : 1,
"Items" : {
"DBInstance" : [ {
"EngineVersion" : "10.0",
"ZoneId" : "cn-hangzhou-h",
"DBInstanceStatus" : "Running",
"ResourceGroupId" : "rg-acfmyiu********",
"DBInstanceNetType" : "Intranet",
"DBInstanceClass" : "pg.n2.small.2c",
"CreateTime" : "2021-02-02T09:14:48Z",
"VSwitchId" : "vsw-bp10aqj6o4lcl********",
"TipsLevel" : 0,
"DBInstanceType" : "Primary",
"PayType" : "Prepaid",
"LockMode" : "Unlock",
"DeletionProtection" : false,
"MutriORsignle" : false,
"InstanceNetworkType" : "VPC",
"InsId" : 1,
"VpcId" : "vpc-bp1opxu1zkhn0********",
"DBInstanceId" : "pgm-bp10re7n********",
"ConnectionMode" : "Standard",
"ReadOnlyDBInstanceIds" : {
"ReadOnlyDBInstanceId" : [ ]
},
"VpcCloudInstanceId" : "pgm-bp10re7n********",
"RegionId" : "cn-hangzhou",
"ConnectionString" : "pgm-bp10re7n**************.pg.rds.aliyuncs.com",
"ExpireTime" : "2021-02-03T09:14:48Z",
"Engine" : "PostgreSQL"
} ]
}
}
Error codes
HTTP status code | Error code | Error message | Description |
---|---|---|---|
400 | Invalid.NextToken | The parameter NextToken is invalid. | The error message returned because the value of the NextToken parameter is invalid. |
400 | InvalidDBInstanceType.ValueNotSupport | The specified parameter"DBInstanceType" is not valid. | The error message returned because the specified instance type is invalid. You must specify a valid instance type. |
For a list of error codes, visit the Error Center.