Domain name for API request: cdb.intl.tencentcloudapi.com.
This API is used to query the list of TencentDB for MySQL instances. It supports filtering instances by conditions such as project ID, instance ID, access address, and instance status. It also supports querying the list of information about primary instances, disaster recovery instances, and read-only instances.
This API is used to return the availability zone (AZ) status during purchase, which does not change along with the proactive HA switch. If you want to know the AZ status in real time, query through the DescribeDBInstanceConfig API.
A maximum of 100 requests can be initiated per second for this API.
The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| Action | Yes | String | Common Params. The value used for this API: DescribeDBInstances. |
| Version | Yes | String | Common Params. The value used for this API: 2017-03-20. |
| Region | Yes | String | Common Params. For more information, please see the list of regions supported by the product. |
| ProjectId | No | Integer | Project ID. |
| InstanceTypes.N | No | Array of Integer | Instance type. Valid values: 1 - Primary instance, 2 - Disaster recovery instance, 3 - Read-only instance. |
| Vips.N | No | Array of String | Private IP address of the instance. |
| Status.N | No | Array of Integer | Instance status. Valid values: |
| Offset | No | Integer | Offset. Default value is 0. |
| Limit | No | Integer | Number of items returned per request. Default value: 20. Maximum value: 2000. |
| SecurityGroupId | No | String | Security group ID. When using security group ID as the filter condition, the WithSecurityGroup parameter needs to be specified as 1. |
| PayTypes.N | No | Array of Integer | Payment type. Valid values: 0 - yearly/monthly subscription; 1 - bill by hour. |
| InstanceNames.N | No | Array of String | Instance name. |
| TaskStatus.N | No | Array of Integer | Instance task status, possible values: |
| EngineVersions.N | No | Array of String | Database engine version of the instance. Possible values: 5.1, 5.5, 5.6, and 5.7. |
| VpcIds.N | No | Array of Integer | VPC ID. |
| ZoneIds.N | No | Array of Integer | Availability zone ID. |
| SubnetIds.N | No | Array of Integer | Subnet ID. |
| CdbErrors.N | No | Array of Integer | Whether to set the lock flag. Available values: 0 - not lock, 1 - lock. Default is 0. |
| OrderBy | No | String | Sorting field of the returned result set. Currently supports: "instanceId", "instanceName", "createTime", and "deadlineTime". |
| OrderDirection | No | String | Sorting method of the returned result set. Valid values: "ASC" - ascending order; "DESC" - descending order. The default is "DESC". |
| WithSecurityGroup | No | Integer | Whether to use security group ID as the filter condition. |
| WithExCluster | No | Integer | Whether the exclusive cluster detail is included. Value range: 0 - not contained, 1 - contained. |
| ExClusterId | No | String | Dedicated cluster ID. |
| InstanceIds.N | No | Array of String | Instance ID. |
| InitFlag | No | Integer | Initialization flag. Valid values: 0 - uninitialized, 1 - initialized. |
| WithDr | No | Integer | Whether the corresponding instance in the disaster recovery relationship is included. Valid values: 0 - excluding, 1 - included. Default value: 1. If pulling the primary instance, the data of the disaster recovery relationship is in the DrInfo field. If pulling the disaster recovery instance, the data of the disaster recovery relationship is in the MasterInfo field. The disaster recovery relationship only contains partial basic data. Detailed data must be pulled manually via the interface. |
| WithRo | No | Integer | Whether it contains read-only instances. Valid values: 0 - does not include, 1 - includes. Default value is 1. |
| WithMaster | No | Integer | Whether the primary instance is included. Valid values: 0 - does not include, 1 - includes. Default value is 1. |
| DeployGroupIds.N | No | Array of String | Placement group ID list. |
| TagKeysForSearch.N | No | Array of String | Filter by tag key. |
| CageIds.N | No | Array of String | Financial Enclosure ID. |
| TagValues.N | No | Array of String | Tag value |
| UniqueVpcIds.N | No | Array of String | Character type VPC ID |
| UniqSubnetIds.N | No | Array of String | VPC character type subnetId |
| Tags.N | No | Array of Tag | Tag key value |
| ProxyVips.N | No | Array of String | Database proxy IP. |
| ProxyIds.N | No | Array of String | Database proxy ID. |
| EngineTypes.N | No | Array of String | Database engine type. Valid values: InnoDB, RocksDB. |
| QueryClusterInfo | No | Boolean | Whether to obtain the Cluster Edition instance node information. Valid values: true or false. The default value is false. |
| Parameter Name | Type | Description |
|---|---|---|
| TotalCount | Integer | Total number of eligible instances. |
| Items | Array of InstanceInfo | Instance detail list. |
| RequestId | String | The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem. |
This example shows you how to query the instance list.
POST / HTTP/1.1
Host: cdb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeDBInstances
<Common request parameters>
{
"InstanceIds": [
"cdb-70zdmgg1"
]
}
{
"Response": {
"TotalCount": 1,
"RequestId": "97939db3-ef94-4a60-9b64-2a1f4e2f1ea3",
"Items": [
{
"WanStatus": 0,
"Zone": "100001",
"WanPort": 0,
"DiskType": "CLOUD_SSD",
"RoVipInfo": {
"RoVport": 0,
"RoVpcId": 0,
"RoVipStatus": 0,
"RoVip": "192.168.1.1",
"RoSubnetId": 0
},
"Memory": 1000,
"EngineType": "InnoDB",
"Status": 1,
"VpcId": 511512,
"SlaveInfo": {
"Second": {
"Vport": 0,
"Vip": "172.1.1.1",
"Region": "ap-guangzhou",
"Zone": "ap-guangzhou-1"
},
"First": {
"Vport": 0,
"Vip": "17.1.1.1",
"Region": "ap-guangzhou",
"Zone": "ap-guangzhou-1"
}
},
"InstanceId": "cdn-ahend",
"PhysicalId": "136527",
"Volume": 50,
"AutoRenew": 0,
"ProtectMode": 0,
"CdbError": 0,
"DeviceClass": "20",
"MasterInfo": {
"Status": 1,
"VpcId": 0,
"Zone": "100001",
"ExClusterName": "andy",
"InstanceId": "cdb-hsyhend",
"ResourceId": "",
"Region": "ap-guangzhou",
"RegionId": 0,
"ZoneId": 0,
"Volume": 0,
"DeviceType": "UNIVERSAL",
"Memory": 0,
"SubnetId": 0,
"Qps": 0,
"TaskStatus": 0,
"InstanceName": "cdb342",
"InstanceType": 0,
"ExClusterId": "cdb-3ho6jddd"
},
"DeployGroupId": "ps-7t11vrwf",
"InstanceNodes": 2,
"RoGroups": [
{
"RoOfflineDelay": 0,
"RoGroupMode": "alone",
"RoGroupZone": "800003",
"MinRoInGroup": 1,
"DelayReplicationTime": 0,
"RoGroupId": "cdbrg-92zkeaq2",
"RoMaxDelayTime": 1,
"RoGroupName": "cdbro2",
"Weight": 0,
"UniqVpcId": "vpc-ja6ts123",
"RoInstances": [
{
"Zone": "ap-guangzhou-3",
"MasterInstanceId": "cdb-fapcrp1q",
"ReplicationStatus": "success",
"Memory": 1000,
"Status": 1,
"VpcId": 511512,
"InstanceId": "cdb-hendhs",
"Volume": 50,
"OfflineTime": "2024-09-09 16:40:31",
"SubnetId": 115839,
"HourFeeStatus": 1,
"RoStatus": "online",
"Region": "ap-guangzhou",
"DeadlineTime": "2024-12-29 08:37:33",
"TaskStatus": 0,
"DeviceType": "UNIVERSAL",
"EngineVersion": "5.7",
"InstanceName": "cdbro732",
"Weight": 0,
"PayType": 1,
"InstanceType": 3,
"Vip": "127.0.0.1",
"Qps": 1000,
"Vport": 3306
}
],
"Vip": "10.89.90.66",
"UniqSubnetId": "subnet-njh2bc99",
"RoGroupRegion": "ap-guangzhou",
"Vport": 3306,
"WeightMode": "system"
},
{
"RoOfflineDelay": 0,
"RoGroupMode": "alone",
"RoGroupZone": "ap-guangzhou",
"MinRoInGroup": 1,
"DelayReplicationTime": 0,
"RoGroupId": "cdbrg-92zkeaq4",
"RoMaxDelayTime": 1,
"RoGroupName": "andy6",
"UniqVpcId": "vpc-ja6ts453",
"Weight": 0,
"RoInstances": [
{
"Zone": "ap-guangzhou-4",
"MasterInstanceId": "cdb-fapcrp12",
"ReplicationStatus": "success",
"Memory": 1000,
"Status": 1,
"VpcId": 511512,
"InstanceId": "cdbro-c1nl9rpv",
"Volume": 25,
"OfflineTime": "2024-09-09 16:40:30",
"SubnetId": 115839,
"HourFeeStatus": 1,
"RoStatus": "online",
"Region": "ap-guangzhou",
"DeadlineTime": "2024-12-29 08:37:33",
"TaskStatus": 0,
"DeviceType": "UNIVERSAL",
"EngineVersion": "5.7",
"InstanceName": "cdbro7",
"Weight": 0,
"PayType": 1,
"InstanceType": 3,
"Vip": "127.0.0.1",
"Qps": 1000,
"Vport": 3306
}
],
"Vip": "12.1.1.1",
"UniqSubnetId": "subnet-njh2bc11",
"RoGroupRegion": "ap-guangzhou",
"Vport": 3306,
"WeightMode": "system"
}
],
"ProjectId": 0,
"DeadlineTime": "2020-09-22 00:00:00",
"DeployMode": 0,
"TaskStatus": 0,
"SubnetId": 115839,
"DeviceType": "EXCLUSIVE",
"EngineVersion": "5.7",
"MaxDelayTime": 0,
"InstanceName": "cdbandy",
"Cpu": 8,
"CpuModel": "Hygon",
"DrInfo": [
{
"Status": 0,
"Zone": "ap-beijing-3",
"InstanceId": "cdb-hegns",
"Region": "ap-beijing",
"SyncStatus": 0,
"InstanceName": "andydr",
"InstanceType": 0
}
],
"UniqVpcId": "vpc-5v8wn9m1",
"WanDomain": "gz-cdb-******.sql.tencentcdb.com",
"InitFlag": 1,
"PayType": 1,
"InstanceType": 1,
"Vip": "13.1.1.1",
"UniqSubnetId": "subnet-1typ0s7d",
"Region": "ap-beijing",
"Qps": 0,
"Vport": 3306,
"TagList": [
{
"TagKey": "name",
"TagValue": "andy"
}
],
"CreateTime": "2023-08-29 08:37:33",
"ZoneId": 720001,
"ZoneName": "Beijing Zone 3"
}
]
}
}
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.
| Error Code | Description |
|---|---|
| AuthFailure | CAM signature/authentication error. |
| CdbError | Backend or process error. |
| InternalError.CdbError | System error. |
| InternalError.DBOperationError | Database operation failed. |
| InternalError.DatabaseAccessError | Internal database error. |
| InternalError.DesError | Internal system error. |
| InternalError.InternalHttpServerError | An exception occurred while executing the request. |
| InternalError.InternalServiceErrorErr | An error occurred while accessing internal service. |
| InternalError.UndefinedError | Unknown error |
| InternalError.UnknownError | Unknown error |
| InvalidParameter | Parameter error. |
| InvalidParameter.ExceptionParam | Parameter exception. |
| InvalidParameter.InstanceNotFound | The instance does not exist. |
| InvalidParameterValue.DataConvertError | Data conversion failed. |
| InvalidParameterValue.InvalidParameterValueError | Invalid parameter value |
| OperationDenied.UserHasNoStrategy | This account is not authorized to access the requested resource. |
| OperationDenied.WrongStatus | The backend task status is invalid. |
| UnsupportedOperation | Unsupported operation. |
フィードバック