:original_name: gaussdb_04_0005.html .. _gaussdb_04_0005: Querying Instances ================== Function -------- This API is used to query DB instances according to search criteria. Before using this API: - Learn how to :ref:`authorize and authenticate ` it. - Obtain the required :ref:`region and endpoint `. URI --- GET /v3/{project_id}/instances .. table:: **Table 1** URI parameters +-----------------+-----------------+-----------------+----------------------------------------------------------------------------+ | Parameter | Mandatory | Type | Description | +=================+=================+=================+============================================================================+ | project_id | Yes | String | Project ID of a tenant in a region. | | | | | | | | | | To obtain this value, see :ref:`Obtaining a Project ID `. | +-----------------+-----------------+-----------------+----------------------------------------------------------------------------+ .. table:: **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. | | | | | | | | | | - Method 1: Log in to VPC console and view the VPC ID in the VPC details. | | | | | - Method 2: See the "Querying VPCs" section in the *Virtual Private Cloud API Reference*. | +-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | subnet_id | No | String | Network ID of the subnet. | | | | | | | | | | - Method 1: Log in to VPC console and click the target subnet on the **Subnets** page. You can view the network ID on the displayed page. | | | | | - Method 2: See the "Querying Subnets" section under "APIs" or the "Querying Networks" section under "OpenStack Neutron APIs" in the *Virtual Private Cloud API Reference*. | +-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | private_ip | No | String | Private 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 | Query based on the instance tag key and value. *{key}* indicates the tag key, and *{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:: **Table 3** Request header parameters ============ ========= ====== =========== Parameter Mandatory Type Description ============ ========= ====== =========== X-Auth-Token Yes String User token. X-Language No String Language. ============ ========= ====== =========== Response Parameters ------------------- **Status code: 200** .. table:: **Table 4** Response body parameters +-------------+-------------------------------------------------------------------------------------------------+----------------------------+ | Parameter | Type | Description | +=============+=================================================================================================+============================+ | instances | Array of :ref:`MysqlInstanceListInfo ` objects | Instance list information. | +-------------+-------------------------------------------------------------------------------------------------+----------------------------+ | total_count | Integer | Total number of records. | +-------------+-------------------------------------------------------------------------------------------------+----------------------------+ .. _gaussdb_04_0005__response_mysqlinstancelistinfo: .. table:: **Table 5** MysqlInstanceListInfo +-----------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Parameter | Type | Description | +=======================+=====================================================================================+=====================================================================================================================================================================================================================================+ | id | String | Instance ID. | +-----------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | name | String | Instance name. | +-----------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | status | String | 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 | :ref:`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 | :ref:`MysqlFlavorInfo ` object | Flavor information. | +-----------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | volume | :ref:`MysqlVolumeInfo ` object | Storage disk information. | +-----------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | backup_strategy | :ref:`MysqlBackupStrategy ` object | Automated backup policy. | +-----------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | time_zone | String | Time zone. | +-----------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 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 :ref:`InstanceTagItem ` objects | Tag list. | +-----------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. _gaussdb_04_0005__response_mysqldatastore: .. table:: **Table 6** MysqlDatastoreWithKernelVersion +-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------+ | 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. | +-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------+ .. _gaussdb_04_0005__response_mysqlflavorinfo: .. table:: **Table 7** MysqlFlavorInfo ========= ====== ================== Parameter Type Description ========= ====== ================== vcpus String Number of vCPUs. ram String Memory size in GB. ========= ====== ================== .. _gaussdb_04_0005__response_mysqlvolumeinfo: .. table:: **Table 8** MysqlVolumeInfo ========= ====== ===================== Parameter Type Description ========= ====== ===================== type String Disk type. size String Used disk size in GB. ========= ====== ===================== .. _gaussdb_04_0005__response_mysqlbackupstrategy: .. table:: **Table 9** 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. | | | | | | | | 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: 1-732. | +-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------+ .. _gaussdb_04_0005__response_instancetagitem: .. table:: **Table 10** InstanceTagItem ========= ====== =========== Parameter Type Description ========= ====== =========== key String Tag key. value String Tag value. ========= ====== =========== **Status code: 400** .. table:: **Table 11** Response body parameters ========== ====== ============== Parameter Type Description ========== ====== ============== error_code String Error code. error_msg String Error message. ========== ====== ============== **Status code: 500** .. table:: **Table 12** Response body parameters ========== ====== ============== Parameter Type Description ========== ====== ============== error_code String Error code. error_msg String Error message. ========== ====== ============== Example Request --------------- Querying instances .. code-block:: text GET https://{Endpoint}/v3/054e292c9880d4992f02c0196d3ea468/instances?id=61a4ea66210545909d74a05c27a7179ein07&name=hyAbc&type=Cluster&datastore_type=gaussdb-mysql&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&private_ip=192.168.0.142&offset=0&limit=10&tags=taurusKey1=value1 Example Response ---------------- **Status code: 200** .. note:: The value of **region** is used as an example in the following response. Success. .. code-block:: { "total_count" : 1, "instances" : [ { "id" : "d738399de028480fabb2b8120d4e01a4in07", "name" : "gaussdb-mysql-instance01", "status" : "ACTIVE", "port" : 3306, "type" : "Cluster", "private_ips" : [ "192.168.0.142" ], "db_user_name" : "root", "region" : "aaa", "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" : [ ] } ] } Status Code ----------- For details, see :ref:`Status Codes `. Error Code ---------- For details, see :ref:`Error Codes `.