Querying DB instances

Function

This API is used to query DB instances according to search 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	Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID.

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
id	No	String	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	No	String	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	No	String	Instance type to be queried. Currently, only the cluster type is supported.
datastore_type	No	String	DB type. Currently, only gaussdb-mysql is supported.
vpc_id	No	String	VPC ID.
subnet_id	No	String	Network ID of the subnet.
private_ip	No	String	Private IP address.
readonly_private_ip	No	String	Private IP address for read.
proxy_ip	No	String	Proxy IP address.
offset	No	Integer	Index offset. 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 cannot be a negative number.
limit	No	Integer	Number of records to be queried. The default value is 100. The value must be a positive integer. The minimum value is 1 and the maximum value is 100.
tags	No	String	Queries based on the instance tag keys and values. {key} indicates the tag key. {value} indicates the tag value. 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.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the token value.
X-Language	No	String	Request language type. The default value is en-us. Values: en-us zh-cn

Response Parameters

Status code: 200

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

**Table 5** MysqlInstanceListInfoUnifyStatus
Parameter	Type	Description
id	String	Instance ID, which is compliant with the UUID format.
name	String	Instance name.
status	String	Instance status. Values: creating: The DB instance is being created. normal: The instance is running properly. abnormal: The instance is abnormal. createfail: The instance failed to be created.
private_ips	Array of strings	Private IP addresses for write. It is left blank until an ECS is created.
proxy_ips	Array of strings	Proxy IP addresses. It is left blank until proxy instances are created for a DB instance.
readonly_private_ips	Array of strings	Private IP addresses for read. It is left blank until an ECS is created.
public_ips	Array of strings	EIPs.
port	String	Database port.
type	String	Instance type. The value is Cluster.
region	String	Region where the DB instance is deployed.
datastore	MysqlDatastoreWithKernelVersion object	Database information.
created	String	Creation time. The format is yyyy-mm-ddThh:mm:ssZ. 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.
updated	String	Update time. The format is the same as that of the created field.
db_user_name	String	Default username.
vpc_id	String	VPC ID.
subnet_id	String	Network ID of the subnet.
security_group_id	String	Security group ID.
flavor_ref	String	Specification code.
flavor_info	MysqlFlavorInfo object	Flavor information.
volume	MysqlVolumeInfo object	Storage disk information.
backup_strategy	MysqlBackupStrategy object	Automated backup policy.
enterprise_project_id	String	Enterprise project ID.
time_zone	String	Time zone.
charge_info	MysqlChargeInfo object	Billing mode, which is yearly/monthly or pay-per-use (default setting).
dedicated_resource_id	String	Dedicated resource pool ID. This parameter is returned only when the instance belongs to a dedicated resource pool.
tags	Array of InstanceTagItem objects	Tag list.

**Table 6** MysqlDatastoreWithKernelVersion
Parameter	Type	Description
type	String	DB engine. Currently, only gaussdb-mysql is supported.
version	String	DB version.
kernel_version	String	Database kernel version.

**Table 7** MysqlFlavorInfo
Parameter	Type	Description
vcpus	String	Number of vCPUs.
ram	String	Memory size in GB.

**Table 8** MysqlVolumeInfo
Parameter	Type	Description
type	String	Disk type.
size	String	Used disk size in GB.

**Table 9** MysqlBackupStrategy
Parameter	Type	Description
start_time	String	Automated backup start time. The creation of an automated backup will be triggered within one hour after the time specified by this parameter. The value cannot be empty. It must be a valid value in the "hh:mm-HH:MM" format. The current time is in the UTC format. 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.
keep_days	String	Automated backup retention days. Value range: 1–732.

**Table 10** MysqlChargeInfo
Parameter	Type	Description
charge_mode	String	Billing mode. Values: prePaid: indicates the yearly/monthly billing mode. postPaid: indicates the pay-per-use billing mode. Values: prePaid postPaid
period_type	String	Subscription period. Values: month: The service is subscribed by month. year: The service is subscribed by year. This parameter is available and mandatory only when charge_mode is set to prePaid. Values: month year
period_num	Integer	This parameter is available and mandatory only when charge_mode is set to prePaid. Values: When period_type is set to month, the parameter value ranges from 1 to 9. When period_type is set to year, the parameter value ranges from 1 to 3.
is_auto_renew	String	Whether automatic renewal is enabled for yearly/monthly DB instances. The renewal period is the same as the original period and the order will be automatically paid during the subscription renewal. true: indicates that automatic renewal is enabled. false: indicates that automatic renewal is disabled. The default value is false.
is_auto_pay	String	Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment method of automatic renewal. true: indicates the order will be automatically paid from your account. The default value is true. false: indicates the order will be manually paid.

**Table 11** InstanceTagItem
Parameter	Type	Description
key	String	Tag key.
value	String	Tag value.

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 GaussDB(for MySQL) 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"
    } ]
  } ]
}