Querying Instances and Details¶

Function¶

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

Constraints¶

This API supports GaussDB(for Cassandra) instances.

URI¶

GET https://{Endpoint}/v3/{project_id}/instances

**Table 1** Path parameters¶
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. If you enter an instance ID starting with an asterisk (`*`), fuzzy search results are returned. If you enter a valid instance ID, an exact result is returned.
name	No	String	Instance name. If you enter an instance name starting with an asterisk (`*`), fuzzy search results are returned. If you enter a valid instance name, an exact result is returned.
datastore_type	No	String	Database type. The value can be: cassandra, indicating that GaussDB(for Cassandra) instances are queried. If this parameter is not transferred, all types of instances are queried.
mode	No	String	Instance type. The value can be: Cluster, indicating GaussDB(for Cassandra) cluster instances. The system ignores this parameter if parameter datastore_type is not transferred.
vpc_id	No	String	VPC ID. You can obtain the value with 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: See section "Querying VPCs" in the Virtual Private Cloud API Reference.
subnet_id	No	String	Subnet ID. You can obtain the subnet ID with 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 network ID on the displayed page. Method 2: See section "Querying Subnets" in the Virtual Private Cloud API Reference.
offset	No	Integer	Index offset. The query starts from the next instance creation time indexed by this parameter under a specified project. If offset is set to N, the resource query starts from the N+1 piece of data. The value must be no less than 0. If this parameter is not transferred, the index offset is 0 by default, indicating that the query starts from the latest created instance.
limit	No	Integer	Maximum number of instances that can be queried. The value ranges from 1 to 100. If this parameter is not transferred, the first 100 instances are queried by default.

Request Parameters¶

**Table 3** Request header parameters¶
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token.

Response Parameters¶

Status code: 200

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

**Table 5** ListInstancesResult¶
Parameter	Type	Description
id	String	Instance ID.
name	String	Instance name.
status	String	Instance status. The value can be: normal, indicating that the instance is running normally. abnormal, indicating that the instance is abnormal. creating, indicating that the instance is being created. frozen, indicating that the instance is frozen. data_disk_full, indicating that the instance disk is full. createfail, indicating that the instance failed to be created. enlargefail, indicating that nodes failed to be added to the instance.
port	String	Database port.
mode	String	Instance type. This parameter is the same as the corresponding request parameter.
region	String	Region where the instance is deployed.
datastore	ListInstancesDatastoreResult object	Database information.
engine	String	Storage engine. The value is rocksDB.
created	String	Instance creation time.
updated	String	Time when an instance is updated.
db_user_name	String	Default username. The value is rwuser.
vpc_id	String	VPC ID.
subnet_id	String	Subnet ID. One GaussDB(for Cassandra) instance may use multiple subnets. For the subnet ID, see Table 10.
security_group_id	String	Security group ID.
backup_strategy	ListInstancesBackupStrategyResult object	Backup policy.
pay_mode	String	The value is 0.
maintenance_window	String	Maintenance time window.
groups	Array of ListInstancesGroupResult objects	Group information.
enterprise_project_id	String	Enterprise project ID. If you set this parameter to 0, the resource belongs to the default enterprise project.
time_zone	String	Time zone.
actions	Array of strings	Operation that is executed on the instance. Example values: CREATE REBOOT RESTORE

**Table 6** ListInstancesDatastoreResult¶
Parameter	Type	Description
type	String	DB engine.
version	String	DB version number.
whole_version	String	Complete database version number. This parameter is available only to GaussDB(for Cassandra).

**Table 7** ListInstancesBackupStrategyResult¶
Parameter	Type	Description
start_time	String	Backup time window. Automated backup will be triggered during the backup time window. The current time is the UTC time.
keep_days	Integer	Backup retention days. The value ranges from 0 to 35.

**Table 8** ListInstancesGroupResult¶
Parameter	Type	Description
id	String	Group ID.
status	String	Group status. The value can be: normal, indicating that the group is running normally. abnormal, indicating that the group is abnormal. creating, indicating that the group is being created. createfail, indicating that the group failed to be created. deleted: indicating that the group has been deleted. resizefailed: indicating that the group specifications failed to be changed. expandFail: indicating the group failed to be scaled out.
volume	Volume object	Volume information.
nodes	Array of ListInstancesNodeResult objects	Node information.

**Table 9** Volume¶
Parameter	Type	Description
size	String	Storage space in GB.
used	String	Used storage space, in GB.

**Table 10** ListInstancesNodeResult¶
Parameter	Type	Description
id	String	Node ID.
name	String	Node name.
status	String	Node status. The value can be: normal, indicating that the node is running normally. abnormal, indicating that the node is abnormal. creating, indicating that the node is being created. createfail, indicating that the node failed to be created. createfail, indicating that the node has been deleted. resizefailed: indicating that the node specifications failed to be changed. enlargefail: indicating nodes failed to be added.
subnet_id	String	ID of the subnet where the instance node is deployed.
private_ip	String	Private IP address of the node. This parameter value is available after an ECS is created. Otherwise, the value is "".
public_ip	String	Bound EIP. This parameter is valid only for nodes bound with EIPs.
spec_code	String	Resource specification code. For the code, see the value of parameter flavors.spec_code in Querying Instance Specifications.
availability_zone	String	AZ.
support_reduce	Boolean	Whether instance nodes can be deleted. The value can be: true, indicating that instance nodes can be deleted. false, indicating that instance nodes cannot be deleted.

Example Requests¶

URI example

Querying all instances and details

GET https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances

URI example

Querying instances and details based on specified conditions

GET https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances?offset=0&limit=10&id=ed7cc6166ec24360a5ed5c5c9c2ed726in06&name=hy&mode={mode}&datastore_type={datastore_type}&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7

Example Responses¶

Status code: 200

Success

{
  "instances" : [ {
    "id" : "8436a91546294036b75931e879882200in06",
    "name" : "nno-efa6",
    "status" : "normal",
    "port" : "8635",
    "mode" : "Cluster",
    "region" : "aaa",
    "datastore" : {
      "type" : "cassandra",
      "version" : "3.11",
      "patch_available" : false
    },
    "engine" : "rocksDB",
    "created" : "2019-01-17T07:05:52",
    "updated" : "2019-01-17T07:05:47",
    "db_user_name" : "rwuser",
    "vpc_id" : "674e9b42-cd8d-4d25-a2e6-5abcc565b961",
    "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
    "security_group_id" : "7aa51dbf-5b63-40db-9724-dad3c4828b58",
    "backup_strategy" : {
      "start_time" : "16:00-17:00",
      "keep_days" : 7
    },
    "pay_mode" : 0,
    "maintenance_window" : "02:00-06:00",
    "groups" : [ {
      "id" : "0b0ff12541794e1084f6827e424be2d6gr06",
      "status" : "creating",
      "volume" : {
        "size" : 100,
        "used" : 0.003
      },
      "nodes" : [ {
        "id" : "233eaac9c6f245c0bb9c2d21eea12d1bno06",
        "name" : "nosql-efa6_priam_node_2",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.174",
        "spec_code" : "geminidb.cassandra.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "d57d76d6320a4a7b86db82c317550c4ano02",
        "name" : "nosql-efa6_priam_node_1",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.39",
        "spec_code" : "geminidb.cassandra.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "f46b0a1cf4d9400e9fd7af17f8742d37no02",
        "name" : "nosql-efa6_priam_node_3",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.176",
        "spec_code" : "geminidb.cassandra.xlarge.4",
        "availability_zone" : "bbb"
      } ]
    } ],
      "enterprise_project_id" : "0",
      "time_zone" : "",
      "actions" : [ "CREATE" ]
  }, {
    "id" : "1236a91546294036b75931e879882200in06",
    "name" : "nosql-efa7",
    "status" : "Cluster",
    "port" : "8635",
    "mode" : "ReplicaSet",
    "region" : "aaa",
    "datastore" : {
      "type" : "cassandra",
      "version" : "3.11",
      "patch_available" : false
    },
    "engine" : "rocksDB",
    "created" : "2019-01-17T07:05:52",
    "updated" : "2019-01-17T07:05:47",
    "db_user_name" : "rwuser",
    "vpc_id" : "674e9b42-cd8d-4d25-a2e6-5abcc565b961",
    "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
    "security_group_id" : "7aa51dbf-5b63-40db-9724-dad3c4828b58",
    "backup_strategy" : {
      "start_time" : "16:00-17:00",
      "keep_days" : 7
    },
    "pay_mode" : 0,
    "maintenance_window" : "02:00-06:00",
    "groups" : [ {
      "id" : "0b0ff12541794e1084f6827e424be2d1gr07",
      "status" : "creating",
      "volume" : {
        "size" : 100,
        "used" : 0.003
      },
      "nodes" : [ {
        "id" : "233eaac9c6f245c0bb9c2d21eea12d1bno06",
        "name" : "nosql-efa7_priam_node_2",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.174",
        "spec_code" : "geminidb.cassandra.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "d57d76d6320a4a7b86db82c317550c4ano02",
        "name" : "nosql-efa7_priam_node_1",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.39",
        "spec_code" : "geminidb.cassandra.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "f46b0a1cf4d9400e9fd7af17f8742d37no02",
        "name" : "nosql-efa7_prima_node_3",
        "status" : "normal",
        "role" : "Secondary",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.176",
        "spec_code" : "geminidb.cassandra.xlarge.4",
        "availability_zone" : "bbb"
      } ]
    } ],
      "enterprise_project_id" : "0",
      "time_zone" : "",
      "actions" : [ "CREATE" ]
  } ],
  "total_count" : 2
}

Status Codes¶

For details, see Status Codes.

Error Codes¶

For details, see Error Codes.

last updated: 2024-07-25 00:37