更新时间:2022-03-10 GMT+08:00

查询数据库实例列表

功能介绍

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

URI

  • URI格式

    GET https://{Endpoint}/v3/{project_id}/instances?id={id}&name={name}&type={type}&datastore_type={datastore_type}&vpc_id={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit}&tags={key}={value}

  • URI样例
    • 查询所有实例列表

      https://{Endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances

    • 根据指定条件查询实例列表

      https://{Endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datastore_type=MySQL&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offset=0&limit=10&tags=rds001=001,rds002=002

  • 参数说明
    表1 参数说明

    名称

    参数类型

    是否必选

    说明

    project_id

    String

    租户在某一region下的project ID。

    获取方法请参见获取项目ID

    id

    String

    实例ID。

    “*”为系统保留字符,如果id是以“*”起始,表示按照*后面的值模糊匹配,否则,按照id精确匹配查询。不能只传入“*”。

    name

    String

    实例名称。

    “*”为系统保留字符,如果name是以“*”起始,表示按照*后面的值模糊匹配,否则,按照name精确匹配查询。不能只传入“*”。

    type

    String

    按照实例类型查询。取值Single、Ha、Replica、Enterprise,分别对应于单实例、主备实例和只读实例、分布式实例(企业版)。

    datastore_type

    String

    数据库类型,区分大小写。

    • MySQL
    • PostgreSQL

    vpc_id

    String

    虚拟私有云ID。

    • 方法1:登录虚拟私有云服务的控制台界面,在虚拟私有云的详情页面查找VPC ID。
    • 方法2:获取方法请参见《虚拟私有云API参考》中“查询VPC列表”的内容。

    subnet_id

    String

    子网的网络ID信息。

    • 方法1:登录虚拟私有云服务的控制台界面,单击VPC下的子网,进入子网详情页面,查找网络ID。
    • 方法2:获取方法请参见《虚拟私有云API参考》中“查询子网列表”的内容。

    offset

    Integer

    索引位置,偏移量。从第一条数据偏移offset条数据后开始查询,默认为0(偏移0条数据,表示从第一条数据开始查询),必须为数字,不能为负数。

    limit

    Integer

    查询记录数。默认为100,不能为负数,最小值为1,最大值为100。

    tags

    Array of objects

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

    • {key}表示标签键,不可以为空或重复。
    • {value}表示标签值,可以为空。

    如果同时使用多个标签键值对进行查询,中间使用逗号分隔开,最多包含10组。

    详情请参见表2

    表2 tags字段数据结构说明

    名称

    参数类型

    是否必选

    说明

    key

    String

    键。最大长度127个unicode字符。key不能为空或者空字符串,不能为空格,使用之前先trim前后半角空格。不能包含+/?#&=,%特殊字符。

    value

    String

    值。最大长度255个unicode字符,使用之前先trim 前后半角空格。不能包含+/?#&=,%特殊字符。

    如果value为空,则表示any_value(查询任意value)。

请求消息

无。

响应消息

  • 正常响应要素说明
    表3 参数说明

    名称

    参数类型

    说明

    instances

    Array of objects

    实例信息。

    详情请参见表4

    total_count

    Integer

    总记录数。

    表4 instances字段数据结构说明

    名称

    参数类型

    说明

    id

    String

    实例ID。

    name

    String

    创建的实例名称。

    status

    String

    实例状态。

    取值:

    值为“BUILD”,表示实例正在创建。

    值为“ACTIVE”,表示实例正常。

    值为“FAILED”,表示实例异常。

    值为“MODIFYING”,表示实例正在扩容。

    值为“REBOOTING”,表示实例正在重启。

    值为“RESTORING”,表示实例正在恢复。

    值为“MODIFYING INSTANCE TYPE”,表示实例正在转主备。

    值为“SWITCHOVER”,表示实例正在主备切换。

    值为“MIGRATING”,表示实例正在迁移。

    值为“BACKING UP”,表示实例正在进行备份。

    值为“MODIFYING DATABASE PORT”,表示实例正在修改数据库端口。

    private_ips

    List<String>

    实例内网IP地址列表。弹性云服务器创建成功后该值存在,其他情况下为空字符串。

    private_dns_names

    List<String>

    实例内网域名列表。实例创建成功后,需要手动申请内网域名,否则查询内网域名为空。

    public_ips

    List<String>

    实例外网IP地址列表。

    port

    Integer

    数据库端口号。

    • MySQL数据库端口设置范围为1024~65535(其中12017和33071被RDS系统占用不可设置)。
    • PostgreSQL数据库端口修改范围为2100~9500。

    当不传该参数时,默认端口如下:

    • MySQL默认3306。
    • PostgreSQL默认5432。

    type

    String

    实例类型,取值为“Single”,“Ha”或“Replica”, "Enterprise",分别对应于单机实例、主备实例、只读实例、分布式实例(企业版)。

    ha

    Object

    HA信息,获取HA实例时返回。

    详情请参见表4

    region

    String

    实例所在区域。

    datastore

    Object

    数据库信息。

    详情请参见表5

    created

    String

    创建时间,格式为“yyyy-mm-ddThh:mm:ssZ”。

    其中,T指某个时间的开始;Z指时区偏移量,例如偏移1个小时显示为+0100。

    说明:创建时返回值为空,数据库实例创建成功后该值不为空。

    updated

    String

    更新时间,格式与“created”字段对应格式完全相同。

    说明:创建时返回值为空,数据库实例创建成功后该值不为空。

    db_user_name

    String

    默认用户名。

    vpc_id

    String

    虚拟私有云ID。

    subnet_id

    String

    子网的网络ID信息。

    security_group_id

    String

    安全组ID。

    flavor_ref

    String

    规格码。

    volume

    Object

    Volume信息。

    详情请参见表6

    switch_strategy

    String

    数据库切换策略。取值为“reliability”或“availability”,分别对应于可靠性优先和可用性优先。

    backup_strategy

    Object

    备份策略。

    详情请参见表7

    maintenance_window

    String

    可维护时间窗,为UTC时间。

    nodes

    Array of objects

    主备实例信息。

    详情请参见表8

    related_instance

    Array of objects

    所关联的数据库实例列表。

    详情请参见表9

    time_zone

    String

    时区。

    tags

    Array of objects

    标签列表,没有标签默认为空数组。

    详情请参见表11

    表5 ha字段数据结构说明

    名称

    参数类型

    说明

    replication_mode

    String

    备机同步参数。

    取值:非空。

    • MySQL为“async”或“semisync”。
    • PostgreSQL为“async”或“sync”。
    说明:
    • “async”为异步模式。
    • “semisync”为半同步模式。
    • “sync”为同步模式。
    表6 datastore字段数据结构说明

    名称

    参数类型

    说明

    type

    String

    数据库引擎。

    version

    String

    数据库版本。

    表7 volume字段数据结构说明

    名称

    参数类型

    说明

    type

    String

    磁盘类型。

    size

    Integer

    磁盘大小。

    表8 backup_strategy字段数据结构说明

    名称

    参数类型

    说明

    start_time

    String

    备份时间段。自动备份将在该时间段内触发。

    当前时间指UTC时间。

    keep_days

    Integer

    已生成的备份文件可以保存的天数。

    取值范围:0~732。为0时,表示未设置自动备份策略或备份策略已关闭。如果需要延长保留时间请联系客服人员申请,自动备份最长可以保留2562天。

    表9 nodes字段数据结构说明

    名称

    参数类型

    说明

    id

    String

    节点ID。

    name

    String

    节点名称。

    role

    String

    节点类型,取值为“master”、“slave”或“readreplica”,分别对应于主节点、备节点和只读节点。

    status

    String

    节点状态。

    availability_zone

    String

    可用区。

    表10 related_instance字段数据结构说明

    名称

    参数类型

    说明

    id

    String

    关联实例id。

    type

    String

    关联实例类型。

    • “replica_of”对应于“主实例”。
    • “replica”对应于“只读实例”。
    表11 tags字段数据结构说明

    名称

    参数类型

    说明

    key

    String

    标签键。

    value

    String

    标签值。

    响应样例中,“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"
    	}],
    	"private_ips": ["192.168.0.142"],
    	"public_ips": ["10.154.219.187", "10.154.219.186"],
    	"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": [],
    	"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"
    		}],
    		"private_ips": ["192.168.0.142"],
    		"public_ips": ["10.154.219.187", "10.154.219.186"],
    		"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": [],
    		"time_zone": "",
        		        "tags" [
         	       {
           		         "key": "rds001",
           		         "value": "001"
          		      },
         		       {
          		          "key": "rds002",
          		          "value": "002"
         		       }
       		      ]
    	}, {
    		"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in02",
    		"status": "ACTIVE",
    		"name": "mysql-0820-022709-02",
    		"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"
    		}],
    		"private_ips": ["192.168.0.142"],
    		"public_ips": ["10.154.219.187", "10.154.219.186"],
    		"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": [],
    		"time_zone": "",
        		        "tags" [
         	       {
           		         "key": "rds001",
           		         "value": "001"
          		      },
         		       {
          		          "key": "rds002",
          		          "value": "002"
         		       }
       		      ]
    	}],
    	"total_count": 2
    }
  • 异常响应

    请参见异常请求结果

状态码

请参见状态码

错误码

请参见错误码