Function

This API is used to query instances according to search criteria. Before calling this API:

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

URI

URI format
GET https://{endpoint}/mysql/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}
Example
GET https://gaussdb-mysql.eu-de.otc.t-systems.com/mysql/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Cluster&datastore_type=gaussdb-mysql&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offset=0&limit=10

Parameter description

**Table 1** Parameter description
Name	Type	Mandatory	Description
project_id	String	Yes	Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID.
id	String	No	DB instance ID. The asterisk () is reserved for the system. If the instance ID starts with an asterisk (), the value following asterisk (*) is used for fuzzy matching. Otherwise, the instance ID is used for exact matching.
name	String	No	DB instance name. The asterisk () is reserved for the system. If the instance name starts with an asterisk (), the value following asterisk (*) is used for fuzzy matching. Otherwise, the instance name is used for exact matching.
type	String	No	DB instance type to be queried. Its value is Cluster.
datastore_type	String	No	DB type. Currently, only gaussdb-mysql is supported.
vpc_id	String	No	VPC ID. Method 1: Log in to the VPC console and view the VPC ID on the VPC details page. Method 2: See "Querying VPCs" in the Virtual Private Cloud API Reference.
subnet_id	String	No	Network ID of the subnet. Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page. Method 2: See section "Querying Subnets" under "APIs" or section "Querying Networks" under "OpenStack Neutron APIs" in the Virtual Private Cloud API Reference.
offset	Integer	No	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	Integer	No	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.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token.
X-Language	No	String	Language.
Content-Type	Yes	String	MIME type of the request body. You are advised to use the default value application/json. For APIs used to upload objects or images, the value can vary depending on the flow type.

Response Parameters

Status code: 200

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

**Table 4** MysqlInstanceListInfo
Parameter	Type	Description
id	String	DB instance ID.
name	String	DB instance name.
status	String	DB instance status.
private_ips	Array of strings	Private IP address for write. It is a blank string until an ECS is created.
public_ips	Array of strings	Public IP addresses.
port	String	Database port.
type	String	DB instance type. The value is Cluster.
region	String	Region where the DB instance is deployed.
datastore	MysqlDatastore object	Database information.
created	String	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. The value is empty unless the instance creation is complete.
updated	String	Update time. The format is the same as that of the created field. The value is empty unless the instance creation is complete.
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	Specification description.
volume	MysqlVolumeInfo object	Storage disk information.
backup_strategy	MysqlBackupStrategy object	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 5** MysqlDatastore
Parameter	Type	Description
type	String	DB engine. Currently, only gaussdb-mysql is supported.
version	String	DB version. To obtain details about supported DB engine versions, call the API for querying the DB engine versions.
kernel_version	String	Database kernel version.

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

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

**Table 8** MysqlBackupStrategy
Parameter	Type	Description
start_time	String	Automated backup start time. The automated backup will be triggered within one hour after the time specified by this parameter.
keep_days	String	Backup retention days.

**Table 9** MysqlChargeInfo
Parameter	Type	Description
charge_mode	String	Billing mode. Value: postPaid

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

Status code: 400

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

Status code: 500

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

Example Request

Querying DB Instances

GET https://gaussdb-mysql.eu-de.otc.t-systems.com/mysql/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Cluster&datastore_type=gaussdb-mysql&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offset=0&limit=10

Example Response

The value of region is used as an example in the following response.

Status code: 200

Success.

{
  "total_count" : 1,
  "instances" : [ {
    "id" : "ed7cc6166ec24360a5ed5c5c9c2ed726in01",
    "name" : "gaussdb-mysql-instance01",
    "status" : "ACTIVE",
    "port" : 3306,
    "type" : "Cluster",
    "private_ips" : [ "192.168.0.142" ],
    "db_user_name" : "root",
    "region" : "br-iaas-odin1",
    "datastore" : {
      "type" : "gaussdb-mysql",
      "version" : "8.0"
    },
    "created" : "2018-08-20T02:33:49_0800",
    "updated" : "2018-08-20T02:33:49_0800",
    "volume" : {
      "type" : "POOL",
      "used_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" : [ ]
  } ]
}

Status Code

For details, see Status Codes.

Error Code

For details, see Error Codes.