1. 接口描述
接口请求域名： cdb.tencentcloudapi.com 。
本接口(DescribeDBInstances)用于查询云数据库实例列表，支持通过项目 ID、实例 ID、访问地址、实例状态等过滤条件来筛选实例。支持查询主实例、灾备实例和只读实例信息列表。
默认接口请求频率限制：100次/秒。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：DescribeDBInstances。 |
| Version | 是 | String | 公共参数，本接口取值：2017-03-20。 |
| Region | 是 | String | 公共参数，详见产品支持的 地域列表。 |
| ProjectId | 否 | Integer | 项目 ID。 示例值：0 |
| InstanceTypes.N | 否 | Array of Integer | 实例类型，可取值：1 - 主实例，2 - 灾备实例，3 - 只读实例。 示例值：1 |
| Vips.N | 否 | Array of String | 实例的内网 IP 地址。 示例值："" |
| Status.N | 否 | Array of Integer | 实例状态，可取值： 0 - 创建中 1 - 运行中 4 - 正在进行隔离操作 5 - 已隔离（可在回收站恢复开机） 示例值：1 |
| Offset | 否 | Integer | 偏移量，默认值为 0。 示例值：0 |
| Limit | 否 | Integer | 单次请求返回的数量，默认值为 20，最大值为 2000。 示例值：1 |
| SecurityGroupId | 否 | String | 安全组 ID。当使用安全组 ID 为过滤条件时，需指定 WithSecurityGroup 参数为 1。 示例值："" |
| PayTypes.N | 否 | Array of Integer | 付费类型，可取值：0 - 包年包月，1 - 小时计费。 示例值：1 |
| InstanceNames.N | 否 | Array of String | 实例名称。 示例值："" |
| TaskStatus.N | 否 | Array of Integer | 实例任务状态，可能取值： 0 - 没有任务 1 - 升级中 2 - 数据导入中 3 - 开放Slave中 4 - 外网访问开通中 5 - 批量操作执行中 6 - 回档中 7 - 外网访问关闭中 8 - 密码修改中 9 - 实例名修改中 10 - 重启中 12 - 自建迁移中 13 - 删除库表中 14 - 灾备实例创建同步中 15 - 升级待切换 16 - 升级切换中 17 - 升级切换完成 19 - 参数设置待执行 示例值：0 |
| EngineVersions.N | 否 | Array of String | 实例数据库引擎版本，可能取值：5.1、5.5、5.6 和 5.7。 示例值："5.6" |
| VpcIds.N | 否 | Array of Integer | 私有网络的 ID。 示例值：0 |
| ZoneIds.N | 否 | Array of Integer | 可用区的 ID。 示例值：720001 |
| SubnetIds.N | 否 | Array of Integer | 子网 ID。 示例值：0 |
| CdbErrors.N | 否 | Array of Integer | 是否锁定标记，可选值：0 - 不锁定，1 - 锁定，默认为0。 示例值：0 |
| OrderBy | 否 | String | 返回结果集排序的字段，目前支持："InstanceId"，"InstanceName"，"CreateTime"，"DeadlineTime"。 示例值："" |
| OrderDirection | 否 | String | 返回结果集排序方式，目前支持："ASC" 或者 "DESC"。 示例值："DESC" |
| WithSecurityGroup | 否 | Integer | 是否以安全组 ID 为过滤条件。 示例值：0 |
| WithExCluster | 否 | Integer | 是否包含独享集群详细信息，可取值：0 - 不包含，1 - 包含。 示例值：0 |
| ExClusterId | 否 | String | 独享集群 ID。 示例值："" |
| InstanceIds.N | 否 | Array of String | 实例 ID。 示例值：["cdb-70zdmgg1\r\n"] |
| InitFlag | 否 | Integer | 初始化标记，可取值：0 - 未初始化，1 - 初始化。 示例值：0 |
| WithDr | 否 | Integer | 是否包含灾备关系对应的实例，可取值：0 - 不包含，1 - 包含。默认取值为1。如果拉取主实例，则灾备关系的数据在DrInfo字段中， 如果拉取灾备实例， 则灾备关系的数据在MasterInfo字段中。灾备关系中只包含部分基本的数据，详细的数据需要自行调接口拉取。 示例值：0 |
| WithRo | 否 | Integer | 是否包含只读实例，可取值：0 - 不包含，1 - 包含。默认取值为1。 示例值：0 |
| WithMaster | 否 | Integer | 是否包含主实例，可取值：0 - 不包含，1 - 包含。默认取值为1。 示例值：0 |
| DeployGroupIds.N | 否 | Array of String | 置放群组ID列表。 示例值："" |
| TagKeysForSearch.N | 否 | Array of String | 是否以标签键为过滤条件。 示例值：[""] |
| CageIds.N | 否 | Array of String | 金融围拢 ID 。 示例值：["cage-test"] |
| TagValues.N | 否 | Array of String | 标签值 示例值：["a12","v22"] |
| UniqueVpcIds.N | 否 | Array of String | 私有网络字符型vpcId 示例值：["vpc-saxa","vpc-sss"] |
| UniqSubnetIds.N | 否 | Array of String | 私有网络字符型subnetId 示例值：["subnet-kkai"] |
| Tags.N | 否 | Array of Tag | 标签键值 |
| ProxyVips.N | 否 | Array of String | 数据库代理 IP 。 示例值：["127.0.0.1"] |
| ProxyIds.N | 否 | Array of String | 数据库代理 ID 。 示例值：["proxynode-xxxx"] |
| EngineTypes.N | 否 | Array of String | 数据库引擎类型。 示例值：["InnoDB"] |
| QueryClusterInfo | 否 | Boolean | 是否获取集群版实例节点信息，可填：true或false |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| TotalCount | Integer | 符合查询条件的实例总数。 示例值：1 |
| Items | Array of InstanceInfo | 实例详细信息列表。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 查询实例列表
查询实例列表
输入示例
POST / HTTP/1.1
Host: cdb.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeDBInstances
<公共请求参数>
{
"InstanceIds": [
"cdb-70zdmgg1"
]
}输出示例
{
"Response": {
"TotalCount": 1,
"RequestId": "97939db3-ef94-4a60-9b64-2a1f4e2f1ea3",
"Items": [
{
"WanStatus": 0,
"Zone": "100001",
"WanPort": 0,
"DiskType": "test",
"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": "test",
"Region": "ap-guangzhou",
"Zone": "ap-guangzhou-1"
},
"First": {
"Vport": 0,
"Vip": "test",
"Region": "ap-guangzhou",
"Zone": "ap-guangzhou-1"
}
},
"InstanceId": "cdn-abc",
"PhysicalId": "test",
"Volume": 50,
"AutoRenew": 0,
"ProtectMode": 0,
"CdbError": 0,
"DeviceClass": "test",
"MasterInfo": {
"Status": 0,
"VpcId": 0,
"Zone": "100001",
"ExClusterName": "test",
"InstanceId": "test",
"ResourceId": "test",
"Region": "ap-guangzhou",
"RegionId": 0,
"ZoneId": 0,
"Volume": 0,
"DeviceType": "test",
"Memory": 0,
"SubnetId": 0,
"Qps": 0,
"TaskStatus": 0,
"InstanceName": "test",
"InstanceType": 0,
"ExClusterId": "test"
},
"DeployGroupId": "test",
"InstanceNodes": 2,
"RoGroups": [
{
"RoOfflineDelay": 0,
"RoGroupMode": "test",
"RoGroupZone": "test",
"MinRoInGroup": 1,
"DelayReplicationTime": 0,
"RoGroupId": "test",
"RoMaxDelayTime": 1,
"RoGroupName": "test",
"Weight": 0,
"UniqVpcId": "test",
"RoInstances": [
{
"Zone": "test",
"MasterInstanceId": "test",
"Memory": 1000,
"Status": 1,
"VpcId": 511512,
"InstanceId": "test",
"Volume": 50,
"OfflineTime": "test",
"SubnetId": 115839,
"HourFeeStatus": 1,
"RoStatus": "test",
"Region": "test",
"DeadlineTime": "test",
"TaskStatus": 0,
"DeviceType": "test",
"EngineVersion": "test",
"InstanceName": "test",
"Weight": 0,
"PayType": 1,
"InstanceType": 3,
"Vip": "test",
"Qps": 1000,
"Vport": 3306
}
],
"Vip": "test",
"UniqSubnetId": "test",
"RoGroupRegion": "test",
"Vport": 3306,
"WeightMode": "test"
},
{
"RoOfflineDelay": 0,
"RoGroupMode": "test",
"RoGroupZone": "test",
"MinRoInGroup": 1,
"DelayReplicationTime": 0,
"RoGroupId": "test",
"RoMaxDelayTime": 1,
"RoGroupName": "test",
"UniqVpcId": "test",
"Weight": 0,
"RoInstances": [
{
"Zone": "test",
"MasterInstanceId": "test",
"Memory": 1000,
"Status": 1,
"VpcId": 511512,
"InstanceId": "test",
"Volume": 25,
"OfflineTime": "test",
"SubnetId": 115839,
"HourFeeStatus": 1,
"RoStatus": "test",
"Region": "test",
"DeadlineTime": "test",
"TaskStatus": 0,
"DeviceType": "test",
"EngineVersion": "test",
"InstanceName": "test",
"Weight": 0,
"PayType": 1,
"InstanceType": 3,
"Vip": "test",
"Qps": 1000,
"Vport": 3306
}
],
"Vip": "test",
"UniqSubnetId": "test",
"RoGroupRegion": "test",
"Vport": 3306,
"WeightMode": "test"
}
],
"ProjectId": 0,
"DeadlineTime": "2020-09-22 00:00:00",
"DeployMode": 0,
"TaskStatus": 0,
"SubnetId": 115839,
"DeviceType": "test",
"EngineVersion": "test",
"MaxDelayTime": 0,
"InstanceName": "test",
"Cpu": 8,
"DrInfo": [
{
"Status": 0,
"Zone": "test",
"InstanceId": "test",
"Region": "test",
"SyncStatus": 0,
"InstanceName": "test",
"InstanceType": 0
}
],
"UniqVpcId": "test",
"WanDomain": "test",
"InitFlag": 1,
"PayType": 1,
"InstanceType": 1,
"Vip": "test",
"UniqSubnetId": "test",
"Region": "test",
"Qps": 0,
"Vport": 3306,
"TagList": [
{
"TagKey": "test",
"TagValue": "test"
}
],
"CreateTime": "test",
"ZoneId": 720001,
"ZoneName": "test"
}
]
}
}5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| AuthFailure | CAM签名/鉴权错误。 |
| CdbError | 后端错误或者流程错误。 |
| InternalError.CdbError | 系统错误。 |
| InternalError.DBOperationError | 数据库操作失败。 |
| InternalError.DatabaseAccessError | 数据库内部错误。 |
| InternalError.DesError | 系统内部错误。 |
| InternalError.InternalHttpServerError | 请求执行异常。 |
| InternalError.InternalServiceErrorErr | 访问内部服务错误。 |
| InternalError.UndefinedError | 未知错误。 |
| InternalError.UnknownError | 未知错误。 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.ExceptionParam | 异常参数。 |
| InvalidParameter.InstanceNotFound | 实例不存在。 |
| InvalidParameterValue.DataConvertError | 数据转换失败。 |
| InvalidParameterValue.InvalidParameterValueError | 参数值无效。 |
| OperationDenied.UserHasNoStrategy | 用户没有该策略权限。 |
| OperationDenied.WrongStatus | 后端任务状态非法。 |
| UnsupportedOperation | 操作不支持。 |
