文档数据库 MongoDB 版
文档数据库 MongoDB 版
文档指南
请输入
- 文档首页
文档数据库 MongoDB 版API 参考实例管理DescribeDBInstances
复制全文
下载 pdfDescribeDBInstances
文档反馈
问问助手调用 DescribeDBInstances 接口查询 MongoDB 实例的基本信息。
请求类型
同步请求。
注意事项
说明
若您不传入任何参数，默认返回当前账号下所有 MongoDB 实例的列表信息。
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
ZoneId String 可选 示例值：cn-beijing-a
可用区 ID。
说明
InstanceId String 可选 示例值：mongo-replica-e405f8e2f8e2
实例 ID。
InstanceName String 可选 示例值：test_mongo
实例名称。
InstanceType String 可选 示例值：ReplicaSet
MongoDB 的实例类型，取值范围如下：
- ReplicaSet：副本集。
- ShardedCluster：分片集群 。
说明
若该参数留空，默认返回当前账号下所有类型的 MongoDB 实例列表。
InstanceStatus String 可选 示例值：Running
DBEngine String 可选 示例值：MongoDB
数据库引擎。取值固定为 MongoDB。
DBEngineVersion String 可选 示例值：MongoDB_5_0
数据库引擎版本，取值范围如下：
- MongoDB_4_0：MongoDB 4.0 版本。
- MongoDB_4_2：MongoDB 4.2 版本。
- MongoDB_4_4：MongoDB 4.4 版本。
- MongoDB_5_0：MongoDB 5.0 版本。
- MongoDB_6_0：MongoDB 6.0 版本。
- MongoDB_7_0：MongoDB 7.0 版本。
- MongoDB_8_0：MongoDB 8.0 版本。
- MongoDB_8_3：MongoDB 8.3 版本。
说明
CreateStartTime String 可选 示例值：2022-03-15T03:50:00Z
实例创建的开始时间。格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。
CreateEndTime String 可选 示例值：2022-03-15T04:00:00Z
实例创建的结束时间。格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。
UpdateStartTime String 可选 示例值：2022-03-19T03:45:00Z
实例更新的开始时间。格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。
UpdateEndTime String 可选 示例值：2022-03-19T04:00:00Z
实例更新的结束时间。格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。
VpcId String 可选 示例值：vpc-2743n1ihbxla87fap8tap8tap
实例所属的私有网络（VPC）ID。
说明
PageNumber Integer 可选 示例值：1
实例信息列表的页码，默认值为 1。取值为不超过 Integer 数据类型的最大值，起始值为 1。
PageSize Integer 可选 示例值：10
每页记录数，取值范围为 1~1000，默认值为 10。
ProjectName String 可选 示例值：default
指定实例所属的项目名称。
说明
若该参数留空，表示不使用实例的项目名称条件进行筛选。
FilterByTags Object[] 可选 示例值：
用于查询筛选的标签键值对数组。
说明
- 若该参数留空，表示不使用标签条件进行筛选。
- 若同时传入多个标签进行筛选时，多个标签筛选条件之间为或关系。
Key String 必选 示例值：instancetype
用于查询筛选的标签键。
说明
如需使用标签对实例进行查询筛选，标签键（Key）必填。
Values String[] 可选 示例值：["replica"]
用于查询筛选的标签键所对应的标签值。
说明
若该参数留空，表示不对标签值作限制，会筛选所有绑定了指定标签键的实例。
TagFilters Object[] 可选 示例值：
该字段已废弃不再使用。建议通过 FilterByTags 字段进行标签筛选。
Key String 必选 示例值：instancetype
该字段已废弃不再使用。建议通过 FilterByTags 字段进行标签筛选。
Value String 可选 示例值：replica
该字段已废弃不再使用。建议通过 FilterByTags 字段进行标签筛选。
返回参数
Total Integer 示例值：1
所有实例的数量。
DBInstances Object[] 示例值：
实例基本信息列表。
AutoRenew Boolean 示例值：false
包年包月实例是否开启自动续费。取值范围如下：
- false：未开启。
- true：已开启。
说明
仅包年包月实例支持返回该参数。
ChargeStatus String 示例值：Normal
实例计费状态，取值范围如下：
- Normal：正常。
- WaitingPaid：等待支付。
- ChangingPayType：计费变更中。
- Renewing：续费中。
- Overdue：已到期。
- Owing：欠费中。
- Unsubscribing：退订中。
ChargeType String 示例值：Prepaid
实例计费类型，取值范围如下：
- Prepaid：包年包月（也称预付费）。
- PostPaid：按量计费（也称后付费）。
ClosedTime String 示例值：2022-03-19T04:00:00Z
计划关停时间（UTC）。
说明
仅包年包月实例支持返回该参数。
ConfigServers Object[] 示例值：-
ConfigServers 的信息列表。
说明
仅分片集群实例支持返回该参数。
ConfigServerNodeId String 示例值：mongo-shard-3d714182****-config-0
ConfigServer 的节点 ID。
NodeRole String 示例值：Primary
节点角色，取值范围如下：
- Primary：主节点。
- Secondary：从节点。
- Hidden：隐藏节点。
NodeStatus String 示例值：Running
节点状态。
TotalMemoryGB Double 示例值：4
总内存。单位：GiB。
TotalvCPU Double 示例值：2
总核数。
UsedMemoryGB Double 示例值：0.33296966552734375
已用内存。单位：GiB。
UsedvCPU Double 示例值：0.004654006
已用核数。
ZoneId String 示例值：cn-beijing-a
当前节点所属的可用区 ID。
说明
ConfigServersId String 示例值：mongo-shard-fa8cd21d****-config
ConfigServer 的 ID。
说明
仅分片集群实例支持返回该参数。
CreateTime String 示例值：2022-03-15T03:57:15Z
实例创建时间（UTC）。
DBEngineVersion String 示例值：MongoDB_5_0
DBEngineVersionStr String 示例值：MongoDB 5.0
数据库引擎版本的字符串。
ExpiredTime String 示例值：22022-03-19T03:45:28Z
实例到期时间（UTC）。
说明
仅包年包月实例支持返回该参数。
InstanceId String 示例值：mongo-replica-9b3f8fb9****
实例 ID。
InstanceName String 示例值：test-mongo
实例名称。
InstanceStatus String 示例值：Running
InstanceType String 示例值：ReplicaSet
MongoDB 的实例类型，取值范围如下：
- ReplicaSet：副本集。
- ShardedCluster：分片集群 。
MongosId String 示例值：mongo-shard-011d2479****
Mongos 的 ID。
说明
仅分片集群实例支持返回该参数。
ReclaimTime String 示例值：2022-03-26T03:45:28Z
实例的计划回收时间（UTC）。
说明
仅包年包月实例支持返回该参数。
Shards Object[] 示例值：-
Shards 的信息列表。
说明
仅分片集群实例支持返回该参数。
Nodes Object[]
Shard分片中各节点的信息列表。
NodeDelayTime Integer 示例值：0
主从延迟时间。单位：毫秒（ms）。
NodeId String 示例值：mongo-shard-011d2479****-s1-0
节点 ID。
NodeRole String 示例值：Primary
节点角色，取值范围如下：
- Primary：主节点。
- Secondary：从节点。
- Hidden：隐藏节点。
- ReadOnly：只读节点。
- 说明
- 仅副本集实例和分片集群实例的 Shard 分片节点支持使用只读节点。
- 仅当实例中存在只读节点时，才会返回只读节点 ReadOnly 的相关信息。更多关于只读节点的信息，请参见 MongoDB 只读节点。
NodeSpec String 示例值：mongo.shard.2c4g
节点规格。
NodeStatus String 示例值：Running
节点状态。
TotalMemoryGB Double 示例值：4
总内存。单位：GiB。
TotalStorageGB Double 示例值：20
该节点的总存储空间。单位：GiB。
TotalvCPU Double 示例值：2
总核数。
UsedMemoryGB Double 示例值：0.4655952453613281
已用内存。单位：GiB。
UsedStorageGB Double 示例值：0.9955019280314445
该节点已用的存储空间。单位：GiB。
UsedvCPU Double 示例值：0.003100326
已用核数。
ZoneId String 示例值：cn-beijing-a
当前节点所属的可用区 ID。
说明
ShardId String 示例值：mongo-shard-011d2479****-s0
Shard 节点的 ID。
说明
仅分片集群实例支持返回该参数。
ProjectName String 示例值：default
实例所属的项目名称。
SubnetId String 示例值：subnet-2743n265pa8zk7fap8st3****
实例所属的子网 ID。
Tags Object[] 示例值：-
实例已绑定的标签信息。
说明
仅已绑定了标签的实例才会返回该参数。
Key String 示例值：instancetype
当前实例所绑定标签的标签键。
Value String 示例值：replica
当前实例所绑定标签的标签值。
UpdateTime String 示例值：2022-03-19T03:45:28Z
实例的更新时间（UTC）。
VpcId String 示例值：vpc-3tfam26vmy3v****
实例所属的私有网络 ID。
ZoneId String 示例值：cn-beijing-a
实例所属的可用区 ID。
说明
StorageType String 示例值：LocalSSD
实例的存储类型。当前仅支持本地 SSD 盘（即 LocalSSD）存储。
PrivateEndpoint String 示例值：mongodb://:@mongoshard3d714182\*\*\*\*0.mongodb.ivolces.com:3717,mongoshard3d714182\*\*\*\*1.mongodb.ivolces.com:3717,mongoshard3d714182\*\*\*\*2.mongodb.ivolces.com:3717/?authSource=admin&retryWrites=true
实例私网连接地址的字符串信息。
ReadOnlyNodeNumber Integer 示例值：3
实例中的只读节点数量。
说明
- 0 表示当前实例中未添加任何只读节点。
- 针对分片集群实例，该参数的取值表示实例中所有 Shard 分片里的只读节点总数。更多关于只读节点的功能介绍和使用限制，请参见 MongoDB 只读节点。
MongotInfos Object[]
Mongot 节点信息。
ShardId String 示例值：mongo-shard-011d2479****-s0
Shard 节点 ID。
说明
仅分片集群实例支持返回该参数。
NodeInfos Object[] 示例值：-
Mongot 节点的详细信息。
NodeId String 示例值：mongo-mongot-011d2479****-node-0
节点 ID。
ZoneId String 示例值：cn-beijing-a
节点所属的可用区 ID。
NodeSpec String
节点规格
UsedvCPU Double 示例值：0.00256789
节点已用核数。
TotalvCPU Double 示例值：2
节点总核数。
UsedMemoryGB Double 示例值： 0.33296966552734375
节点已用内存，单位 GiB。
TotalMemoryGB Double 示例值：4
节点总内存，单位 GiB。
UsedStorageGB Double 示例值：1.56789
节点已使用存储空间，单位 GiB。
TotalStorageGB Double 示例值：20
节点总存储空间，单位 GiB。
MongotEnable Boolean
是否开启 Mongot。
BackupVersion String
backup 版本
MaintenanceTime String
可维护时间段
MongoClusterVersion String
mgc 版本
示例
请求示例 1
通过 FilterByTags 字段筛选出按量计费分片集群实例。
POST https://mongodb.cn-beijing.volcengineapi.com/?Action=DescribeDBInstances&Version=2022-01-01 HTTP/1.1
Host: mongodb.cn-beijing.volcengineapi.com
Content-Type: application/json; charset=utf-8
X-Date: 20201103T104027Z
Authorization: HMAC-SHA256 Credential=AK****/20201103/cn-beijing/mongodb/request,SignedHeaders=content-type;host;x-date,Signature=****
{
"ZoneId":"cn-beijing-a",
"PageSize":20,
"PageNumber":1,
"FilterByTags":[
{
"Key":"instancetype",
"Value":[
"shard"
]
},
{
"Key":"chargetype",
"Value":[
"postpaid"
]
}
]
}
返回示例 1
按量计费分片集群实例的正常返回示例。
{
"ResponseMetadata": {
"RequestId": "202607221702535ABA4C2C163526D9DD26-41185e",
"Action": "DescribeDBInstances",
"Version": "2022-01-01",
"Service": "mongodb",
"Region": "cn-guilin-boe"
},
"Result": {
"DBInstances": [
{
"AutoRenew": false,
"BackupVersion": "25.12.2",
"ChargeStatus": "Normal",
"ChargeType": "PostPaid",
"ClosedTime": "",
"CreateTime": "2026-07-20T12:06:02Z",
"DBEngine": "MongoDB",
"DBEngineVersion": "MongoDB_8_3",
"DBEngineVersionStr": "MongoDB 8.3",
"InstanceId": "mongo-replica-49d441f6387f",
"InstanceName": "mengyuantest-83",
"InstanceStatus": "Running",
"InstanceType": "ReplicaSet",
"MongoClusterVersion": "6.6.1",
"MongotEnable": true,
"MongotInfos": [
{
"NodeInfos": [
{
"NodeId": "mongo-replica-49d441f6387f-mongot-cn-guilin-c-0",
"NodeSpec": "mongo.mongot.2c4g",
"TotalMemoryGB": 4,
"TotalStorageGB": 200,
"TotalvCPU": 2,
"UsedMemoryGB": 0.9510612487792969,
"UsedStorageGB": 57.727448959834874,
"UsedvCPU": 0.16433774006423757,
"ZoneId": "cn-guilin-c"
},
{
"NodeId": "mongo-replica-49d441f6387f-mongot-cn-guilin-c-1",
"NodeSpec": "mongo.mongot.2c4g",
"TotalMemoryGB": 4,
"TotalStorageGB": 200,
"TotalvCPU": 2,
"UsedMemoryGB": 1.0714073181152344,
"UsedStorageGB": 57.70432886015624,
"UsedvCPU": 0.1782868634719083,
"ZoneId": "cn-guilin-c"
}
],
"ShardId": "mongo-replica-49d441f6387f"
}
],
"Nodes": [
{
"Cluster": "mix-azc-database",
"NodeDelayTime": 0,
"NodeId": "mongo-replica-49d441f6387f-0",
"NodeRole": "Primary",
"NodeSpec": "mongo.2c4g",
"NodeStatus": "Running",
"TotalMemoryGB": 4,
"TotalStorageGB": 200,
"TotalvCPU": 2,
"UsedMemoryGB": 1.4146957397460938,
"UsedStorageGB": 1.5358618013560772,
"UsedvCPU": 0.02275546154096394,
"ZoneId": "cn-guilin-c"
},
{
"Cluster": "mix-azc-database",
"NodeDelayTime": 0,
"NodeId": "mongo-replica-49d441f6387f-1",
"NodeRole": "Secondary",
"NodeSpec": "mongo.2c4g",
"NodeStatus": "Running",
"TotalMemoryGB": 4,
"TotalStorageGB": 200,
"TotalvCPU": 2,
"UsedMemoryGB": 1.5751991271972656,
"UsedStorageGB": 1.507725021801889,
"UsedvCPU": 0.029590983440963087,
"ZoneId": "cn-guilin-c"
},
{
"Cluster": "mix-azc-database",
"NodeDelayTime": 0,
"NodeId": "mongo-replica-49d441f6387f-2",
"NodeRole": "Hidden",
"NodeSpec": "mongo.2c4g",
"NodeStatus": "Running",
"TotalMemoryGB": 4,
"TotalStorageGB": 200,
"TotalvCPU": 2,
"UsedMemoryGB": 1.5389442443847656,
"UsedStorageGB": 1.4735627947375178,
"UsedvCPU": 0.021694304222169156,
"ZoneId": "cn-guilin-c"
}
],
"PrivateEndpoint": "mongodb://\u003cuser\u003e:\u003cpassword\u003e@mongoreplica49d441f6387f0.mongodb-boe.ivolces.com:3717,mongoreplica49d441f6387f1.mongodb-boe.ivolces.com:3717/?authSource=admin\u0026replicaSet=rs-mongo-replica-49d441f6387f\u0026retryWrites=true",
"ProjectName": "default",
"ReadOnlyNodeNumber": 0,
"ReclaimTime": "",
"SpecType": "GENERAL",
"StorageType": "LocalSSD",
"SubnetId": "subnet-1el48uidyuku81jcpwich01b3",
"Tags": [
{
"Key": "sys:tag:createdBy",
"Value": "Root:2100001228"
}
],
"Tenant": "2100001228",
"UpdateTime": "2026-07-21T03:39:43Z",
"VpcId": "vpc-1elkrq4tg3ta81jcpwjx5j6s4",
"ZoneId": "cn-guilin-c"
}
],
"Total": 1
}
}
请求示例 2
通过 ChargeType 和 InstanceType 字段筛选出包年包月副本集实例。
POST https://mongodb.cn-beijing.volcengineapi.com/?Action=DescribeDBInstances&Version=2022-01-01 HTTP/1.1
Host: mongodb.cn-beijing.volcengineapi.com
Content-Type: application/json; charset=utf-8
X-Date: 20201103T104027Z
Authorization: HMAC-SHA256 Credential=AK****/20201103/cn-beijing/mongodb/request,SignedHeaders=content-type;host;x-date,Signature=****
{
"ZoneId":"cn-beijing-a",
"PageSize":20,
"PageNumber":1,
"ChargeType": "Prepaid",
"InstanceType": "ReplicaSet"
}
返回示例 2
包年包月副本集实例的正常返回示例。
{
"ResponseMetadata": {
"RequestId": "202607221711566B372AB2549B669A7E63-e1e085",
"Action": "DescribeDBInstances",
"Version": "2022-01-01",
"Service": "mongodb",
"Region": "cn-guilin-boe"
},
"Result": {
"DBInstances": [
{
"AutoRenew": false,
"BackupVersion": "25.12.2",
"ChargeStatus": "Normal",
"ChargeType": "Prepaid",
"ClosedTime": "2026-08-23T04:00:00Z",
"CreateTime": "2026-07-22T09:06:15Z",
"DBEngine": "MongoDB",
"DBEngineVersion": "MongoDB_8_3",
"DBEngineVersionStr": "MongoDB 8.3",
"ExpiredTime": "2026-08-22T15:59:59Z",
"InstanceId": "mongo-replica-fbe4cdd7de82",
"InstanceName": "lwy",
"InstanceStatus": "Running",
"InstanceType": "ReplicaSet",
"MongoClusterVersion": "6.6.1",
"MongotEnable": true,
"MongotInfos": [
{
"NodeInfos": [
{
"NodeId": "mongo-replica-fbe4cdd7de82-mongot-cn-guilin-c-0",
"NodeSpec": "mongo.mongot.2c4g",
"TotalMemoryGB": 4,
"TotalStorageGB": 100,
"TotalvCPU": 2,
"UsedMemoryGB": 0.22344589233398438,
"UsedStorageGB": 0.0003870902583003044,
"UsedvCPU": 0.02888356021528477,
"ZoneId": "cn-guilin-c"
},
{
"NodeId": "mongo-replica-fbe4cdd7de82-mongot-cn-guilin-c-1",
"NodeSpec": "mongo.mongot.2c4g",
"TotalMemoryGB": 4,
"TotalStorageGB": 100,
"TotalvCPU": 2,
"UsedMemoryGB": 0.2442169189453125,
"UsedStorageGB": 0.0003944067284464836,
"UsedvCPU": 0.028520820104053955,
"ZoneId": "cn-guilin-c"
}
],
"ShardId": "mongo-replica-fbe4cdd7de82"
}
],
"Nodes": [
{
"Cluster": "mix-azc-database",
"NodeDelayTime": 0,
"NodeId": "mongo-replica-fbe4cdd7de82-0",
"NodeRole": "Primary",
"NodeSpec": "mongo.2c4g",
"NodeStatus": "Running",
"TotalMemoryGB": 4,
"TotalStorageGB": 100,
"TotalvCPU": 2,
"UsedMemoryGB": 0.16679763793945312,
"UsedStorageGB": 0.19842858891934156,
"UsedvCPU": 0.020273914465585765,
"ZoneId": "cn-guilin-c"
},
{
"Cluster": "mix-azc-database",
"NodeDelayTime": 0,
"NodeId": "mongo-replica-fbe4cdd7de82-1",
"NodeRole": "Secondary",
"NodeSpec": "mongo.2c4g",
"NodeStatus": "Running",
"TotalMemoryGB": 4,
"TotalStorageGB": 100,
"TotalvCPU": 2,
"UsedMemoryGB": 0.17095184326171875,
"UsedStorageGB": 0.19854046124964952,
"UsedvCPU": 0.023445956565812377,
"ZoneId": "cn-guilin-c"
},
{
"Cluster": "mix-azc-database",
"NodeDelayTime": 0,
"NodeId": "mongo-replica-fbe4cdd7de82-2",
"NodeRole": "Hidden",
"NodeSpec": "mongo.2c4g",
"NodeStatus": "Running",
"TotalMemoryGB": 4,
"TotalStorageGB": 100,
"TotalvCPU": 2,
"UsedMemoryGB": 0.1707000732421875,
"UsedStorageGB": 0.19866509269922972,
"UsedvCPU": 0.020877794648836212,
"ZoneId": "cn-guilin-c"
}
],
"PrivateEndpoint": "mongodb://\u003cuser\u003e:\u003cpassword\u003e@mongoreplicafbe4cdd7de820.mongodb-boe.ivolces.com:3717,mongoreplicafbe4cdd7de821.mongodb-boe.ivolces.com:3717/?authSource=admin\u0026replicaSet=rs-mongo-replica-fbe4cdd7de82\u0026retryWrites=true",
"ProjectName": "default",
"ReadOnlyNodeNumber": 0,
"ReclaimTime": "2026-08-29T15:59:59Z",
"SpecType": "GENERAL",
"StorageType": "LocalSSD",
"SubnetId": "subnet-1el48uidyuku81jcpwich01b3",
"Tags": [
{
"Key": "sys:tag:createdBy",
"Value": "Root:2100001228"
}
],
"Tenant": "2100001228",
"UpdateTime": "2026-07-22T09:09:55Z",
"VpcId": "vpc-1elkrq4tg3ta81jcpwjx5j6s4",
"ZoneId": "cn-guilin-c"
}
],
"Total": 1
}
}
错误码
最近更新时间：2026.07.22 20:22:56
这个页面对您有帮助吗？
有用
有用
无用
无用