# 查询实例列表和详情-QueryingInstancesandDetails #### 功能介绍 根据指定条件查询实例列表和详情。 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=DDS&api=ListInstances)中调试该接口。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-dds/dds_api_permission.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | dds:instance:listAll | list | - | - | dds:instance:list | - | #### URI - URI格式 GET /v3/{project_id}/instances 表1参数说明 | 名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | 租户在某一Region下的项目ID。请参考[获取项目ID](https://support.huaweicloud.com/api-dds/dds_projectid.html)章节获取项目编号。 | | 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列表](https://support.huaweicloud.com/api-vpc/vpc_api01_0003.html)。 | | subnet_id | 否 | String | 子网的网络ID，获取方法如下： - 方法1：登录虚拟私有云服务的控制台界面，单击VPC下的子网，进入子网详情页面，查找网络ID。 - 方法2：通过虚拟私有云服务的API接口查询，具体操作可参考[查询子网列表](https://support.huaweicloud.com/api-vpc/vpc_subnet01_0003.html)。 | | 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。请参考[认证鉴权](https://support.huaweicloud.com/api-dds/dds_api_0010.html)。 | #### 响应参数 表3响应Body参数 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | instances | Array of objects | 实例信息。详情请参见[表4]。 | | total_count | Integer | 总记录数。 | 表4instances字段数据结构说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | 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]。 | 表5datastore字段数据结构说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | type | String | 数据库引擎。取值为"DDS-Community"。 | | 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时可以通过"数据库补丁升级"进行升级。 | 表6backup_strategy字段数据结构说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | start_time | String | 备份时间段。自动备份将在该时间段内触发。当前时间指UTC时间。 | | keep_days | Integer | 已生成备份文件可以保存的天数。取值范围：0\~732。 | 表7groups字段数据结构说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | 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]。 | 表8volume字段数据结构说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | size | String | 磁盘大小。单位：GB。 | | used | String | 磁盘使用量。单位：GB。 | 表9nodes字段数据结构说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | id | String | 节点ID。 | | name | String | 节点名称。 | | status | String | 节点状态。 取值： - normal，表示节点正常。 - abnormal，表示节点异常。 - creating，表示节点创建中。 - data_disk_full，表示节点存储空间满。 - createfail，表示节点创建失败。 - enlargefail，表示扩容节点失败。 - resizefailed，表示节点规格变更失败。 | | 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 | 资源规格编码。关于实例的规格信息，请参见[查询数据库规格-QueryingDatabaseSpecifications](https://support.huaweicloud.com/api-dds/dds_instance_specification.html)中响应参数"flavors.spec_code"的值。 | | availability_zone | String | 可用区。 | | nat_gateway_id | String | 公网NAT网关实例的ID。可以调用"[查询公网NAT网关列表](https://support.huaweicloud.com/api-natgateway/ListNatGateways.html)"接口获取。 | | external_service_port | Integer | 弹性公网IP对外提供服务的端口号。取值范围：1\~65535。 | 表10tag字段说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | key | String | 标签键。 | | value | String | 标签值。 | ![](https://support.huaweicloud.com/api-dds/public_sys-resources/note_3.0-zh-cn.png) 响应示例中参数"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 } ``` #### 状态码 详情请参见[状态码](https://support.huaweicloud.com/api-dds/dds_status_code.html)。 #### 错误码 详情请参见[错误码](https://support.huaweicloud.com/api-dds/dds_error_code.html)。