Querying DB Instances

Function

This API is used to query DB instances based on specified criteria. Before calling this API:

Learn how to authorize and authenticate it.
Obtain the required region and endpoint.

URI

GET /v3.1/{project_id}/instances

**Table 1** URI parameter
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID. Constraints N/A Range The value contains 32 characters. Only letters and digits are allowed. Default Value N/A

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
id	No	String	Definition Instance ID. Constraints 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, exact match is performed based on the instance ID. The value cannot contain only asterisks (). Range N/A Default Value N/A
name	No	String	Definition Instance name. Constraints 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, exact match is performed based on the instance name. The value cannot contain only asterisks (). Range N/A Default Value N/A
type	No	String	Definition Instance type. Constraints Currently, only the cluster type is supported. Range Cluster Default Value Cluster
datastore_type	No	String	Definition Database type. Constraints Only gaussdb-mysql is supported. Range gaussdb-mysql Default Value gaussdb-mysql
vpc_id	No	String	Definition VPC ID. To obtain this value, use either of the following methods: Method 1: Log in to the VPC console and view the VPC ID on the VPC details page. Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs. Constraints N/A Range N/A Default Value N/A
subnet_id	No	String	Definition Subnet ID. To obtain this value, use either of the following methods: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the subnet ID on the displayed page. Method 2: Query the subnet ID through the VPC API. For details, see Querying Subnets. Constraints N/A Range N/A Default Value N/A
private_ip	No	String	Definition Private IP address. Constraints N/A Range N/A Default Value N/A
readonly_private_ip	No	String	Definition Private IP address for read. Constraints N/A Range N/A Default Value N/A
proxy_ip	No	String	Definition Proxy IP address. Constraints N/A Range N/A Default Value N/A
offset	No	Integer	Definition Index offset. The query starts from the next piece of data indexed by this parameter. Constraints The value cannot be a negative number. Range ≥ 0 Default Value 0
limit	No	Integer	Definition Number of records to be queried. Constraints The value cannot be a negative number. Range 1–100 Default Value 100
tags	No	String	Definition Tag key–value pairs of the instance. {key} indicates the tag key. {value} indicates the tag value. Constraints To query instances with multiple tag keys and values, separate key-value pairs with commas (,). The key must be unique. Multiple keys are in AND relationship. Range N/A Default Value N/A

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. To obtain this value, call the IAM API for obtaining a user token. The value of X-Subject-Token in the response header is the token value. Constraints N/A Range N/A Default Value N/A
X-Language	No	String	Definition Request language type. Constraints N/A Range en-us zh-cn Default Value en-us

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
instances	Array of MysqlInstanceListInfoUnifyStatus objects	Definition Instance list.
total_count	Integer	Definition Total number of records. Range N/A

**Table 5** MysqlInstanceListInfoUnifyStatus
Parameter	Type	Description
id	String	Definition Instance ID. Range The value contains 36 characters with a suffix of in07. Only letters and digits are allowed.
name	String	Definition Instance name. Range N/A
status	String	Definition Instance status. Range creating: An instance is being created. normal: An instance is available. abnormal: An instance is abnormal. createfail: An instance failed to be created.
private_ips	Array of strings	Definition Private IP addresses for write of instances. This parameter is left blank until an ECS is created. Range N/A
proxy_ips	Array of strings	Definition Proxy IP addresses. This parameter is left blank until proxy instances are created for a DB instance. Range N/A
readonly_private_ips	Array of strings	Definition Private IP addresses for read of instances. This parameter is left blank until an ECS is created. Range N/A
public_ips	Array of strings	Definition Public IP addresses. Range N/A
port	String	Definition Database port. Range 1024 to 65535, excluding 5342 to 5345, 12017, 20000, 20201, 20202, 33062, and 33071
type	String	Definition Instance type. Range Cluster
region	String	Definition Region where an instance is deployed. Range N/A
datastore	MysqlDatastoreWithKernelVersion object	Definition Database information.
created	String	Definition 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, if the time zone offset is one hour, the value of Z is +0100. Range N/A
updated	String	Definition Update 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, if the time zone offset is one hour, the value of Z is +0100. Range N/A
db_user_name	String	Definition Default username. Range N/A
vpc_id	String	Definition VPC ID. Range N/A
subnet_id	String	Definition Subnet ID. Range N/A
security_group_id	String	Definition Security group ID. Range N/A
flavor_ref	String	Definition Specification code. Range N/A
flavor_info	MysqlFlavorInfo object	Definition Flavor information. Range N/A
volume	MysqlVolumeInfo object	Definition Storage disk information.
backup_strategy	MysqlBackupStrategy object	Definition Automated backup policy. Constraints N/A
enterprise_project_id	String	Definition Enterprise project ID. Range N/A
time_zone	String	Definition Time zone. Range N/A
charge_info	MysqlChargeInfo object	Definition Billing mode, which is yearly/monthly or pay-per-use (default setting).
dedicated_resource_id	String	Definition Dedicated resource pool ID. This parameter is only returned when the instance belongs to a dedicated resource pool. Range N/A
tags	Array of InstanceTagItem objects	Definition Tag list.

**Table 6** MysqlDatastoreWithKernelVersion
Parameter	Type	Description
type	String	Definition DB engine. Range gaussdb-mysql
version	String	Definition DB version. Range N/A
kernel_version	String	Definition DB kernel version. Range N/A

**Table 7** MysqlFlavorInfo
Parameter	Type	Description
vcpus	String	Definition Number of vCPUs. Range N/A
ram	String	Definition Memory size, in GB. Range N/A

**Table 8** MysqlVolumeInfo
Parameter	Type	Description
type	String	Definition Disk type. Range N/A
size	String	Definition Used disk size, in GB. Range N/A

**Table 9** MysqlBackupStrategy
Parameter	Type	Description
start_time	String	Definition Automated backup start time. An automated backup will be triggered within one hour after the time specified by this parameter. Constraints N/A Range The value cannot be empty. It must be a valid value in the "hh:mm-HH:MM" format. The current time is the UTC time. The HH value must be 1 greater than the hh value. The values of mm and MM must be the same and must be set to 00. Default Value N/A
keep_days	String	Definition Retention days of automated backups. Constraints The value must be a positive integer. Range 1–732 Default Value N/A

**Table 10** MysqlChargeInfo
Parameter	Type	Description
charge_mode	String	Definition Billing mode. Constraints N/A Range prePaid: yearly/monthly postPaid: pay-per-use Default Value postPaid
period_type	String	Definition Subscription period type in yearly/monthly mode. Constraints This parameter is only valid and mandatory when charge_mode is set to prePaid. Range month: The service is subscribed by month. year: The service is subscribed by year. Default Value N/A
period_num	Integer	Definition Subscription period in yearly/monthly mode. Constraints This parameter is only valid and mandatory when charge_mode is set to prePaid. Range When period_type is set to month, the value range is 1 to 9. When period_type is set to year, the value range is 1 to 3. Default Value N/A
is_auto_renew	String	Definition Whether automatic renewal is enabled for yearly/monthly instances. The renewal period is the same as the original period and the order will be automatically paid during the subscription renewal. Constraints This parameter is only valid when charge_mode is set to prePaid. Range true: Automatic renewal is enabled. false: Automatic renewal is disabled. Default Value false
is_auto_pay	String	Definition Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment method of automatic renewal. Constraints This parameter is only valid when charge_mode is set to prePaid. Range true: The order will be automatically paid. false: The order will be manually paid. Default Value true

**Table 11** InstanceTagItem
Parameter	Type	Description
key	String	Definition Tag key. Range N/A
value	String	Definition Tag value. Range N/A

Status code: 400

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 500

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Request

Querying TaurusDB instances whose private IP addresses are 192.*.*.*

GET https://{endpoint}/v3.1/054e292c9880d4992f02c0196d3ea468/instances?id=61a4ea66210545909d74a05c27a7179ein07&name=gaussdb-mysql-instance01&type=Cluster&datastore_type=gaussdb-mysql&vpc_id=3cedfc54-b105-4652-a4e0-847b11576b58&subnet_id=c1cfa53c-65d3-431e-8552-326bf310c7ad&private_ip=192.*.*.*&offset=0&limit=10&tags=taurusKey1=value1

Example Response

Status code: 200

Success.

{
  "total_count" : 1,
  "instances" : [ {
    "id" : "61a4ea66210545909d74a05c27a7179ein07",
    "name" : "gaussdb-mysql-instance01",
    "status" : "normal",
    "port" : 3306,
    "type" : "Cluster",
    "private_ips" : [ "192.*.*.*" ],
    "readonly_private_ips" : [ "192.*.*.*", "192.*.*.*" ],
    "proxy_ips" : [ "192.*.*.*" ],
    "db_user_name" : "root",
    "region" : "region-1",
    "datastore" : {
      "type" : "gaussdb-mysql",
      "version" : "8.0",
      "kernel_version" : "2.0.29.1"
    },
    "created" : "2018-08-20T02:33:49_0800",
    "updated" : "2018-08-20T02:33:49_0800",
    "volume" : {
      "type" : "POOL",
      "size" : 100
    },
    "vpc_id" : "3cedfc54-b105-4652-a4e0-847b11576b58",
    "subnet_id" : "c1cfa53c-65d3-431e-8552-326bf310c7ad",
    "security_group_id" : "fc577a1a-f202-424a-977f-24faec3fdd55",
    "flavor_ref" : "gaussdb.mysql.c3.small.4",
    "flavor_info" : {
      "vcpus" : 8,
      "ram" : 16
    },
    "backup_strategy" : {
      "start_time" : "19:00-20:00",
      "keep_days" : 7
    },
    "charge_info" : {
      "charge_mode" : "postPaid"
    },
    "enterprise_project_id" : 0,
    "time_zone" : "UTC",
    "tags" : [ {
      "key" : "Key1",
      "value" : "value1"
    } ]
  } ]
}