Use DescribeDBInstances to query MongoDB instances - ApsaraDB for MongoDB - Alibaba Cloud - ApsaraDB for MongoDB

Queries a list of MongoDB instances.

Operation description

By default, this operation queries the list of replica set instances (including single-node instances). If the request parameter DBInstanceType is not specified, the default value of this parameter is replicate. To query the list of sharded cluster instances, set DBInstanceType to sharding.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

dds:DescribeDBInstances

get

*Instance

acs:dds:{#regionId}:{#accountId}:dbinstance/*

*Instance

acs:dds:{#regionId}:{#accountId}:dbinstance/{#dbinstanceId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	No	The region ID. You can call the DescribeRegions operation to query the region ID.	cn-hangzhou
PageNumber	integer	No	The page number. The value must be a positive integer that does not exceed the maximum value of the Integer data type. Default value: 1.	1
PageSize	integer	No	The number of entries per page. Valid values: 30 (default) 50 100 Valid values: 30 : 30 entries per page. 50 : 50 entries per page. 100 : 100 entries per page.	30
DBInstanceId	string	No	The instance ID.	dds-bp199659b178****
ReplicationFactor	string	No	The number of nodes in the replica set instance. Valid values: 3 5 7	3
DBInstanceDescription	string	No	The instance name. The name must meet the following requirements: It must start with a Chinese character or a letter. It can contain digits, Chinese characters, letters, underscores (_), and hyphens (-). It must be 2 to 256 characters in length.	TestDatabase
ExpireTime	string	No	The expiration time of the instance in the yyyy-MM-ddTHH:mm:ssZ format (UTC). This parameter is used to filter instances whose expiration time is earlier than or equal to the specified time.	2019-12-26T16:00:00Z
DBInstanceStatus	string	No	The instance status. For more details about valid values, see Instance status table.	Running
DBInstanceType	string	No	The instance type. Valid values: sharding: sharded cluster instance. replicate: default value. Replica set instance or single-node instance.	sharding
DBInstanceClass	string	No	The instance specification. For more information about valid values, see Instance specifications.	dds.mongo.mid
Engine	string	No	The database engine. Set the value to MongoDB. Valid values: MongoDB : MongoDB database engine.	MongoDB
EngineVersion	string	No	The database engine version. Valid values: 7.0 6.0 5.0 4.4 4.2 4.0 3.4	4.0
NetworkType	string	No	The network type of the instance. Valid values: Classic: classic network. VPC: VPC.	VPC
VpcId	string	No	The VPC ID.	vpc-bp1n3i15v90el48nx****
VSwitchId	string	No	The vSwitch ID of the VPC.	vsw-bp1vj604nj5a9zz74****
ChargeType	string	No	The billing method of the instance. Valid values: PrePaid: subscription. PostPaid: pay-as-you-go.	PrePaid
ZoneId	string	No	The zone ID. You can call the DescribeRegions operation to query the zone ID.	cn-hangzhou-b
Expired	string	No	The expiration status of the instance. Valid values: true: expired. false: not expired.	true
ConnectionDomain	string	No	The endpoint of the node. You can call the DescribeDBInstanceAttribute operation to query the endpoint.	dds-bp1ea17b41abecf43****.mongodb.rds.aliyuncs.com
ResourceGroupId	string	No	The resource group ID.	rg-acfmyiu4ekp****
Tag	array<object>	No	The tags.
	object	No
Key	string	No	The tag key of the instance. Valid values of N: 1 to 20. The tag key cannot start with `aliyun`, `acs:`, `http://`, or `https://`. The tag key can be up to 64 characters in length. The tag key cannot be an empty string.	testdatabase
Value	string	No	The tag value of the instance. Valid values of N: 1 to 20. The tag value cannot start with `aliyun`, `acs:`, `http://`, or `https://`. The tag value can be up to 128 characters in length. The tag value can be an empty string.	apitest
DBNodeType	string	No	Specifies whether to filter standard or test instances. Single-node instances and DBFS instances: customized Standard instances (replica set and sharded cluster): standard Default (displays all instances): default	default

Response elements

Element	Type	Description	Example
	object
TotalCount	integer	The number of instances in the query result.	5
RequestId	string	The request ID.	0E4FE33F-5510-5758-8FA7-A6672CDE****
PageSize	integer	The number of records per page.	30
PageNumber	integer	The page number.	1
DBInstances	object
DBInstance	array<object>	The list of instance information.
	array<object>
CreationTime	string	The time when the instance was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).	2021-03-25T02:18:00Z
ChargeType	string	The billing method of the instance. Valid values: PrePaid: subscription. PostPaid: pay-as-you-go.	PrePaid
Tags	object
Tag	array<object>	The list of resource tags.
	object	The list of resource tags.
Key	string	The tag key of the resource.	test
Value	string	The tag value of the resource.	api
VpcAuthMode	string	Indicates whether password-free access over VPC is enabled. Valid values: Open: enabled. Close: disabled.	Close
NetworkType	string	The network type of the instance. Valid values: Classic: classic network. VPC: VPC.	Classic
LockMode	string	The lock status of the instance. Valid values: Unlock: The instance is not locked. ManualLock: The instance is manually locked. LockByExpiration: The instance is automatically locked because it has expired. LockByRestoration: The instance is automatically locked before a rollback. LockByDiskQuota: The instance is automatically locked because the storage is full. Released: The instance is released. In this case, the instance cannot be unlocked. You can only use backup data to create a new instance. The rebuild process takes a long time.	Unlock
EngineVersion	string	The database engine version. Valid values: 7.0 6.0 5.0 4.4 4.2 4.0 3.4	4.2
MongosList	object
MongosAttribute	array<object>	The list of mongos node information. Note This parameter is returned when the instance type is a sharded cluster instance.
	object	The list of mongos node information. Note This parameter is returned when the instance type is a sharded cluster instance.
NodeClass	string	The node specifications of the mongos node.	dds.mongos.standard
NodeDescription	string	The description of the mongos node.	Test mongos node
NodeId	string	The ID of the mongos node.	s-bp10e3b0d02f****
DBInstanceDescription	string	The description or remarks of the instance.	TestDatabase
ExpireTime	string	The time when the instance expires. The time is in the yyyy-MM-ddTHH:mmZ format (UTC).	2021-11-25T16:00Z
DBInstanceType	string	The instance type. Valid values: sharding: sharded cluster instance. replicate: replica set instance or standalone instance.	sharding
LastDowngradeTime	string	The last time when the instance was downgraded. The time is in the YYYY-MM-DD format.	2021-05-08
ShardList	object
ShardAttribute	array<object>	The list of shard node information. Note This parameter is returned when the instance type is a sharded cluster instance.
	object	The list of shard node information. Note This parameter is returned when the instance type is a sharded cluster instance.
NodeClass	string	The instance type of the shard node.	dds.shard.mid
NodeDescription	string	The description of the shard node.	Test shard node
NodeStorage	integer	The storage capacity of the shard node. Unit: GB.	10
NodeId	string	The ID of the shard node.	d-bp1cac6f2083****
ReadonlyReplicas	integer	The number of read-only nodes in the shard node. Valid values: 0 to 5.	2
DestroyTime	string	The data destruction time of the instance. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC). Note For subscription instances, compute resources are released on the 16th day after the instance expires, and data is retained for 7 more days. On the 23rd day after the instance expires, data is deleted and cannot be recovered. For pay-as-you-go instances, compute resources are released on the 16th day after the instance has an overdue payment, and data is retained for 7 more days. On the 23rd day after the overdue payment, data is deleted and cannot be recovered.	2021-12-10T16:00:00Z
DBInstanceStatus	string	The instance status. For details, see Instance status table.	Running
RegionId	string	The region ID of the instance.	cn-hangzhou
DBInstanceStorage	integer	The instance storage capacity.	20
ResourceGroupId	string	The resource group ID.	rg-acfmyiu4ekp****
ZoneId	string	The zone ID of the instance.	cn-hangzhou-g
DBInstanceId	string	The instance ID.	dds-bp18b0934e70****
DBInstanceClass	string	The instance type.	dds.mongo.mid
Engine	string	The database engine.	MongoDB
ReplicationFactor	string	The number of nodes in the instance. Note This parameter is returned when the instance type is a replica set instance.	3
KindCode	string	The type of the instance. Valid values: 0: physical machine. 1: ECS. 2: DOCKER. 18: Kubernetes-based new architecture instance.	1
CapacityUnit	string	The read/write throughput consumed by the instance. Note This parameter is returned when the instance type is a serverless instance.	100
StorageType	string	The storage type. Valid values: cloud_essd: ESSD cloud disk. local_ssd: local standard SSD.	local_ssd
BackupRetentionPolicy	integer	The backup data retention policy. Valid values: 0: All backup sets are immediately deleted when the instance is released. 1: An automatic backup is performed when the instance is released, and the backup set is retained for long-term retention (LTR). 2: An automatic backup is performed when the instance is released, and all backup sets of the cluster are retained for long-term retention (LTR).	1
ReleaseTime	string	The time when the instance is released. The time is in the YYYY-MM-DDTHH:mmZ format (UTC).	2024-06-17T07:01Z

Examples

Success response

JSON format

{
  "TotalCount": 5,
  "RequestId": "0E4FE33F-5510-5758-8FA7-A6672CDE****",
  "PageSize": 30,
  "PageNumber": 1,
  "DBInstances": {
    "DBInstance": [
      {
        "CreationTime": "2021-03-25T02:18:00Z",
        "ChargeType": "PrePaid",
        "Tags": {
          "Tag": [
            {
              "Key": "test",
              "Value": "api"
            }
          ]
        },
        "VpcAuthMode": "Close",
        "NetworkType": "Classic",
        "LockMode": "Unlock",
        "EngineVersion": "4.2",
        "MongosList": {
          "MongosAttribute": [
            {
              "NodeClass": "dds.mongos.standard",
              "NodeDescription": "测试mongos节点",
              "NodeId": "s-bp10e3b0d02f****"
            }
          ]
        },
        "DBInstanceDescription": "测试数据库",
        "ExpireTime": "2021-11-25T16:00Z",
        "DBInstanceType": "sharding",
        "LastDowngradeTime": "2021-05-08",
        "ShardList": {
          "ShardAttribute": [
            {
              "NodeClass": "dds.shard.mid",
              "NodeDescription": "测试shard节点",
              "NodeStorage": 10,
              "NodeId": "d-bp1cac6f2083****",
              "ReadonlyReplicas": 2
            }
          ]
        },
        "DestroyTime": "2021-12-10T16:00:00Z",
        "DBInstanceStatus": "Running",
        "RegionId": "cn-hangzhou",
        "DBInstanceStorage": 20,
        "ResourceGroupId": "rg-acfmyiu4ekp****",
        "ZoneId": "cn-hangzhou-g",
        "DBInstanceId": "dds-bp18b0934e70****",
        "DBInstanceClass": "dds.mongo.mid",
        "Engine": "MongoDB",
        "ReplicationFactor": "3",
        "KindCode": "1",
        "CapacityUnit": "100",
        "StorageType": "local_ssd",
        "BackupRetentionPolicy": 1,
        "ReleaseTime": "2024-06-17T07:01Z"
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.