文档首页/ 文档数据库服务 DDS/ API参考/ API v3（推荐）/ 实例管理/ 查询实例列表和详情
更新时间：2025-10-27 GMT+08:00
查看PDF
分享

查询实例列表和详情

功能介绍

根据指定条件查询实例列表和详情。

调试

您可以在API Explorer中调试该接口。

URI

  • URI格式

    GET /v3/{project_id}/instances

表1 参数说明

名称

是否必选

参数类型

描述

project_id

是

String

租户在某一Region下的项目ID。请参考获取项目ID章节获取项目编号。

id

否

String

实例ID，可以调用“查询实例列表和详情”接口获取。如果未申请实例，可以调用“创建实例”接口创建。

name

否

String

实例名称。

如果name以“*”起始，表示按照“*”后面的值模糊匹配，否则，按照实际填写的name精确匹配查询。

说明：

“*”为系统保留字符，不能只传入该字符。

mode

否

String

实例类型。

  • 取值为“Sharding”，表示集群实例。
  • 取值为“ReplicaSet”，表示副本集实例。
  • 取值为“Single”，表示单节点实例。

datastore_type

否

String

数据库版本类型。取值为“DDS-Community”。

vpc_id

否

String

虚拟私有云ID，获取方法如下：

  • 方法1：登录虚拟私有云服务的控制台界面，在虚拟私有云的详情页面查找VPC ID。
  • 方法2：通过虚拟私有云服务的API接口查询，具体操作可参考查询VPC列表。

subnet_id

否

String

子网的网络ID，获取方法如下：

  • 方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找网络ID。
  • 方法2：通过虚拟私有云服务的API接口查询，具体操作可参考查询子网列表。

offset

否

Integer

索引位置偏移量，表示从指定project ID下最新的实例创建时间开始，按时间的先后顺序偏移offset条数据后查询对应的实例信息。

取值大于或等于0。不传该参数时，查询偏移量默认为0，表示从最新的实例创建时间对应的实例开始查询。

limit

否

Integer

查询实例个数上限值。

取值范围：1~100。不传该参数时，默认查询前100条实例信息。

tags

否

String

根据实例标签键值对进行查询。

{key}表示标签键，{value}表示标签值，最多包含20组。key不可以为空或重复，value可以为空。

如果同时使用多个标签键值对进行查询，中间使用逗号分隔开，表示查询同时包含指定标签键值对的实例。

请求参数

表2 请求Header参数

名称

是否必选

参数类型

描述

X-Auth-Token

是

string

从IAM服务获取的用户Token。请参考认证鉴权。

响应参数

表3 响应Body参数

名称

是否必选

参数类型

描述

instances

是

Array of objects

实例信息。详情请参见表4。

total_count

是

Integer

总记录数。
表4 instances字段数据结构说明

名称

是否必选

参数类型

描述

id

是

String

实例ID。

name

是

String

实例名称。

remark

是

String

实例备注。

status

是

String

实例状态。

取值：

  • normal，表示实例正常。
  • abnormal，表示实例异常。
  • creating，表示实例创建中。
  • frozen，表示实例被冻结。
  • data_disk_full，表示存储空间满。
  • createfail，表示实例创建失败。
  • enlargefail，表示实例扩容节点个数失败。
说明：

实例正在执行的动作（actions），例如“rebooting，重启中”与实例状态（status）有本质的区别。详情请参见该表中的actions字段。

port

是

String

数据库端口号。文档数据库实例支持的端口号范围为2100～9500。

mode

是

String

实例类型。与请求参数相同。

region

是

String

实例所在区域。

datastore

是

Object

数据库信息。

详情请参见表5。

engine

是

String

存储引擎。支持WiredTiger/RocksDB存储引擎。

  • 数据库版本为4.2及以上时，存储引擎为RocksDB，取值为“rocksDB”。
  • 数据库版本为4.0和3.4时，存储引擎为WiredTiger，取值为“wiredTiger”。

created

是

String

实例创建时间。

updated

是

String

实例操作最新变更的时间。

db_user_name

是

String

默认用户名。取值为“rwuser”。

ssl

是

Integer

是否开启SSL安全连接。

  • 取值为“1”，表示开启。
  • 取值为“0”，表示不开启。

vpc_id

是

String

虚拟私有云ID。

subnet_id

是

String

子网的网络ID。

security_group_id

是

String

安全组ID列表。当实例存在多安全组时，多个安全组ID采用英文逗号分隔。

backup_strategy

是

Object

备份策略。

详情请参见表6。

pay_mode

否

String

计费方式。

  • 取值为“0”，表示按需计费。
  • 取值为“1”，表示包年/包月计费。

maintenance_window

是

String

系统可维护时间窗。

groups

是

Array of objects

组信息。

详情请参见表7。

disk_encryption_id

是

String

磁盘加密的密钥ID。该参数仅在实例磁盘被加密时返回。

enterprise_project_id

是

String

企业项目ID。

取值为“0”，表示为default企业项目。

time_zone

是

String

时区。

dss_pool_id

否

String

Dec用户专属存储ID。

actions

是

Array of strings

实例正在执行的动作。

取值：

  • RESTARTING，重启中。
  • RESTORE，恢复中。
  • RESIZE_FLAVOR，规格变更中。
  • RESTORE_TO_NEW_INSTANCE，恢复中。
  • MODIFY_VPC_PEER，跨子网访问设置中。
  • CREATE，创建中。
  • FROZEN，冻结。
  • RESIZE_VOLUME，存储扩容中。
  • RESTORE_CHECK，恢复检查中。
  • RESTORE_FAILED_HANGUP，恢复失败。
  • CLOSE_AUDIT_LOG，关闭审计策略中。
  • OPEN_AUDIT_LOG，打开审计策略中。
  • PERIOD_RESOURCE_SPEC_CHG，包周期资源变更检查中。
  • CREATE_IP_SHARD，shard IP显示开启中。
  • CREATE_IP_CONFIG，config IP显示开启中。
  • GROWING，节点扩容中。
  • SET_CONFIGURATION，修改参数中。
  • RESTORE_TABLE，恢复中。
  • MODIFY_SECURITYGROUP，修改安全组中。
  • BIND_EIP，修改公网EIP中。
  • UNBIND_EIP，解绑EIP中。
  • SWITCH_SSL，切换SSL中。
  • SWITCH_PRIMARY，主备切换中。
  • CHANGE_DBUSER_PASSWORD，修改密码中。
  • MODIFY_PORT，修改端口号中。
  • MODIFY_IP，修改内网IP中。
  • DELETE_INSTANCE，实例删除中。
  • REBOOT，重启中。
  • BACKUP，备份中。
  • MIGRATE_AZ，可用区迁移中。
  • PWD_RESETING，重置密码中。
  • UPGRADE_DATABASE，补丁升级中。
  • DATA_MIGRATION，数据迁移中。
  • SHARD_GROWING，分片扩容中。
  • APPLY_CONFIGURATION，变更参数组中。
  • RESET_PASSWORD，重置密码中。
  • GROWING_REVERT，删除节点中。
  • SHARD_GROWING_REVERT，分片删除中。
  • ONDEMAND_TO_PERIOD，转包周期中。
  • LOG_PLAINTEXT_SWITCH，慢日志配置修改中。
  • CREATE_DATABASE_USER，创建数据库用户中。
  • CREATE_DATABASE_ROLE，创建数据库角色中。
  • MODIFY_NAME，修改名称中。
  • MODIFY_PRIVATE_DNS，修改内网域名中。
  • MODIFY_OP_LOG_SIZE，oplog大小修改中。
  • ADD_READONLY_NODES，只读节点扩容中。

order_id

否

String

订单ID，仅包周期场景返回。

tags

是

Array of objects

标签列表。

详情请参见表10。
表5 datastore字段数据结构说明

名称

是否必选

参数类型

描述

type

是

String

数据库引擎。

version

是

String

数据库版本。支持5.0、4.4、4.2、4.0、3.4版本，取值为“5.0”、“4.4”、“4.2”、“4.0”、“3.4”。

whole_version

是

String

数据库的完整版本号。

patch_available

是

Boolean

当前实例是否有可升级的补丁，返回true时可以通过“数据库补丁升级”进行升级。
表6 backup_strategy字段数据结构说明

名称

是否必选

参数类型

描述

start_time

是

String

备份时间段。自动备份将在该时间段内触发。当前时间指UTC时间。

keep_days

是

Integer

已生成备份文件可以保存的天数。取值范围：0~732。
表7 groups字段数据结构说明

名称

是否必选

参数类型

描述

type

是

String

节点类型。

取值：
  • shard
  • config
  • mongos
  • replica
  • single
  • readonly

id

是

String

组ID。节点类型为shard、config和readonly时，该参数有效。

name

是

String

组名称。节点类型为shard、config和readonly时，该参数有效。

status

是

String

组状态。节点类型为shard、config和readonly时，该参数有效。

volume

是

Object

volume信息。详情请参见表8。节点类型为shard、config、replica、single、readonly时，该参数有效。

nodes

是

Array of objects

节点信息。详情请参见表9。
表8 volume字段数据结构说明

名称

是否必选

参数类型

描述

size

是

String

磁盘大小。单位：GB。

used

是

String

磁盘使用量。单位：GB。
表9 nodes字段数据结构说明

名称

是否必选

参数类型

描述

id

是

String

节点ID。

name

是

String

节点名称。

status

是

String

节点状态。

role

是

String

节点角色。

取值：
  • master，mongos节点返回该值。
  • Primary，shard组主节点、config组主节点、副本集主节点、单节点返回该值。
  • Secondary，shard组备节点、config组备节点、副本集备节点返回该值。
  • Hidden，shard组隐藏节点、config组隐藏节点、副本集隐藏节点返回该值。
  • unknown，节点异常时返回该值。
  • Readonly, 只读节点返回该值。

private_ip

是

String

节点内网IP。该参数默认仅针对集群实例的mongos节点、副本集实例、以及单节点实例有效，且在弹性云服务器创建成功后参数值存在，否则，值为""。

注意：

打开shard或者config IP 之后，集群实例的shard节点或者config节点的Primary、Secondary节点也会有该值。

public_ip

是

String

绑定的外网IP。该参数仅针对集群实例的mongos节点、副本集实例的主节点和备节点、以及单节点实例有效。

spec_code

是

String

资源规格编码。关于实例的规格信息，请参见查询数据库规格中响应参数“flavors.spec_code”的值。

availability_zone

是

String

可用区。
表10 tag字段说明

名称

是否必选

参数类型

描述

key

是

String

标签键。

value

是

String

标签值。

响应示例中参数“region”和“availability_zone”的值为示例值。

请求示例

  • 查询所有实例列表和详情 
    https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances
  • 根据指定条件查询实例列表和详情 
    https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances?offset=0&limit=10&id=ed7cc6166ec24360a5ed5c5c9c2ed726in02&name=hy&mode=ReplicaSet&datastore_type=DDS-Community&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&tags=key1=value1,key2=value2

响应示例

{
  "instances": [
    {
      "id": "8436a91546294036b75931e879882200in02",
      "name": "dds-efa6",
      "remark": "test",
      "status": "normal",
      "port": "8635",
      "mode": "ReplicaSet",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:05:52",
      "updated": "2019-01-17T07:05:47",
      "db_user_name": "rwuser",
      "ssl": 1,
      "vpc_id": "674e9b42-cd8d-4d25-a2e6-5abcc565b961",
      "subnet_id": "f1df08c5-71d1-406a-aff0-de435a51007b",
      "security_group_id": "7aa51dbf-5b63-40db-9724-dad3c4828b58",
      "backup_strategy": {
        "start_time": "16:00-17:00",
        "keep_days": 7
      },
      "pay_mode": 0,
      "maintenance_window": "02:00-06:00",
      "groups": [{
        "type": "replica",
        "volume": {
          "size": "10",
          "used": "0.33"
        },
        "nodes": [
          {
            "id": "233eaac9c6f245c0bb9c2d21eea12d1bno02",
            "name": "dds-efa6_replica_node_2",
            "status": "normal",
            "role": "Primary",
            "private_ip": "192.168.0.174",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          },
          {
            "id": "d57d76d6320a4a7b86db82c317550c4ano02",
            "name": "dds-efa6_replica_node_1",
            "status": "normal",
            "role": "Hidden",
            "private_ip": "192.168.0.39",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          },
          {
            "id": "f46b0a1cf4d9400e9fd7af17f8742d37no02",
            "name": "dds-efa6_replica_node_3",
            "status": "normal",
            "role": "Secondary",
            "private_ip": "192.168.0.176",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          }
        ]
      }],
      "enterprise_project_id": "0",
      "time_zone": "",
      "dss_pool_id": "f5f84ed7-6f19-4bd4-99d7-b450ad6cc4dd",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    },
    {
      "id": "d77905385f114217b75ae7d6ab9a7588in02",
      "name": "dds-5699",
      "status": "normal",
      "remark": "测试",
      "port": "8635",
      "mode": "Single",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:04:39",
      "updated": "2019-01-17T07:04:33",
      "db_user_name": "rwuser",
      "ssl": 1,
      "vpc_id": "674e9b42-cd8d-4d25-a2e6-5abcc565b961",
      "subnet_id": "f1df08c5-71d1-406a-aff0-de435a51007b",
      "security_group_id": "7aa51dbf-5b63-40db-9724-dad3c4828b58",
      "backup_strategy": {
        "start_time": "17:00-18:00",
        "keep_days": 7
      },
      "pay_mode": 0,
      "maintenance_window": "02:00-06:00",
      "groups": [{
        "type": "single",
        "volume": {
          "size": "10",
          "used": "0.33"
        },
        "nodes": [
          {
            "id": "bd4dccbd53ae48d5bd3046bebf715079no02",
            "name": "dds-5699_single_node_1",
            "status": "normal",
            "role": "Primary",
            "private_ip": "192.168.0.9",
            "public_ip": "",
            "spec_code": "dds.mongodb.c6.medium.4.single",
            "availability_zone": "bbb"
          }
        ]
      }],
      "enterprise_project_id": "0",
      "time_zone": "",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    },
    {
      "id": "9136fd2a9fcd405ea4674276ce36dae8in02",
      "name": "dds-32f4",
      "remark": 123,
      "status": "normal",
      "port": "8635",
      "mode": "Sharding",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:04:37",
      "updated": "2019-01-17T07:04:31",
      "db_user_name": "rwuser",
      "ssl": 1,
      "vpc_id": "674e9b42-cd8d-4d25-a2e6-5abcc565b961",
      "subnet_id": "f1df08c5-71d1-406a-aff0-de435a51007b",
      "security_group_id": "7aa51dbf-5b63-40db-9724-dad3c4828b58",
      "backup_strategy": {
        "start_time": "19:00-20:00",
        "keep_days": 7
      },
      "pay_mode": 0,
      "maintenance_window": "02:00-06:00",
      "groups": [
        {
          "type": "mongos",
          "nodes": [
            {
              "id": "a742c13a284949adad177672e8a0f01cno02",
              "name": "dds-32f4_mongos_node_1",
              "status": "normal",
              "role": "Primary",
              "private_ip": "192.168.0.56",
              "public_ip": "",
              "spec_code": "dds.mongodb.c6.medium.4.mongos",
              "availability_zone": "bbb"
            },
            {
              "id": "d4f66666b1d64ab28719da0526341c7eno02",
              "name": "dds-32f4_mongos_node_2",
              "status": "normal",
              "role": "Primary",
              "private_ip": "192.168.0.185",
              "public_ip": "",
              "spec_code": "dds.mongodb.c6.medium.4.mongos",
              "availability_zone": "bbb"
            }
          ]
        },
        {
          "type": "shard",
          "volume": {
            "size": "10",
            "used": "0.33"
          },
          "nodes": [
            {
              "id": "0e9abaebe5974b63a5b221de6ee34cfeno02",
              "name": "dds-32f4_shard_2_node_3",
              "status": "normal",
              "role": "Primary",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            },
            {
              "id": "1d7f4c5476c04cc187f920925c2b601fno02",
              "name": "dds-32f4_shard_2_node_2",
              "status": "normal",
              "role": "Hidden",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            },
            {
              "id": "3dd2cce03da54fc08f10651cbfea778dno02",
              "name": "dds-32f4_shard_2_node_1",
              "status": "normal",
              "role": "Secondary",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            }
          ]
        },
        {
          "type": "config",
          "volume": {
            "size": "10",
            "used": "0.33"
          },
          "nodes": [
            {
              "id": "7422f7331b714ac39aa647a1ec968d33no02",
              "name": "dds-32f4_config_node_2",
              "status": "normal",
              "role": "Primary",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            },
            {
              "id": "9e3b343151044eda91ddb8a42ae5cbefno02",
              "name": "dds-32f4_config_node_3",
              "status": "normal",
              "role": "Hidden",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            },
            {
              "id": "c0053ca460ac4889841ffb14a886ec54no02",
              "name": "dds-32f4_config_node_1",
              "status": "normal",
              "role": "Secondary",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            }
          ]
        }
      ],
      "enterprise_project_id": "0",
      "time_zone": "",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    }
  ],
  "total_count": 3
}

状态码

详情请参见状态码。

错误码

详情请参见错误码。

父主题： 实例管理

相关文档