DescribeDBInstances API Reference for MongoDB - ApsaraDB for MongoDB

The list of replica set and standalone instances is displayed when the DBInstanceType parameter uses the default value replicate. To query the list of sharded cluster instances, you must set the DBInstanceType parameter to sharding.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	DescribeDBInstances	The operation that you want to perform. Set the value to DescribeDBInstances.
RegionId	String	No	cn-hangzhou	The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.
PageNumber	Integer	No	1	The number of the page to return. The value of this parameter must be an integer that is greater than 0. Default value: 1.
PageSize	Integer	No	30	The number of entries to return on each page. Default value: 30. Valid values: 30 50 100
DBInstanceId	String	No	dds-bp199659b178****	The ID of the instance.
ReplicationFactor	String	No	3	The number of nodes in the replica set instance. Valid values: 3 5 7
DBInstanceDescription	String	No	testdatabase	The name of the instance. Valid values: The name must start with a letter. The name can contain digits, letters, underscores (_), and hyphens (-). The name must be 2 to 256 characters in length.
ExpireTime	String	No	2019-12-26T16:00Z	The time when the instance expires.
DBInstanceStatus	String	No	Running	The state of the instance. For more information about valid values, see Instance states.
DBInstanceType	String	No	sharding	The architecture of the instance. Default value: replicate. Valid values: sharding: sharded cluster instance replicate: replica set or standalone instance
DBInstanceClass	String	No	dds.mongo.mid	The instance type. For more information about valid values, see Instance types.
Engine	String	No	MongoDB	The database engine of the instance. Set the value to MongoDB.
EngineVersion	String	No	4.0	The database engine version of the instance. Valid values: 5.0 4.4 4.2 4.0 3.4
NetworkType	String	No	VPC	The network type of the instance. Valid values: Classic: classic network VPC: Virtual Private Cloud (VPC)
VpcId	String	No	vpc-bp1n3i15v90el48nx****	The ID of the VPC.
VSwitchId	String	No	vsw-bp1vj604nj5a9zz74****	The ID of the vSwitch.
ChargeType	String	No	PrePaid	The billing method of the instance. Valid values: PrePaid: subscription PostPaid: pay-as-you-go
ZoneId	String	No	cn-hangzhou-b	The zone ID of the instance. You can call the DescribeRegions operation to query the most recent zone list.
Expired	String	No	true	Specifies whether the instance has expired. Valid values: true: The instance has expired. false: The instance has not expired.
ConnectionDomain	String	No	dds-bp1ea17b41abecf43****.mongodb.rds.aliyuncs.com	The endpoint of the node. You can call the DescribeDBInstanceAttribute operation to query the endpoint of the node.
ResourceGroupId	String	No	rg-acfmyiu4ekp****	The ID of the resource group.
Tag.N.Key	String	No	testdatabase	The key of tag N of the instance. Valid values of N: 1 to 20. The key cannot start with `aliyun`, `acs:`, `http://`, or `https://`. The key can be up to 64 characters in length. The key cannot be an empty string.
Tag.N.Value	String	No	apitest	The value of tag N of the instance. Valid values of N: 1 to 20. The value cannot start with `aliyun`, `acs:`, `http://`, or `https://`. The value can be up to 128 characters in length. The value can be an empty string.

Response parameters


Parameter	Type	Example	Description
TotalCount	Integer	5	The number of instances in the query results.
RequestId	String	0E4FE33F-5510-5758-8FA7-A6672CDE****	The ID of the request.
PageSize	Integer	30	The number of entries to return on each page.
PageNumber	Integer	1	The number of the returned page.
DBInstances	Array of DBInstance		Details of the instances.
DBInstance
CreationTime	String	2021-03-25T02:18:00Z	The time when the instance was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
ChargeType	String	PrePaid	The billing method of the instance. Valid values: PrePaid: subscription PostPaid: pay-as-you-go
Tags	Array of Tag		Details of the resource tags.
Tag
Key	String	test	The tag key of the resource.
Value	String	api	The tag value of the resource.
VpcAuthMode	String	Close	Indicates whether password-free access within a VPC is enabled. Valid values: Open: Password-free access is enabled. Close: Password-free access is disabled.
NetworkType	String	Classic	The network type of the instance. Valid values: Classic: classic network VPC: VPC
LockMode	String	Unlock	The lock state of the instance. Valid values: Unlock: The cluster is not locked. ManualLock: The instance is manually locked. LockByExpiration: The instance is automatically locked due to instance expiration. LockByRestoration: The instance is automatically locked before it is rolled back. LockByDiskQuota: The instance is automatically locked due to exhausted storage capacity. Released: The instance is released. After an instance is released, the instance cannot be unlocked. You can only restore the backup data of the instance to a new instance. This process requires a long period of time.
EngineVersion	String	4.2	The database engine version of the instance. Valid values: 5.0 4.4 4.2 4.0 3.4
MongosList	Array of MongosAttribute		Details of the mongos nodes. Note This parameter is returned if the instance is a sharded cluster instance.
MongosAttribute
NodeClass	String	dds.mongos.standard	The type of the mongos node.
NodeDescription	String	testmongosnode	The description of the mongos node.
NodeId	String	s-bp10e3b0d02f****	The ID of the mongos node.
DBInstanceDescription	String	testdatabase	The description of the instance.
ExpireTime	String	2021-11-25T16:00Z	The time when the instance expires. The time is in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC.
DBInstanceType	String	sharding	The architecture of the instance. sharding: sharded cluster instance replicate: replica set or standalone instance
LastDowngradeTime	String	2021-05-08	The date when the last downgrade operation was performed.
ShardList	Array of ShardAttribute		Details of the shard nodes. Note This parameter is returned if the instance is a sharded cluster instance.
ShardAttribute
NodeClass	String	dds.shard.mid	The type of the shard node.
NodeDescription	String	testshardnode	The description of the shard node.
NodeStorage	Integer	10	The storage capacity of the shard node. Unit: GB.
NodeId	String	d-bp1cac6f2083****	The ID of the shard node.
ReadonlyReplicas	Integer	2	The number of read-only nodes in the shard node. Valid values: 0 to 5.
DestroyTime	String	2021-12-10T16:00:00Z	The time when the instance data was destroyed. The time is in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC. Note Subscription instances are released 15 days after expiration. After an instance is released, its data is deleted and cannot be restored. Pay-as-you-go instances are locked after the payments have been overdue for longer than 24 hours. The instances are released after the payments have been overdue for longer than 15 days. The data of released instances is deleted and cannot be restored.
DBInstanceStatus	String	Running	The state of the instance. For more information, see Instance states.
RegionId	String	cn-hangzhou	The region ID of the instance.
DBInstanceStorage	Integer	20	The storage capacity of the instance.
ResourceGroupId	String	rg-acfmyiu4ekp****	The ID of the resource group.
ZoneId	String	cn-hangzhou-g	The zone ID of the instance.
DBInstanceId	String	dds-bp18b0934e70****	The ID of the instance.
DBInstanceClass	String	dds.mongo.mid	The instance type.
Engine	String	MongoDB	The database engine of the instance.
ReplicationFactor	String	3	The number of nodes in the instance. Note This parameter is returned if the instance is a replica set instance.
KindCode	String	1	The kind code of the instance. Valid values: 0: physical machine 1: Elastic Compute Service (ECS) instance 2: Docker cluster 18: Kubernetes cluster
CapacityUnit	String	100	The I/O throughput consumed by the instance. Note This parameter is returned when the instance is a serverless instance.
StorageType	String	local_ssd	The storage type of the instance. Valid values: cloud_essd: enhanced SSD (ESSD) local_ssd: local SSD
SecondaryZoneId	String	cn-hangzhou-i	The ID of the secondary zone 1 of the instance. Valid values: cn-hangzhou-g: Hangzhou Zone G cn-hangzhou-h: Hangzhou Zone H cn-hangzhou-i: Hangzhou Zone I cn-hongkong-b: Hongkong Zone B cn-hongkong-c: Hongkong Zone C cn-hongkong-d: Hongkong Zone D cn-wulanchabu-a: Ulanqab Zone A cn-wulanchabu-b: Ulanqab Zone B cn-wulanchabu-c: Ulanqab Zone C ap-southeast-1a: Singapore Zone A ap-southeast-1b: Singapore Zone B ap-southeast-1c: Singapore Zone C ap-southeast-5a: Jakarta Zone A ap-southeast-5b: Jakarta Zone B ap-southeast-5c: Jakarta Zone C eu-central-1a: Frankfurt Zone A eu-central-1b: Frankfurt Zone B eu-central-1c: Frankfurt Zone C Note This parameter is returned if the instance is a replica set or sharded cluster instance that runs MongoDB 4.4 or 5.0 and uses multi-zone deployment. This parameter is returned only if you use the Chine site (aliyun.com).
HiddenZoneId	String	cn-hangzhou-h	The ID of the secondary zone 2 of the instance. Valid values: cn-hangzhou-g: Hangzhou Zone G cn-hangzhou-h: Hangzhou Zone H cn-hangzhou-i: Hangzhou Zone I cn-hongkong-b: Hongkong Zone B cn-hongkong-c: Hongkong Zone C cn-hongkong-d: Hongkong Zone D cn-wulanchabu-a: Ulanqab Zone A cn-wulanchabu-b: Ulanqab Zone B cn-wulanchabu-c: Ulanqab Zone C ap-southeast-1a: Singapore Zone A ap-southeast-1b: Singapore Zone B ap-southeast-1c: Singapore Zone C ap-southeast-5a: Jakarta Zone A ap-southeast-5b: Jakarta Zone B ap-southeast-5c: Jakarta Zone C eu-central-1a: Frankfurt Zone A eu-central-1b: Frankfurt Zone B eu-central-1c: Frankfurt Zone C Note This parameter is returned if the instance is a replica set or sharded cluster instance that runs MongoDB 4.4 or 5.0 and uses multi-zone deployment. This parameter is returned only if you use the Chine site (aliyun.com).

Examples

Sample requests

http(s)://mongodb.aliyuncs.com/?Action=DescribeDBInstances
&DBInstanceType=sharding
&NetworkType=classic
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeDBInstancesResponse>
    <TotalCount>5</TotalCount>
    <RequestId>0E4FE33F-5510-5758-8FA7-A6672CDE****</RequestId>
    <PageSize>30</PageSize>
    <PageNumber>1</PageNumber>
    <DBInstances>
        <CreationTime>2021-03-25T02:18:00Z</CreationTime>
        <ChargeType>PrePaid</ChargeType>
        <Tags>
            <Key>test</Key>
            <Value>api</Value>
        </Tags>
        <VpcAuthMode>Close</VpcAuthMode>
        <NetworkType>Classic</NetworkType>
        <LockMode>Unlock</LockMode>
        <EngineVersion>4.2</EngineVersion>
        <MongosList>
            <NodeClass>dds.mongos.standard</NodeClass>
            <NodeDescription>testmongosnode</NodeDescription>
            <NodeId>s-bp10e3b0d02f****</NodeId>
        </MongosList>
        <DBInstanceDescription>testdatabase</DBInstanceDescription>
        <ExpireTime>2021-11-25T16:00Z</ExpireTime>
        <DBInstanceType>sharding</DBInstanceType>
        <LastDowngradeTime>2021-05-08</LastDowngradeTime>
        <ShardList>
            <NodeClass>dds.shard.mid</NodeClass>
            <NodeDescription>testshardnode</NodeDescription>
            <NodeStorage>10</NodeStorage>
            <NodeId>d-bp1cac6f2083****</NodeId>
            <ReadonlyReplicas>2</ReadonlyReplicas>
        </ShardList>
        <DestroyTime>2021-12-10T16:00:00Z</DestroyTime>
        <DBInstanceStatus>Running</DBInstanceStatus>
        <RegionId>cn-hangzhou</RegionId>
        <DBInstanceStorage>20</DBInstanceStorage>
        <ResourceGroupId>rg-acfmyiu4ekp****</ResourceGroupId>
        <ZoneId>cn-hangzhou-g</ZoneId>
        <DBInstanceId>dds-bp18b0934e70****</DBInstanceId>
        <DBInstanceClass>dds.mongo.mid</DBInstanceClass>
        <Engine>MongoDB</Engine>
        <ReplicationFactor>3</ReplicationFactor>
        <KindCode>1</KindCode>
        <CapacityUnit>100</CapacityUnit>
        <StorageType>local_ssd</StorageType>
    </DBInstances>
</DescribeDBInstancesResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "TotalCount" : 5,
  "RequestId" : "0E4FE33F-5510-5758-8FA7-A6672CDE****",
  "PageSize" : 30,
  "PageNumber" : 1,
  "DBInstances" : {
    "CreationTime" : "2021-03-25T02:18:00Z",
    "ChargeType" : "PrePaid",
    "Tags" : {
      "Key" : "test",
      "Value" : "api"
    },
    "VpcAuthMode" : "Close",
    "NetworkType" : "Classic",
    "LockMode" : "Unlock",
    "EngineVersion" : 4.2,
    "MongosList" : {
      "NodeClass" : "dds.mongos.standard",
      "NodeDescription": "testmongosnode"
      "NodeId" : "s-bp10e3b0d02f****"
    },
    "DBInstanceDescription": "testdatabase",
    "ExpireTime" : "2021-11-25T16:00Z",
    "DBInstanceType" : "sharding",
    "LastDowngradeTime" : "2021-05-08",
    "ShardList" : {
      "NodeClass" : "dds.shard.mid",
      "NodeDescription": "testshardnode"
      "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"
  }
}

Error codes

For a list of error codes, visit the API Error Center.