# 查询数据库实例列表 - ListInstances #### 功能介绍 根据指定条件查询实例列表。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-rds/rds_10_0005.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | rds:instance:listAll | read | - | - | rds:instance:list | - | #### URI - URI格式 GET /v3/{project_id}/instances?id={id}\&name={name}\&type={type}\&datastore_type={datastore_type}\&group_type={group_type}\&offset={offset}\&limit={limit}\&tags={key}={value} - 参数说明 表1参数说明 | 名称 | 参数类型 | 是否必选 | 说明 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释**： 租户在某一Region下的项目ID。 获取方法请参见[获取项目ID](https://support.huaweicloud.com/api-flexusrds/rds_03_0002.html)。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | id | String | 否 | **参数解释**： 实例ID。 "\*"为系统保留字符，如果ID是以"\*"起始，表示按照\*后面的值模糊匹配，否则，按照ID精确匹配查询。不能只传入"\*"。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | name | String | 否 | **参数解释**： 实例名称。 "\*"为系统保留字符，如果name是以"\*"起始，表示按照\*后面的值模糊匹配，否则，按照name精确匹配查询。不能只传入"\*"。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | type | String | 否 | **参数解释**： 按照实例类型查询。 **约束限制**： 不涉及。 **取值范围**： 取值Single、Ha，分别对应于单实例、主备实例。 **默认取值**： 不涉及。 | | datastore_type | String | 否 | **参数解释**： 数据库类型。 **约束限制**： 不涉及。 **取值范围**： MySQL，区分大小写。 **默认取值**： 不涉及。 | | offset | Integer | 否 | **参数解释**： 索引位置，偏移量。 **约束限制**： 不涉及。 **取值范围**： 从第一条数据偏移offset条数据后开始查询，默认为0（偏移0条数据，表示从第一条数据开始查询），必须为数字，不能为负数。 **默认取值**： 0 | | limit | Integer | 否 | **参数解释**： 查询记录数。 **约束限制**： 不涉及。 **取值范围**： 默认为100，不能为负数，最小值为1，最大值为100。 **默认取值**： 100 | | tags | Array of objects | 否 | **参数解释：** 根据实例标签键值对进行查询。详情请参见[表2]。 **约束限制：** 如果同时使用多个标签键值对进行查询，中间使用逗号分隔开，最多包含20组。 | | group_type | String | 是 | **参数解释：** 查询FlexusRDS实例列表。 **约束限制：** 不涉及。 **取值范围：** flexus **默认取值：** 不涉及。 | 表2tags字段数据结构说明 | 名称 | 参数类型 | 是否必选 | 说明 | |:---|:---|:---|:---| | key | String | 是 | **参数解释：** 标签键。 **约束限制：** 不涉及。 **取值范围：** 长度为1-128个unicode字符。 可以包含任何语种字母、数字、空格和_.:=+-@，但首尾不能含有空格，不能以_sys_开头。 **默认取值：** 不涉及。 | | value | String | 否 | **参数解释：** 标签值。 **约束限制：** 不涉及。 **取值范围：** 最大长度255个unicode字符，可以为空字符串。 可以包含任何语种字母、数字、空格和_.:=+-@。 **默认取值：** 不涉及。 | #### 请求参数 无。 #### 请求示例 - 查询所有实例列表 ``` GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances ``` - 根据指定条件查询实例列表 ``` GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datastore_type=MySQL&offset=0&limit=10&tags=rds001=001,rds002=002&group_type=flexus ``` #### 响应消息 - 正常响应要素说明 表3参数说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | instances | Array of objects | **参数解释：** 实例信息。详情请参见[表4]。 | | total_count | Integer | **参数解释：** 总记录数。 **取值范围：** 不涉及。 | 表4instances字段数据结构说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | id | String | **参数解释：** 实例ID。 **取值范围：** 不涉及。 | | name | String | **参数解释：** 实例名称。 **取值范围：** 不涉及。 | | status | String | **参数解释：** 实例状态。 **取值范围：** - BUILD：表示实例正在创建。 - ACTIVE：表示实例正常。 - FAILED：表示实例异常。 - MODIFYING：表示实例正在扩容。 - REBOOTING：表示实例正在重启。 - RESTORING：表示实例正在恢复。 - BACKING UP：表示实例正在进行备份。 - STORAGE FULL：表示实例磁盘空间满。 | | alias | String | **参数解释：** 实例的备注信息。 **取值范围：** 不涉及。 | | private_ips | List\ | **参数解释：** 实例内网IP地址列表。实例创建成功后该值存在，其他情况下为空字符串。 | | private_dns_names | List\ | **参数解释：** 实例内网域名列表。实例创建成功后，需要手动申请内网域名，否则查询内网域名为空。 | | public_dns_names | List\ | **参数解释：** 实例公网域名列表。实例创建成功后，需要手动申请公网域名，否则查询公网域名为空。 | | public_ips | List\ | **参数解释：** 实例外网IP地址列表。 | | port | Integer | **参数解释：** 数据库端口号。 **取值范围：** 当不传该参数时，默认端口：3306 | | enable_ssl | Boolean | **参数解释：** 实例开启SSL标志。 **取值范围：** - 取值为"true"：表示实例已开启SSL。 - 取值为"false"：表示实例未开启SSL。 | | type | String | **参数解释：** 实例类型。 **取值范围：** 取值为"Single"，"Ha"，分别对应于单机实例、主备实例。 | | ha | Object | **参数解释：** HA信息，获取HA实例时返回。 详情请参见[表5]。 | | region | String | **参数解释：** 实例所在区域。 **取值范围：** 不涉及。 | | datastore | Object | **参数解释：** 数据库信息。详情请参见[表6]。 | | created | String | **参数解释：** 创建时间。 **取值范围：** 格式为"yyyy-mm-ddThh:mm:ssZ"。 其中，T指某个时间的开始；Z指时区偏移量，例如偏移1个小时显示为+0100。 创建时返回值为空，数据库实例创建成功后该值不为空。 | | updated | String | **参数解释：** 更新时间。 **取值范围：** 格式为"yyyy-mm-ddThh:mm:ssZ"。 其中，T指某个时间的开始；Z指时区偏移量，例如偏移1个小时显示为+0100。 创建时返回值为空，数据库实例创建成功后该值不为空。 | | db_user_name | String | **参数解释：** 默认用户名。 **取值范围：** 不涉及。 | | vpc_id | String | **参数解释：** 虚拟私有云ID。 **取值范围：** 不涉及。 | | subnet_id | String | **参数解释：** 子网的网络ID信息。 **取值范围：** 不涉及。 | | security_group_id | String | **参数解释：** 安全组ID。 **取值范围：** 不涉及。 | | flavor_ref | String | **参数解释：** 规格码。 **取值范围：** 不涉及。 | | cpu | String | **参数解释：** CPU大小。例如，1表示1U。 **取值范围：** 不涉及。 | | mem | String | **参数解释：** 内存大小（单位：GB）。 **取值范围：** 不涉及。 | | volume | Object | **参数解释：** 实例存储信息。详情请参见[表7]。 | | switch_strategy | String | **参数解释：** 数据库切换策略。 **取值范围：** 取值为"reliability"或"availability"，分别对应于可靠性优先和可用性优先。 | | db_read_only_from_tenant | String | **参数解释：** 数据库是否为只读权限。 **取值范围：** - true：表示数据库是只读权限。 - false：表示数据库非只读权限。 | | read_only_by_user | Boolean | **参数解释：** 用户设置的实例只读状态。 **取值范围：** - true：表示该实例被设置为只读状态。 - false：表示该实例未被设置为只读状态。 | | backup_strategy | Object | **参数解释：** 备份策略。详情请参见[表8]。 | | maintenance_window | String | **参数解释：** 可维护时间窗，为UTC时间。 **取值范围：** 不涉及。 | | nodes | Array of objects | **参数解释：** 主备实例信息。详情请参见[表9]。 | | related_instance | Array of objects | **参数解释：** 所关联的数据库实例列表。详情请参见[表10]。 | | disk_encryption_id | String | **参数解释：** 磁盘加密密钥ID。 **取值范围：** 不涉及。 | | enterprise_project_id | String | **参数解释：** 企业项目ID。 **取值范围：** 不涉及。 | | time_zone | String | **参数解释：** 时区。 **取值范围：** 不涉及。 | | charge_info | Object | **参数解释：** 计费类型信息。详情请参见[表11]。 | | tags | Array of objects | **参数解释：** 标签列表，没有标签默认为空数组。 详情请参见[表12]。 | | order_id | String | **参数解释：** 订单ID。 **取值范围：** 不涉及。 | | associated_with_ddm | Boolean | **参数解释：** 是否已被DDM实例关联。 **取值范围：** 不涉及。 | | expiration_time | String | **参数解释：** 实例的到期时间。 **取值范围：** 格式为"yyyy-mm-ddThh:mm:ssZ"。 仅包周期场景返回。 | 表5ha字段数据结构说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | replication_mode | String | **参数解释：** 备机同步参数。 **取值范围：** - "async"为异步模式。 - "semisync"为半同步模式。 | 表6datastore字段数据结构说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | type | String | **参数解释：** 数据库引擎。 **取值范围：** MySQL，不区分大小写。 | | version | String | **参数解释：** 数据库版本。 **取值范围：** 5.7、8.0 | | complete_version | String | **参数解释：** 数据库完整版本号。 **取值范围：** 不涉及。 | 表7volume字段数据结构说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | type | String | **参数解释：** 磁盘类型。 **取值范围：** CLOUDSSD：区分大小写，表示SSD云盘，仅支持通用型和独享型规格实例。 | | size | Integer | **参数解释：** 磁盘大小。 **取值范围：** 40 GB\~4000 GB，必须为10的整数倍。 | 表8backup_strategy字段数据结构说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | start_time | String | **参数解释：** 备份时间段。自动备份将在该时间段内触发。 **取值范围：** 非空，格式必须为hh:mm-HH:MM且有效，当前时间指UTC时间。 - HH取值必须比hh大1。 - mm和MM取值必须相同，且取值必须为00、15、30或45。 示例： - 08:15-09:15 - 23:00-00:00 | | keep_days | Integer | **参数解释：** 指定备份文件的可保存天数。 **取值范围：** 0～732。取值为0，表示关闭自动备份策略。如果需要延长保留时间请联系客服人员申请，自动备份最长可以保留2562天。 | 表9nodes字段数据结构说明 | **名称** | **参数类型** | **说明** | |:---|:---|:---| | id | String | **参数解释：** 节点ID。 **取值范围：** 不涉及。 | | name | String | **参数解释：** 节点名称。 **取值范围：** 不涉及。 | | role | String | **参数解释：** 节点类型。 **取值范围：** 取值为"master"、"slave"，分别对应于主节点、备节点。 | | status | String | **参数解释：** 节点状态。 **取值范围：** - creating：表示节点正在创建。 - active或者normal：表示节点正常。 - abnormal：表示节点异常。 - createfail：表示节点创建失败。 - enlargefail：表示节点扩容失败。 - restarting：表示节点正在重启。 - resizing：表示正在变更规格。 - resizefailed：表示变更规格失败。 - data_disk_full：表示磁盘空间满。 | | availability_zone | String | **参数解释：** 可用区。 **取值范围：** 不涉及。 | 表10related_instance字段数据结构说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | id | String | **参数解释：** 关联实例ID。 **取值范围：** 不涉及。 | | type | String | **参数解释：** 关联实例类型。 **取值范围：** replica_of：表示主实例。 | 表11chargeInfo字段数据结构说明 | 名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | charge_mode | 是 | String | **参数解释：** 计费模式。 **取值范围：** prePaid：预付费，即包年/包月。 | 表12tags字段数据结构说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | key | String | **参数解释：** 标签键。 **取值范围：** 不涉及。 | | value | String | **参数解释：** 标签值。 **取值范围：** 不涉及。 | ![](https://support.huaweicloud.com/api-flexusrds/public_sys-resources/note_3.0-zh-cn.png) 响应样例中，"region"和 "availability_zone"的值为示例值。 - 正常响应样例 **根据指定条件查询实例列表：** ``` { "instances": [{ "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01", "status": "ACTIVE", "name": "mysql-0820-022709-01", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2018-08-20T02:33:49+0800", "updated": "2018-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.cn-xianhz-1.mysql.rds.myhuaweicloud.com"], "public_ips": ["10.10.10.1"], "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "switch_strategy": "", "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ] }], "total_count": 1 } ``` - **查询所有实例列表：** ``` { "instances": [{ "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01", "status": "ACTIVE", "name": "mysql-0820-022709-01", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.7" }, "created": "2018-08-20T02:33:49+0800", "updated": "2018-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.cn-xianhz-1.mysql.rds.myhuaweicloud.com"], "public_ips": ["10.10.10.1"], "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "cpu": "2", "mem": "4", "switch_strategy": "", "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ], "associated_with_ddm": false }, { "id": "ed7cc6166ec24360a5ed5c5c9c2ed726in02", "status": "ACTIVE", "name": "mysql-0820-022709-02", "port": 3306, "type": "Single", "region": "aaa", "datastore": { "type": "MySQL", "version": "5.6" }, "created": "2019-08-20T02:33:49+0800", "updated": "2019-08-20T02:33:50+0800", "volume": { "type": "ULTRAHIGH", "size": 100 }, "nodes": [{ "id": "06f1c2ad57604ae89e153e4d27f4e4b8no01", "name": "mysql-0820-022709-01_node0", "role": "master", "status": "ACTIVE", "availability_zone": "bbb" }], "alias": "description", "private_ips": ["192.168.0.1"], "private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.cn-xianhz-1.mysql.rds.myhuaweicloud.com"], "public_ips": ["10.10.10.1"], "db_user_name": "root", "vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7", "subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef", "security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97", "flavor_ref": "rds.mysql.s1.large", "cpu": "2", "cpu": "4", "switch_strategy": "", "backup_strategy": { "start_time": "19:00-20:00", "keep_days": 7 }, "maintenance_window": "02:00-06:00", "related_instance": [], "disk_encryption_id": "", "time_zone": "", "tags": [ { "key": "rds001", "value": "001" }, { "key": "rds002", "value": "002" } ], "associated_with_ddm": false }], "total_count": 2 } ``` - 异常响应 请参见[异常请求结果](https://support.huaweicloud.com/api-flexusrds/rds_01_0010.html)。 #### 状态码 - 正常 200 - 异常 请参见[状态码](https://support.huaweicloud.com/api-flexusrds/rds_10_0200.html)。