Querying Instances and Details

API Description

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

URI

URI format
GET https://{Endpoint}/v3/{project_id}/instances?id={id}&name={name}&mode={mode}&datastore_type={datastore_type}&vpc_id={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit}&tags={key}={value},{key}={value}
URI example
- Querying all instances and details
  https://dds.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances
- Querying instances and details based on search criteria
  https://dds.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances?offset=0&limit=10&id=ed7cc6166ec24360a5ed5c5c9c2ed726in02&name=hy&mode=ReplicaSet&datastore_type=DDS-Community&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&tags=key1=value1,key2=value2

**Table 1** Parameter description
Name	Type	Mandatory	Description
x-auth-token	string	Yes	User token
project_id	String	Yes	The project ID of a tenant in a region. To obtain the project ID, see Obtaining a Project ID.
id	String	No	The instance ID, which can be obtained by calling the API that is used for querying instances and details. If you do not have an instance, you can call the API used for creating an instance.
name	String	No	The DB instance name. If you use asterisk () at the beginning of the name, fuzzy search results are returned. Otherwise, the exact results are returned. NOTE: The asterisk () is a reserved character in the system and cannot be used alone.
mode	String	No	The instance type. Sharding indicates the cluster instance. ReplicaSet indicate the replica set instance. Single indicates the single node instance.
datastore_type	String	No	The database type. The value is DDS-Community.
vpc_id	String	No	The VPC ID. To obtain this parameter value, use either of the following methods: Method 1: Log in to VPC console and view the VPC ID on the VPC details page. Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs.
subnet_id	String	No	The network ID of the subnet. To obtain this parameter value, use either of the following methods: 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: Query the network ID through the VPC API. For details, see Querying Subnets.
offset	Integer	No	The 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 greater than or equal to 0. If this parameter is not transferred, offset is set to 0 by default, indicating that the query starts from the latest created DB instance.
limit	Integer	No	The maximum allowed number of DB instances. The value ranges from 1 to 100. If this parameter is not transferred, the first 100 DB instances are queried by default.
tags	String	No	Query based on the instance tag key and value. {key} indicates the tag key, and {value} indicates the tag value. A maximum of 20 key-value pairs are supported. The key cannot be empty or duplicate, but the value can be empty. To query instances with multiple tag keys and values, separate key-value pairs with commas (,).

Requests

None

Responses

Parameter description

**Table 2** Response body parameters
Name	Type	Mandatory	Description
instances	Array of objects	Yes	The DB instance information. For more information, see Table 3.
total_count	Integer	Yes	The total number of queried records.

**Table 3** Data structure of the instances field
Name	Type	Mandatory	Description
id	String	Yes	The DB instance ID.
name	String	Yes	The DB instance name.
remark	String	Yes	Instance remarks
status	String	Yes	The DB instance status. Valid value: normal: indicates that the instance is running properly. abnormal: indicates that the instance is abnormal. creating: indicates that the instance is being created. frozen: indicates that the instance is frozen. data_disk_full: The storage space is full. createfail: indicates that the instance failed to be created. enlargefail: indicates that nodes failed to be added to the instance. NOTE: Actions that are being executed on an instance, for example, rebooting, are essentially different from the instance status. For details, see the actions field in this table.
port	String	Yes	The database port. The port range is 2100 to 9500.
mode	String	Yes	The instance type, which is the same as the request parameter.
region	String	Yes	The region where the DB instance is deployed.
datastore	Object	Yes	The database information. For more information, see Table 4.
engine	String	Yes	The storage engine. DDS supports the WiredTiger and RocksDB storage engines. If the database version is 4.2 and the storage engine is RocksDB, the value is rocksDB. If the database version is 4.0 or 3.4 and the storage engine is WiredTiger, the value is wiredTiger.
created	String	Yes	The DB instance creation time.
updated	String	Yes	The time when a DB instance is updated.
db_user_name	String	Yes	The default username. The value is rwuser.
ssl	Integer	Yes	Whether SSL is enabled. 1: indicate that SSL is enabled. 0: indicate that SSL is disabled.
vpc_id	String	Yes	The VPC ID.
subnet_id	String	Yes	The network ID of the subnet.
security_group_id	String	Yes	Indicates the security group ID.
backup_strategy	Object	Yes	The backup policy. For more information, see Table 5.
pay_mode	String	No	The billing mode. 0: indicates the pay-per-use billing mode. 1: indicates the yearly/monthly billing mode.
maintenance_window	String	Yes	The maintenance time window.
groups	Array of objects	Yes	Group information. For more information, see Table 6.
disk_encryption_id	String	Yes	The disk encryption key ID. This parameter is returned only when the instance disk is encrypted.
enterprise_project_id	String	Yes	Enterprise project ID. If the value is 0, the resource belongs to the default enterprise project.
time_zone	String	Yes	The time zone.
dss_pool_id	String	No	The DSS storage pool ID of the DeC user.
actions	Array of strings	Yes	Action that is being executed on an instance. Valid value: RESTARTING: The instance is being restarted. RESTORE: The instance is being restored. RESIZE_FLAVOR: The specifications are being changed. RESTORE_TO_NEW_INSTANCE: The instance is being restored. MODIFY_VPC_PEER: Cross-subnet access is being configured. CREATE: The instance is being created. FROZEN: The instance is frozen. RESIZE_VOLUME: The storage is being scaled up. RESTORE_CHECK: The restoration is being checked. RESTORE_FAILED_HANGUP: The restoration failed. CLOSE_AUDIT_LOG: The audit policy is being disabled. OPEN_AUDIT_LOG: The audit policy is being enabled. PERIOD_RESOURCE_SPEC_CHG: The yearly/monthly resource changes are being checked. CREATE_IP_SHARD: The shard IP address is being enabled. CREATE_IP_CONFIG: The config IP address is being enabled. GROWING: The node is being scaled up. SET_CONFIGURATION: Parameters are being modified. RESTORE_TABLE: The table is being restored. MODIFY_SECURITYGROUP: A security group is being changed. BIND_EIP: The EIP is being changed. UNBIND_EIP: The EIP is being unbound. SWITCH_SSL: The SSL is being switched. SWITCH_PRIMARY: A primary/standby switchover is being performed. CHANGE_DBUSER_PASSWORD: The password is being changed. MODIFY_PORT: The port is being changed. MODIFY_IP: The private IP address is being changed. DELETE_INSTANCE: The instance is being deleted. REBOOT: The instance is being restarted. BACKUP: The backup is in progress. MIGRATE_AZ: The AZ is being changed. PWD_RESETING: The password is being reset. UPGRADE_DATABASE: The patch is being upgraded. DATA_MIGRATION: Data is being migrated. SHARD_GROWING: The shard is being scaled out. APPLY_CONFIGURATION: A parameter group is being changed. RESET_PASSWORD: The password is being reset. GROWING_REVERT: Nodes are being deleted. SHARD_GROWING_REVERT: Shards are being deleted. ONDEMAND_TO_PERIOD: The billing mode is being changed to yearly/monthly. LOG_PLAINTEXT_SWITCH: The slow query log configuration is being modified. CREATE_DATABASE_USER: The database user is being created. CREATE_DATABASE_ROLE: The database role is being created. MODIFY_NAME: The name is being changed. MODIFY_PRIVATE_DNS: The private zone is being modified. MODIFY_OP_LOG_SIZE: The oplog size is being changed. ADD_READONLY_NODES: Read replicas are being scaled up.
order_id	String	No	Order ID, which is returned only when an instance is billed on a yearly/monthly basis.
tags	Array of objects	Yes	Tag list For details, see Table 9.

**Table 4** Data structure of the datastore field
Name	Type	Mandatory	Description
type	String	Yes	The DB engine.
version	String	Yes	The database version. Versions 4.2, 4.0, and 3.4 are supported. The value can be 4.2, 4.0, or 3.4. NOTE: DDS 4.2 is restricted for commercial use. For details, see the DDS notices. To ensure you have a good experience using DDS, create a DDS 4.0 instance.
patch_available	Boolean	Yes	Whether there is an available patch for upgrade. If true is returned, you can install the patch to upgrade the instance.

**Table 5** backup_strategy field data structure description
Name	Type	Mandatory	Description
start_time	String	Yes	The backup time window. Automated backups will be triggered during the backup time window. The current time is the UTC time.
keep_days	Integer	Yes	The number of days to retain the generated backup files. The value range is from 0 to 732.

**Table 6** groups field data structure description
Name	Type	Mandatory	Description
type	String	Yes	The node type. Valid value: shard config mongos replica single
id	String	Yes	The group ID. This parameter is valid only when the node type is shard or config.
name	String	Yes	The group name. This parameter is valid only when the node type is shard or config.
status	String	Yes	The group status. This parameter is valid only when the node type is shard or config.
volume	Object	Yes	The volume information. For more information, see Table 7. This parameter is valid only when the node type is shard, config, or replica.
nodes	Array of objects	Yes	The node information. For more information, see Table 8.

**Table 7** Data structure description of the volume field
Name	Type	Mandatory	Description
size	String	Yes	The disk size. Unit: GB
used	String	Yes	The disk usage. Unit: GB

**Table 8** nodes field data structure description
Name	Type	Mandatory	Description
id	String	Yes	The node ID.
name	String	Yes	The node name.
status	String	Yes	The node status.
role	String	Yes	The node role. Valid value: master: This value is returned for the mongos node. Primary: This value is returned for the primary shard and config nodes, and the primary node of a replica set. Secondary: This value is returned for the secondary shard and config nodes, and the secondary node of a replica set. Hidden: This value is returned for the hidden shard and config nodes, and the hidden node of a replica set. unknown. This value is returned when the node is abnormal.
private_ip	String	Yes	The private IP address of a node. By default, this parameter is valid only for mongos nodes and replica set instances. The value exists after the ECS is created successfully. Otherwise, the value is "". CAUTION: After the shard or config IP address is enabled, private IP addresses are assigned to the primary and secondary shard or config nodes of the cluster instance.
public_ip	String	Yes	The EIP that has been bound. This parameter is valid only for mongos nodes of cluster instances and the primary and secondary nodes of replica set instances.
spec_code	String	Yes	The resource specification code. For details about the instance specifications, see the value of the flavors.spec_code parameter in Querying Database Specifications.
availability_zone	String	Yes	AZ.

**Table 9** Description of the tag field
Name	Type	Mandatory	Description
key	String	Yes	Tag key
value	String	Yes	Tag value

The values of region and availability_zone are used as examples.

Response example

{
  "instances": [
    {
      "id": "8436a91546294036b75931e879882200in02",
      "name": "dds-efa6",
      "remark": "test",
      "status": "normal",
      "port": 8635,
      "mode": "ReplicaSet",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:05:52",
      "updated": "2019-01-17T07:05:47",
      "db_user_name": "rwuser",
      "ssl": 1,
      "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": {
        "type": "replica",
        "volume": {
          "size": 10,
          "used": 0.33
        },
        "nodes": [
          {
            "id": "233eaac9c6f245c0bb9c2d21eea12d1bno02",
            "name": "dds-efa6_replica_node_2",
            "status": "normal",
            "role": "Primary",
            "private_ip": "192.168.0.174",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          },
          {
            "id": "d57d76d6320a4a7b86db82c317550c4ano02",
            "name": "dds-efa6_replica_node_1",
            "status": "normal",
            "role": "Hidden",
            "private_ip": "192.168.0.39",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          },
          {
            "id": "f46b0a1cf4d9400e9fd7af17f8742d37no02",
            "name": "dds-efa6_replica_node_3",
            "status": "normal",
            "role": "Secondary",
            "private_ip": "192.168.0.176",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          }
        ]
      },
      "enterprise_project_id": "0",
      "time_zone": "",
      "dss_pool_id": "f5f84ed7-6f19-4bd4-99d7-b450ad6cc4dd",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    },
    {
      "id": "d77905385f114217b75ae7d6ab9a7588in02",
      "name": "dds-5699",
      "status": "normal",
      "remark": "Test",
      "port": 8635,
      "mode": "Single",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:04:39",
      "updated": "2019-01-17T07:04:33",
      "db_user_name": "rwuser",
      "ssl": 1,
      "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": "17:00-18:00",
        "keep_days": 7
      },
      "pay_mode": 0,
      "maintenance_window": "02:00-06:00",
      "groups": {
        "type": "single",
        "volume": {
          "size": 10,
          "used": 0.33
        },
        "nodes": [
          {
            "id": "bd4dccbd53ae48d5bd3046bebf715079no02",
            "name": "dds-5699_single_node_1",
            "status": "normal",
            "role": "Primary",
            "private_ip": "192.168.0.9",
            "public_ip": "",
            "spec_code": "dds.mongodb.c6.medium.4.single",
            "availability_zone": "bbb"
          }
        ]
      },
      "enterprise_project_id": "0",
      "time_zone": "",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    },
    {
      "id": "9136fd2a9fcd405ea4674276ce36dae8in02",
      "name": "dds-32f4",
      "remark": 123,
      "status": "normal",
      "port": 8635,
      "mode": "Sharding",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:04:37",
      "updated": "2019-01-17T07:04:31",
      "db_user_name": "rwuser",
      "ssl": 1,
      "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": "19:00-20:00",
        "keep_days": 7
      },
      "pay_mode": 0,
      "maintenance_window": "02:00-06:00",
      "groups": [
        {
          "type": "mongos",
          "nodes": [
            {
              "id": "a742c13a284949adad177672e8a0f01cno02",
              "name": "dds-32f4_mongos_node_1",
              "status": "normal",
              "role": "Primary",
              "private_ip": "192.168.0.56",
              "public_ip": "",
              "spec_code": "dds.mongodb.c6.medium.4.mongos",
              "availability_zone": "bbb"
            },
            {
              "id": "d4f66666b1d64ab28719da0526341c7eno02",
              "name": "dds-32f4_mongos_node_2",
              "status": "normal",
              "role": "Primary",
              "private_ip": "192.168.0.185",
              "public_ip": "",
              "spec_code": "dds.mongodb.c6.medium.4.mongos",
              "availability_zone": "bbb"
            }
          ]
        },
        {
          "type": "shard",
          "volume": {
            "size": 10,
            "used": 0.33
          },
          "nodes": [
            {
              "id": "0e9abaebe5974b63a5b221de6ee34cfeno02",
              "name": "dds-32f4_shard_2_node_3",
              "status": "normal",
              "role": "Primary",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            },
            {
              "id": "1d7f4c5476c04cc187f920925c2b601fno02",
              "name": "dds-32f4_shard_2_node_2",
              "status": "normal",
              "role": "Hidden",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            },
            {
              "id": "3dd2cce03da54fc08f10651cbfea778dno02",
              "name": "dds-32f4_shard_2_node_1",
              "status": "normal",
              "role": "Secondary",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            }
          ]
        },
        {
          "type": "config",
          "volume": {
            "size": 10,
            "used": 0.33
          },
          "nodes": [
            {
              "id": "7422f7331b714ac39aa647a1ec968d33no02",
              "name": "dds-32f4_config_node_2",
              "status": "normal",
              "role": "Primary",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            },
            {
              "id": "9e3b343151044eda91ddb8a42ae5cbefno02",
              "name": "dds-32f4_config_node_3",
              "status": "normal",
              "role": "Hidden",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            },
            {
              "id": "c0053ca460ac4889841ffb14a886ec54no02",
              "name": "dds-32f4_config_node_1",
              "status": "normal",
              "role": "Secondary",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            }
          ]
        }
      ],
      "enterprise_project_id": "0",
      "time_zone": "",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    }
  ],
  "total_count": 3
}

Status Code

For more information, see Status Code.

Error Code

For more information, see Error Code.

Parent topic: DB Instance Management

Previous topic: Deleting a DB Instance

Next topic: Scaling Up Storage Space

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel