You need to enable JavaScript to run this app.
导航
文档数据库 MongoDB 版
  • 文档首页
    • /
  • 文档数据库 MongoDB 版

DescribeDBInstances

最近更新时间：2024.04.26 11:09:07

首次发布时间：2022.04.12 11:06:53

我的收藏

调用 DescribeDBInstances 接口查询一个或多个 MongoDB 实例的基本信息。

请求类型

同步请求

注意事项

说明

若您不传入任何参数，默认返回当前账号下所有 MongoDB 实例的列表信息。

请求参数

参数类型是否必选示例值描述

ZoneId

String

否

cn-beijing-a

可用区 ID。

说明

您可以调用 DescribeAvailabilityZones 接口查询 MongoDB 实例的所有可用区信息，包括可用区 ID。

InstanceIdString否mongo-replica-e405f8e2****实例 ID。
InstanceNameString否test_mongo实例名称。

InstanceType

String

否

ReplicaSet

MongoDB 的实例类型，取值范围如下：

  • ReplicaSet：副本集。
  • ShardedCluster：分片集群 。

说明

若该参数留空，默认返回当前账号下所有类型的 MongoDB 实例列表。

InstanceStatusString否Running实例状态。关于实例状态的更多详情，请参见实例状态说明。
DBEngineString否MongoDB数据库引擎。取值固定为 MongoDB。

DBEngineVersion

String

否

MongoDB_4_0

数据库引擎版本，取值范围如下：

  • MongoDB_4_0：MongoDB 4.0 版本。
  • MongoDB_5_0：MongoDB 5.0 版本。

说明

若该参数留空，默认返回当前账号下所有版本的 MongoDB 实例列表。

CreateStartTimeString否2022-03-15T03:50:00Z实例创建的开始时间。格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。
CreateEndTimeString否2022-03-15T04:00:00Z实例创建的结束时间。格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。
UpdateStartTimeString否2022-03-19T03:45:00Z实例更新的开始时间。格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。
UpdateEndTimeString否2022-03-19T04:00:00Z实例更新的结束时间。格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。

VpcId

String

否

vpc-2743n1ihbxla87fap8tap****

实例所属的私有网络（VPC）ID。

说明

您可以调用 DescribeVpcs 接口查询当前账号下的所有私有网络列表信息，包括私有网络 ID。

PageNumberInteger否1实例信息列表的页码，默认值为 1。取值为不超过 Integer 数据类型的最大值，起始值为 1。
PageSizeInteger否10每页记录数，取值范围为 1~1000，默认值为 10。

TagFilters

Array of TagFilterObject

否

[
{
"Key":"instancetype",
"Value":"shard"
},
{
"Key":"chargetype",
"Value":"postpaid"
}
]

用于查询筛选的标签键值对数组。

说明

  • 筛选时标签键（Key）必填，标签值（Value）可不填，不填标签值表示不对标签值作限制，会搜索所有绑定了指定标签键的实例。
  • 单次最多支持同时传入 10 组标签键值对进行查询筛选。

ProjectName

String

否

default

指定实例所属的项目名称。

说明

若该参数留空，表示不使用实例的项目名称条件进行筛选。

TagFilterObject

参数类型是否必选示例值描述

Key

String

是

instancetype

用于查询筛选的标签键。

说明

  • 如需使用标签对实例进行查询筛选，该参数必填。
  • 允许传入重复的标签键。
  • 单次最多支持同时传入 10 个标签进行查询筛选。

Value

String

否

replica

用于查询筛选的标签键所对应的标签值。

说明

  • 若该参数留空，表示不对标签值作限制，会筛选所有绑定了指定标签键的实例。
  • 若传入空字符串，表示筛选对应标签键下，标签值为空的实例。

返回参数

参数类型示例值描述
TotalInteger1所有实例的数量。
DBInstancesArray of DBInstances请参见返回示例。实例基本信息列表。

DBInstances

参数类型示例值描述

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）。

说明

仅包年包月实例支持返回该参数。

ConfigServersId

String

mongo-shard-fa8cd21d****-config

ConfigServer 的 ID。

说明

仅分片集群实例支持返回该参数。

CreateTimeString2022-03-15T03:57:15Z实例创建时间（UTC）。

DBEngineVersion

String

MongoDB_4_0

数据库引擎版本，取值范围如下：

  • MongoDB_4_0：MongoDB 4.0 版本。
  • MongoDB_5_0：MongoDB 5.0 版本。

DBEngineVersionStr

String

MongoDB 4.0

数据库引擎版本的字符串。取值范围如下：

  • MongoDB 4.0：MongoDB 4.0 版本。
  • MongoDB 5.0：MongoDB 5.0 版本。

ExpiredTime

String

22022-03-19T03:45:28Z

实例到期时间（UTC）。

说明

仅包年包月实例支持返回该参数。

InstanceIdStringmongo-replica-9b3f8fb9****实例 ID。
InstanceNameStringtest-mongo实例名称。
InstanceStatusStringRunning实例状态。关于实例状态的更多详情，请参见实例状态说明。

InstanceType

String

ReplicaSet

MongoDB 的实例类型，取值范围如下：

  • ReplicaSet：副本集。
  • ShardedCluster：分片集群 。

MongosId

String

mongo-shard-011d2479****

Mongos 的 ID。

说明

仅分片集群实例支持返回该参数。

ReclaimTime

String

2022-03-26T03:45:28Z

实例的计划回收时间（UTC）。

说明

仅包年包月实例支持返回该参数。

ProjectNameStringdefault实例所属的项目名称。
SubnetIdStringsubnet-2743n265pa8zk7fap8st3****实例所属的子网 ID。

Tags

Array of TagObject

[
{
"Key": "department",
"Value": "game"
},
{
"Key": "owner",
"Value": "Alice"
}
]

实例已绑定的标签信息。

说明

仅已绑定了标签的实例才会返回该参数。

UpdateTimeString2022-03-19T03:45:28Z实例的更新时间（UTC）。
VpcIdStringvpc-3tfam26vmy3v****实例所属的私有网络 ID。

ZoneId

String

cn-beijing-a

实例所属的可用区 ID。

说明

若您的实例部署了多可用区，则会同时展示所有节点所在的可用区信息，从左至右依次为主节点、从节点、隐藏节点所在的可用区。关于多可用区部署的更多详情，请参见多可用区同城容灾解决方案。

StorageTypeStringLocalSSD实例的存储类型。当前仅支持本地 SSD 盘（即 LocalSSD）存储。
PrivateEndpointStringmongodb://:@mongoshard3d714182****0.mongodb.ivolces.com:3717,mongoshard3d714182****1.mongodb.ivolces.com:3717,mongoshard3d714182****2.mongodb.ivolces.com:3717/?authSource=admin&retryWrites=true实例私网连接地址的字符串信息。

TagObject

参数类型示例值描述

Key

String

instancetype

Key 参数在不同 API 接口中作用不同，其中：

  • 在 CreateDBInstance 和 AddTagsToResource 请求参数中表示需要绑定标签所对应的标签键。

    说明

    • 该参数留空表示新建实例不绑定任何标签。当需要为实例绑定标签时，标签键（Key）必填，标签值（Value）可不填，不填标签值表示对应标签键的标签值为空。
    • 支持一次传入多组标签键值对象，多组标签键值对象间用英文逗号（,）分隔。最多同时传入 20 组标签键值对。单个实例最多可绑定 50 个标签。标签键需满足设置规则，具体规则请参见标签设置规则。
  • 在 DescribeDBInstances 和 DescribeDBInstanceDetail 的返回数据中表示当前实例所绑定标签的标签键。

Value

String

replica

Value 参数在不同 API 接口中作用不同，其中：

  • 在 CreateDBInstance 和 AddTagsToResource 请求参数中表示需要绑定标签所对应的标签值。

    说明

    • 当需要为实例绑定标签时，标签键（Key）必填，标签值（Value）可不填，不填标签值表示对应标签键的标签值为空。支持一次传入多组标签键值对象，多组标签键值对象间用英文逗号（,）分隔。
    • 最多同时传入 20 组标签键值对。单个实例最多可绑定 50 个标签。标签键需满足设置规则，具体规则请参见标签设置规则。

  • 在 DescribeDBInstances 和 DescribeDBInstanceDetail 的返回数据中表示当前实例所绑定标签的标签值。

示例

请求示例 1

通过 TagFilters 字段筛选出按量计费分片集群实例。

POST https://mongodb.volcengineapi.com/?Action=DescribeDBInstances&Version=2022-01-01 HTTP/1.1
Host: mongodb.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,
    "TagFilters":[
        {
            "Key":"instancetype",
            "Value":"shard"
        },
        {
            "Key":"chargetype",
            "Value":"postpaid"
        }
    ]
}

返回示例 1

按量计费分片集群实例的正常返回示例。

{
    "ResponseMetadata": {
        "RequestId": "2023080717063891CD986698CC4AB46749",
        "Action": "DescribeDBInstances",
        "Version": "2022-01-01",
        "Service": "mongodb",
        "Region": "cn-beijing"
    },
    "Result": {
        "DBInstances": [
            {
                "ChargeStatus": "Normal",
                "ChargeType": "PostPaid",
                "ClosedTime": "",
                "ConfigServersId": "mongo-shard-3d71418285fd-config",
                "CreateTime": "2023-06-15T09:27:55Z",
                "DBEngine": "MongoDB",
                "DBEngineVersion": "MongoDB_4_0",
                "DBEngineVersionStr": "MongoDB 4.0",
                "ExpiredTime": "",
                "InstanceId": "mongo-shard-3d714182****",
                "InstanceName": "python_sdk_test_shard",
                "InstanceStatus": "Running",
                "InstanceType": "ShardedCluster",
                "MongosId": "mongo-shard-3d714182****",
                "PrivateEndpoint": "mongodb://<user>:<password>@mongoshard3d714182****0.mongodb.ivolces.com:3717,mongoshard3d714182****1.mongodb.ivolces.com:3717,mongoshard3d714182****2.mongodb.ivolces.com:3717/?authSource=admin&retryWrites=true",
                "ProjectName": "default",
                "ReclaimTime": "",
                "StorageType": "LocalSSD",
                "SubnetId": "subnet-rr96lovl7f28v0x58tv****",
                "Tags": [
                  {
                      "Key": "chargetype",
                      "Value": "postpaid"
                  },
                  {
                      "Key": "instancetype",
                      "Value": "shard"
                  }
                ],
                "UpdateTime": "2023-06-29T13:23:20Z",
                "VpcId": "vpc-13f24t16guqdc3n6nu4k5****",
                "ZoneId": "cn-beijing-a"
            }
        ],
        "Total": 1
    }
}

请求示例 2

通过 ChargeType 和 InstanceType 字段筛选出包年包月副本集实例。

POST https://mongodb.volcengineapi.com/?Action=DescribeDBInstances&Version=2022-01-01 HTTP/1.1
Host: mongodb.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": "2023080717041449288C0B997AD0B1****",
        "Action": "DescribeDBInstances",
        "Version": "2022-01-01",
        "Service": "mongodb",
        "Region": "cn-beijing"
    },
    "Result": {
        "DBInstances": [
            {
                "AutoRenew": false,
                "ChargeStatus": "Normal",
                "ChargeType": "Prepaid",
                "ClosedTime": "2023-09-04T04:00:00Z",
                "CreateTime": "2023-08-02T09:22:58Z",
                "DBEngine": "MongoDB",
                "DBEngineVersion": "MongoDB_5_0",
                "DBEngineVersionStr": "MongoDB 5.0",
                "ExpiredTime": "2023-09-03T15:59:59Z",
                "InstanceId": "mongo-replica-c70a99ee****",
                "InstanceName": "api_test_replica",
                "InstanceStatus": "Running",
                "InstanceType": "ReplicaSet",
                "PrivateEndpoint": "mongodb://<user>:<password>@mongoreplicac70a99ee****0.mongodb.ivolces.com:3717,mongoreplicac70a99ee****1.mongodb.ivolces.com:3717/?authSource=admin&replicaSet=rs-mongo-replica-c70a99ee****&retryWrites=true",
                "ProjectName": "default",
                "ReclaimTime": "2023-09-10T15:59:59Z",
                "StorageType": "LocalSSD",
                "SubnetId": "subnet-rr96lovl7f28v0x58tv****",
                "UpdateTime": "2023-08-03T02:58:29Z",
                "VpcId": "vpc-13f24t16guqdc3n6nu4k5****",
                "ZoneId": "cn-beijing-a"
            }
        ],
        "Total": 1
    }
}