• Relational Database Service

rds
  1. Help Center
  2. Relational Database Service
  3. API Reference
  4. API v3 (Recommended)
  5. DB Instance Management
  6. Querying DB Instances Based on Specified Conditions

Querying DB Instances Based on Specified Conditions

Function

This API is used to query DB instances based on specified conditions.

URI

  • URI format

    PATH: /{version_id}/{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}

    Method: GET

  • Parameter description
    Table 1 Parameter description

    Name

    Type

    Mandatory

    Description

    version_id

    String

    Yes

    Specifies the API version. It is case-sensitive and the value is v3.

    project_id

    String

    Yes

    Specifies the project ID of a tenant in a region.

    id

    String

    No

    Specifies the DB instance ID.

    The asterisk (*) is reserved for the system. If the instance ID starts with *, it indicates that fuzzy match is performed based on the value following * Otherwise, the exact match is performed based on the instance ID. The value cannot contain only asterisks (*).

    name

    String

    No

    Specifies the DB instance name.

    The asterisk (*) is reserved for the system. If the instance name starts with *, it indicates that fuzzy match is performed based on the value following * Otherwise, the exact match is performed based on the instance name. The value cannot contain only asterisks (*).

    type

    String

    No

    Specifies the instance type based query. The value is Single, Ha, or Replica, which correspond to single instance, primary/standby instances, and read replica, respectively.

    datastore_type

    String

    No

    Specifies the database type. MySQL, PostgreSQL, and Microsoft SQL Server are supported. The value is MySQL, PostgreSQL, or SQLServer.

    vpc_id

    String

    No

    Indicates the VPC ID.

    subnet_id

    String

    No

    Specifies the subnet ID.

    offset

    Integer

    No

    Specifies the index position. If offset is set to N, the resource query starts from the N+1 piece of data. The value is 0 by default, indicating that the query starts from the first piece of data. The value must be a positive number.

    limit

    Integer

    No

    Specifies the number of resources to be queried. The default value is 100. The value cannot be a negative number. The minimum value is 1 and the maximum value is 100.

Example

Query all instances.

GET /v3/97b026aa9cc4417888c14c84a1ad9860/instances

Query DB instances based on specified conditions.

GET /v3/97b026aa9cc4417888c14c84a1ad9860/instances?offset=0&limit=10&id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Ha&datastore_type=MySQL&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7

Request

N/A

Normal Response

  • Parameter description
    Table 2 Parameter description

    Name

    Type

    Description

    instances

    List data structure

    Indicates the DB instance information.

    For details, see table 4 in section "Obtaining a DB Instance List."

    total_count

    Integer

    Indicates the total number of resources.

    Table 3 instances field data structure description

    Name

    Type

    Description

    id

    String

    Indicates the DB instance ID.

    name

    String

    Indicates the created DB instance name.

    status

    String

    Indicates the DB instance status.

    Value:

    If the value is BUILD, the instance is being created.

    If the value is ACTIVE, the instance is normal.

    If the value is FAILED, the instance is abnormal.

    If the value is MODIFYING, the instance is being scaled up.

    If the value is REBOOTING, the instance is being rebooted.

    If the value is RESTORING, the instance is being restored.

    If the value is MODIFYING INSTANCE TYPE, the instance is changing from primary to standby.

    If the value is SWITCHOVER, the primary/standby switchover is being performed.

    If the value is MIGRATING, the instance is being migrated.

    If the value is BACKING UP, the instance is being backed up.

    If the value is MODIFYING DATABASE PORT, the database port is being changed.

    private_ips

    List<String>

    Indicates the private IP address list. It is a blank string until an ECS is created.

    public_ips

    List<String>

    Indicates the public IP address list.

    port

    Int

    Indicates the database port number.

    • The MySQL database port ranges from 1024 to 65535 (excluding 12017 and 33071, which are occupied by the RDS system and cannot be used).
    • The PostgreSQL database port ranges from 2100 to 9500.
    • The Microsoft SQL Server database port can be 1433 or ranges from 2100 to 9500, excluding 5355 and 5985.

    If this parameter is not set, the default value is as follows:

    • For MySQL, the default value is 3306.
    • For PostgreSQL, the default value is 5432.
    • For Microsoft SQL Server, the default value is 1433.

    type

    String

    The value is Single, Ha, or Replica, which correspond to single instance, primary/standby instances, and read replica, respectively.

    ha

    Dictionary data structure

    Indicates the primary/standby DB instance information. Returned only when you obtain a primary/standby DB instance list.

    For details, see Table 4.

    region

    String

    Indicates the region where the DB instance is deployed.

    datastore

    Dictionary data structure

    Indicates the database information.

    For details, see Table 5.

    created

    String

    Indicates the creation time in the "yyyy-mm-ddThh:mm:ssZ" format.

    T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, in the Beijing time zone, the time zone offset is shown as +0800.

    The value is empty when the DB instance is being created. After the DB instance is created, the value is not empty.

    updated

    String

    Indicates the update time. The format is the same as that of the created field.

    The value is empty when the DB instance is being created. After the DB instance is created, the value is not empty.

    db_user_name

    String

    Indicates the default username.

    vpc_id

    String

    Indicates the VPC ID.

    subnet_id

    String

    Indicates the subnet ID.

    security_group_id

    String

    Indicates the security group ID.

    flavor_ref

    String

    Indicates the specification code.

    volume

    Dictionary data structure. For details, see Table 6.

    Indicates the volume information.

    switch_strategy

    String

    Indicates the database switchover policy. The value can be reliability or availability, indicating the reliability first and availability first, respectively.

    backup_strategy

    Dictionary data structure. For details, see Table 7.

    Indicates the backup policy.

    maintenance_window

    String

    Indicates the maintenance time window.

    nodes

    List data structure. For details, see Table 8.

    Indicates the primary/standby DB instance information.

    related_instance

    List data structure. For details, see Table 9.

    Indicates the list of associated DB instances.

    disk_encryption_id

    String

    Indicates the disk encryption key ID.

    time_zone

    String

    Indicates the time zone.

    Table 4 ha field data structure description

    Name

    Type

    Description

    replication_mode

    String

    Indicates the replication mode for the standby DB instance.

    The value cannot be empty.

    • For MySQL, the value is async or semisync.
    • For PostgreSQL, the value is async or sync.
    • For Microsoft SQL Server, the value is sync.
    NOTE:
    • async indicates the asynchronous replication mode.
    • semisync indicates the semi-synchronous replication mode.
    • sync indicates the synchronous replication mode.
    Table 5 datastore field data structure description

    Name

    Type

    Description

    type

    String

    Indicates the DB engine.

    version

    String

    Indicates the database version.

    Table 6 volume field data structure description

    Name

    Type

    Description

    type

    String

    Indicates the volume type.

    size

    Int

    Indicates the volume size.

    Table 7 backup_strategy field data structure description

    Name

    Type

    Description

    start_time

    String

    Indicates the backup time window. Automated backups will be triggered during the backup time window.

    The time is in the UTC format.

    keep_days

    Int

    Indicates the number of days to retain the generated backup files.

    The value range is from 0 to 732. If the value is 0, the automated backup policy is not configured or has been disabled.

    Table 8 nodes field data structure description

    Name

    Type

    Description

    id

    String

    Indicates the node ID.

    name

    String

    Indicates the node name.

    role

    String

    Indicates the node type. The value can be master, slave, or readreplica, indicating the primary node, standby node, and read replica node, respectively.

    status

    String

    Indicates the node status.

    availability_zone

    String

    Indicates the AZ.

    Table 9 related_instance field data structure description

    Name

    Type

    Description

    id

    String

    Indicates the associated DB instance ID.

    type

    String

    Indicates the associated DB instance type. The value can be replica_of or replica, indicating the primary DB instance and read replica, respectively.

  • Response example

    Single DB instance:

    "instances": [{
    	"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01",
    	"status": "ACTIVE",
    	"name": "mysql-0820-022709-01",
    	"port": 3306,
    	"type": "Single",
    	"region": "eu-de",
    	"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": "eu-de-01"
    	}],
    	"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": [],
    	"disk_encryption_id": "",
    	"time_zone": ""
    }], "total_count": 1
    }

    Primary/standby DB instances:

    {
    	"instances": [{
    		"id": "69c41685b4804565aba06af5bc910607in03",
    		"status": "ACTIVE",
    		"name": "Postgresql-001",
    		"port": 5432,
    		"type": "Ha",
    		"ha": {
    			"replication_mode": "sync"
    		},
    		"region": "eu-de",
    		"datastore": {
    			"type": "postgresql",
    			"version": "11.0"
    		},
    		"created": "2018-08-29T08:41:15+0800",
    		"updated": "2018-08-29T09:02:53+0800",
    		"volume": {
    			"type": "ULTRAHIGH",
    			"size": 80
    		},
    		"nodes": [{
    			"id": "c645bbb14d3e4393a628181a4120a6f4no03",
    			"name": "Postgresql-001_node1",
    			"role": "slave",
    			"status": "ACTIVE",
    			"availability_zone": "eu-de-01"
    		}, {
    			"id": "cc613893150748b8937439d3d8bc493cno03",
    			"name": "Postgresql-001_node0",
    			"role": "master",
    			"status": "ACTIVE",
    			"availability_zone": "eu-de-02"
    		}],
    		"private_ips": ["192.168.0.216"],
    		"public_ips": [],
    		"db_user_name": "root",
    		"vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7",
    		"subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef",
    		"security_group_id": "9f6c3c74-4af4-4e21-b835-ec20703d575b",
    		"flavor_ref": "",
    		"switch_strategy": "reliability",
    		"backup_strategy": {
    			"start_time": "00:00-01:00",
    			"keep_days": 0
    		},
    		"maintenance_window": "02:00-06:00",
    		"related_instance": [{
    			"id": "f13f5f9aac104e6e814a008684cd32e6in03",
    			"type": "replica"
    		}],
    		"disk_encryption_id": "",
    		"time_zone": ""
    	}],
    	"total_count": 1
    }

    Read replica:

    {
    	"instances": [{
    		"id": "879e29da174246c79915056686548044in01",
    		"status": "ACTIVE",
    		"name": "replica-001",
    		"port": 3306,
    		"type": "Replica",
    		"region": "eu-de",
    		"datastore": {
    			"type": "mysql",
    			"version": "5.7"
    		},
    		"created": "2018-08-29T06:55:03+0800",
    		"updated": "2018-08-29T06:55:05+0800",
    		"volume": {
    			"type": "ULTRAHIGH",
    			"size": 40
    		},
    		"nodes": [{
    			"id": "7bbe211966f8421ba71857545ec581e5no01",
    			"name": "replica-001_node0",
    			"role": "readreplica",
    			"status": "ACTIVE",
    			"availability_zone": "eu-de-01"
    		}],
    		"private_ips": ["192.168.1.158"],
    		"public_ips": [],
    		"db_user_name": "root",
    		"vpc_id": "324a98f1-1b72-44cd-b64f-293d94666cf7",
    		"subnet_id": "6ae75351-a044-4571-a3e1-7b218f0cfc67",
    		"security_group_id": "9f6c3c74-4af4-4e21-b835-ec20703d575b",
    		"flavor_ref": "",
    		"switch_strategy": "reliability",
    		"backup_strategy": {
    			"start_time": "00:00-01:00",
    			"keep_days": 0
    		},
    		"maintenance_window": "02:00-06:00",
    		"related_instance": [{
    			"id": "7e60a6bb042741079edfb21cddf7827din01",
    			"type": "replica_of"
    		}],
    		"disk_encryption_id": "",
    		"time_zone": "UTC+08:00"
    	}],
    	"total_count": 1
    }

Abnormal Response

For details, see Abnormal Request Results.