Querying Instances and Details

Function

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

Constraints

This API supports the following instances:

GeminiDB Cassandra
GeminiDB Mongo
GeminiDB Influx
GeminiDB Redis

Authorization Information

Each account has permissions to call all APIs, but IAM users must have the required permissions specifically assigned.

If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
gaussdbfornosql:instance:list	Read	-	-	nosql:backup:list	-

URI

GET /v3/{project_id}/instances

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID. Constraints N/A Range N/A Default Value N/A

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
id	No	String	Definition Instance ID Constraints 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. Range* N/A Default Value N/A
name	No	String	Definition Instance name Constraints 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. Range* N/A Default Value N/A
datastore_type	No	String	Definition Database type Constraints N/A Range cassandra, indicating that GeminiDB Cassandra instances are queried. mongodb, indicating that GeminiDB Mongo instances are queried. influxdb, indicating that GeminiDB Influx instances are queried. redis, indicating that GeminiDB Redis instances are queried. Default Value If this parameter is not transferred, all types of instances are queried.
mode	No	String	Definition Instance type Constraints N/A Range Cluster: GeminiDB Cassandra or GeminiDB Influx cluster instance; proxy cluster GeminiDB Redis instance with classic storage CloudNativeCluster: GeminiDB Cassandra, Influx, or Redis cluster instance with cloud native storage RedisCluster: Redis Cluster GeminiDB Redis instance with classic storage Replication: primary/standby GeminiDB Redis instance with classic storage InfluxdbSingle: single-node GeminiDB Influx instance with classic storage EnhancedCluster: GeminiDB Influx cluster (performance-enhanced) instance with classic storage ReplicaSet: GeminiDB Mongo instance in a replica set The system ignores this parameter if datastore_type is not transferred. Default Value N/A
vpc_id	No	String	Definition VPC ID. You can obtain the value with either of the following methods: Method 1: Log in to the VPC console and find the VPC ID on the VPC details page. Method 2: Query the VPC ID using the VPC API. For details, see Querying VPCs. Constraints N/A Range N/A Default Value N/A
subnet_id	No	String	Definition Subnet ID. You can obtain the subnet ID with either of the following methods: Method 1: Log in to the VPC console, click a subnet under the VPC, and find the network ID on the subnet details page. Method 2: Query the subnet ID using the VPC API. For details, see Querying Subnets. Constraints N/A Range N/A Default Value N/A
offset	No	Integer	Definition 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. Constraints N/A Range The value must be no less than 0. Default Value 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	Definition Maximum number of instances that can be queried. Constraints N/A Range 1 to 100 Default Value 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	Definition User token You can obtain the token by calling the IAM API by following Obtaining a User Token Through Password Authentication. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
instances	Array of ListInstancesResult objects	Definition Instance information.
total_count	Integer	Definition Total number of records. Range N/A

**Table 5** ListInstancesResult
Parameter	Type	Description
id	String	Definition Instance ID Range N/A
name	String	Definition Instance name Range N/A
status	String	Definition Instance status Range normal: An instance is available. abnormal: An instance is abnormal. creating: An instance is being created. frozen: An instance is frozen. data_disk_full: An instance disk is full. createfail: An instance failed to be created. enlargefail: Instance nodes failed to be added.
port	String	Definition Database port Range N/A
mode	String	Definition Instance type Range This parameter is the same as the corresponding request parameter.
product_type	String	Definition Product type used for GeminiDB Redis instances with cloud native storage Range Standard Capacity Performance
region	String	Definition Region where an instance is deployed Range N/A
datastore	ListInstancesDatastoreResult object	Definition Database information
engine	String	Definition Storage engine Values: rocksDB
created	String	Definition Instance creation time Range N/A
updated	String	Definition Time when an instance is updated Range N/A
db_user_name	String	Definition Default username Range rwuser
vpc_id	String	Definition VPC ID Range N/A
subnet_id	String	Definition Subnet ID. Range One GeminiDB Cassandra instance may use multiple subnets. For the subnet ID, see Table 10.
security_group_id	String	Definition Security group ID. Range N/A
backup_strategy	ListInstancesBackupStrategyResult object	Definition Backup policy.
pay_mode	String	Definition Billing mode. Options: Range 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	Definition Maintenance time window. Range N/A
groups	Array of ListInstancesGroupResult objects	Definition Group information.
enterprise_project_id	String	Definition Enterprise project ID. Range 0: default enterprise project
time_zone	String	Definition Time zone. Range N/A
actions	Array of strings	Definition Operation that is executed on the instance. Example values: CREATE REBOOT RESTORE
dedicated_resource_id	String	Definition Dedicated resource ID. This parameter is returned only when the instance belongs to a dedicated resource pool. Range N/A
lb_ip_address	String	Definition Load balancer IP address Constraints: This parameter is returned only when a load balancer IP address is assigned. Range N/A
lb_port	String	Definition Load balancer port Constraints: This parameter is returned only when a load balancer IP address is assigned. Range N/A
availability_zone	String	Definition AZ Range N/A
dual_active_info	DualActiveInfo object	Definition Active-active instance information

**Table 6** ListInstancesDatastoreResult
Parameter	Type	Description
type	String	Definition Database API Range cassandra: GeminiDB Cassandra instance mongodb: GeminiDB Mongo instance influxdb: GeminiDB Influx instance redis: GeminiDB Redis instance
version	String	Definition Database version Range N/A
patch_available	Boolean	Definition Whether the current instance can be patched Range true: A database can be upgraded through a patching API. false: A database cannot be upgraded through a patching API.
whole_version	String	Definition Whole version of a GeminiDB Cassandra and Redis instance Values: N/A

**Table 7** ListInstancesBackupStrategyResult
Parameter	Type	Description
start_time	String	Definition Backup time window. Automated backup will be triggered during the backup time window. The current time is the UTC time. Values: N/A
keep_days	Integer	Definition Backup retention days Range 0–35

**Table 8** ListInstancesGroupResult
Parameter	Type	Description
id	String	Definition Group ID Values: N/A
status	String	Definition Group status Range normal: A group is normal. abnormal: A group is abnormal. creating: A group is being created. createfail: A group failed to be created. deleted: A group is deleted. resizefailed: The group specifications failed to be modified. enlargefail: A group failed to be scaled out.
volume	Volume object	Definition Volume information
nodes	Array of ListInstancesNodeResult objects	Definition Node information

**Table 9** Volume
Parameter	Type	Description
size	String	Definition Storage (GB) Values: N/A
used	String	Definition Used storage (GB) Values: N/A

**Table 10** ListInstancesNodeResult
Parameter	Type	Description
id	String	Definition Node ID Values: N/A
name	String	Definition Node name Values: N/A
status	String	Definition Node status Values: normal: A node is normal. abnormal: A node is abnormal. creating: A node is being created. createfail: A node failed to be created. deleted: A node is deleted. resizefailed: Node specifications failed to be changed. enlargefail: Nodes failed to be added.
role	String	Definition Node role Constraints This parameter is available only for GeminiDB MongoAPI replica set instances. Values: N/A
subnet_id	String	Definition ID of the subnet where the instance node is deployed Values: N/A
private_ip	String	Definition Private IP address of a node Constraints This parameter value is available after an ECS is created. Otherwise, the value is "". Values: N/A
public_ip	String	Definition Bound EIP Constraints This parameter is valid only for nodes bound with EIPs. Values: N/A
spec_code	String	Definition Resource specification code. For the code, see the value of parameter flavors.spec_code in Querying Instance Specifications. Values: N/A
availability_zone	String	Definition AZ Values: N/A
support_reduce	Boolean	Definition Whether instance nodes can be deleted Values: true: Instance nodes can be deleted. false: Instance nodes cannot be deleted.

**Table 11** DualActiveInfo
Parameter	Type	Description
role	String	Definition Active-active role Values: N/A
status	String	Definition Active-active status Values: normal: The active-active status is normal. abnormal: The active-active status is abnormal.
destination_instance_id	String	Definition ID of the peer instance in the active-active pair Values: N/A
destination_region	String	Definition Peer region of the active-active pair Values: N/A

Example Requests

URI example

Querying all instances and details

GET https://gaussdb-nosql.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances

URI example

Querying instances and details based on specified conditions

GET https://gaussdb-nosql.ap-southeast-1.myhuaweicloud.com/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

Successful response

{
  "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",
      "availability_zone": "cn-north-4a,cn-north-4b,cn-north-4c",
      "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
      },
      "nodes" : [ {
        "id" : "233eaac9c6f245c0bb9c2d21eea12d1bno02",
        "name" : "nosql-efa7_replica_node_2",
        "status" : "normal",
        "role" : "Primary",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.174",
        "public_ip" : "10.154.217.134",
        "spec_code" : "geminidb.mongodb.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "d57d76d6320a4a7b86db82c317550c4ano02",
        "name" : "nosql-efa7_replica_node_1",
        "status" : "normal",
        "role" : "Secondary",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.39",
        "spec_code" : "geminidb.mongodb.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "f46b0a1cf4d9400e9fd7af17f8742d37no02",
        "name" : "nosql-efa7_replica_node_3",
        "status" : "normal",
        "role" : "Secondary",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.176",
        "spec_code" : "geminidb.mongodb.xlarge.4",
        "availability_zone" : "bbb"
      } ]
    } ],
      "enterprise_project_id" : "0", 
      "availability_zone": "cn-north-4a,cn-north-4b,cn-north-4c",
      "time_zone" : "",
      "actions" : [ ]
  } ],
  "total_count" : 2
}