Help Center/ GeminiDB/ API Reference/ APIs v3/ Instances/ Querying Instances and Details
Updated on 2023-11-21 GMT+08:00
View PDF

Querying Instances and Details

Function

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

Constraints

This API supports the following types of instances:

  • GeminiDB Cassandra
  • GeminiDB Influx
  • GeminiDB Redis

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 GeminiDB Cassandra instances are queried.

influxdb, indicating that GeminiDB Influx instances are queried.

redis, indicating that GeminiDB Redis instances are queried.

mode

No

String

Instance type. The value can be:

Cluster, indicating that the instance is a GeminiDB Cassandra, GeminiDB Influx, or GeminiDB Redis replica set instance.

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: Query the VPC ID using the VPC API. For details, see Querying VPCs.

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: Query the network ID using the VPC API. For details, see Querying Subnets.

offset

No

Integer

Index position. 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 GeminiDB 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

Billing mode. Options:

  • 0: indicates the instance is billed on a pay-per-use basis.
  • 1: indicates the instance is billed on a yearly/monthly basis.

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 API.

version

String

DB version number.

whole_version

String

Complete database version number. This parameter is available only to GeminiDB 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 normal.
  • 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.
  • enlargefail: 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.
  • deleted, 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://gaussdb-nosql.eu-west-101.myhuaweicloud.eu/v3/0483b6b16e954cb88930a360d2c4e663/instances
  • URI example

    Querying instances and details based on specified conditions

    GET https://gaussdb-nosql.eu-west-101.myhuaweicloud.eu/v3/0483b6b16e954cb88930a360d2c4e663/instances?offset=0&limit=10&id=ed7cc6166ec24360a5ed5c5c9c2ed726in06&name=hy&mode=Cluster&datastore_type=cassandra&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7

Example Responses

Status code: 200

Success

{
  "instances" : [ {
    "id" : "8436a91546294036b75931e879882200in06",
    "name" : "nosql-efa6",
    "status" : "normal",
    "port" : "8635",
    "mode" : "Cluster",
    "region" : "aaa",
    "datastore" : {
      "type" : "Cassandra",
      "version" : "3.11",
      "whole_version" : "3.11.3.11204", 
      "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" : 10,
        "used" : 0.33
      },
      "nodes" : [ {
        "id" : "233eaac9c6f245c0bb9c2d21eea12d1bno06",
        "name" : "nosql-efa6_priam_node_1",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.174",
        "spec_code" : "geminidb.redis.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "d57d76d6320a4a7b86db82c317550c4ano06",
        "name" : "nosql-efa6_priam_node_2",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.175",
        "spec_code" : "geminidb.redis.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "f46b0a1cf4d9400e9fd7af17f8742d37no06",
        "name" : "nosql-efa6_priam_node_3",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.176",
        "spec_code" : "geminidb.redis.xlarge.4",
        "availability_zone" : "bbb"
      } ]
    } ],
      "enterprise_project_id" : "0",
      "time_zone" : "",
      "actions" : [ "CREATE" ],
      "lb_ip_address" : "192.168.11.145",
      "lb_port" : "8635"
  }, {
    "id" : "1236a91546294036b75931e879882200in02",
    "name" : "nosql-efa7",
    "status" : "normal",
    "port" : "8635",
    "mode" : "ReplicaSet",
    "region" : "aaa",
    "datastore" : {
      "type" : "ReplicaSet",
      "version" : "4.0",
      "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" : "0b0ff12541794e1084f6827e424be2d1gr02",
      "status" : "normal",
      "volume" : {
        "size" : 100,
        "used" : 0.003
      },
    } ],
      "enterprise_project_id" : "0", 
      "time_zone" : "",
      "actions" : [ ]
  } ],
  "total_count" : 2
}

Status Codes

For details, see Status Codes.

Error Codes

For details, see Error Codes.

Parent topic: Instances