All Products
Search
Document Center

ApsaraDB for MongoDB:DescribeDBInstances

Last Updated:Mar 15, 2024

Queries a list of ApsaraDB for MongoDB instances.

Operation description

The list of replica set and standalone instances is displayed when the DBInstanceType parameter uses the default value replicate. To query a 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.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
dds:DescribeDBInstancesLIST
  • dbinstance
    acs:dds:{#regionId}:{#accountId}:dbinstance/*
  • dbinstance
    acs:dds:{#regionId}:{#accountId}:dbinstance/{#dbinstanceId}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringNo

The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
PageNumberintegerNo

The number of the page to return. The value of this parameter must be an integer that is greater than 0. Default value: 1.

1
PageSizeintegerNo

The number of entries to return on each page. Valid values:

  • 30 (default)
  • 50
  • 100
30
DBInstanceIdstringNo

The instance ID.

dds-bp199659b178****
ReplicationFactorstringNo

The number of nodes in the replica set instance. Valid values:

  • 3
  • 5
  • 7
3
DBInstanceDescriptionstringNo

The name of the instance. The name must meet the following requirements:

  • The name must start with a letter.
  • It can contain digits, letters, underscores (_), and hyphens (-).
  • It must be 2 to 256 characters in length.
Test database
ExpireTimestringNo

The time when the instance expires.

Enumeration Value:
  • 1
  • 3
  • 7
2019-12-26T16:00Z
DBInstanceStatusstringNo

The state of the instance. For more information about valid values, see Instance states.

Running
DBInstanceTypestringNo

The architecture of the instance. Valid values:

  • sharding: sharded cluster instance
  • replicate: replica set or standalone instance
sharding
DBInstanceClassstringNo

The instance type. For more information about valid values, see Instance types.

dds.mongo.mid
EnginestringNo

The database engine of the instance. Set the value to MongoDB.

MongoDB
EngineVersionstringNo

The database engine version of the instance.

  • 6.0
  • 5.0
  • 4.4
  • 4.2
  • 4.0
  • 3.4
4.0
NetworkTypestringNo

The network type of the instance. Valid values:

  • Classic
  • VPC
VPC
VpcIdstringNo

The VPC ID of the instance.

vpc-bp1n3i15v90el48nx****
VSwitchIdstringNo

The vSwitch ID of the instance.

vsw-bp1vj604nj5a9zz74****
ChargeTypestringNo

The billing method of the instance. Valid values:

  • PrePaid: subscription
  • PostPaid: pay-as-you-go
PrePaid
ZoneIdstringNo

The zone ID of the instance. You can call the DescribeRegions operation to query the most recent zone list.

cn-hangzhou-b
ExpiredstringNo

Specifies whether the instance has expired. Valid values:

  • true
  • false
true
ConnectionDomainstringNo

The endpoint of the node. You can call the DescribeDBInstanceAttribute operation to query the endpoint of the node.

dds-bp1ea17b41abecf43****.mongodb.rds.aliyuncs.com
ResourceGroupIdstringNo

The ID of the resource group.

rg-acfmyiu4ekp****
Tagobject []No

The tags of the instance.

KeystringNo

The tag key of the instance. Valid values of N: 1 to 20.

  • The key cannot start with aliyun, acs:, http://, or https://.
  • It can be up to 64 characters in length.
  • It cannot be an empty string.
testdatabase
ValuestringNo

The tag value 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.
  • It can be an empty string.
apitest
DBNodeTypestringNo

The type of the node in the instance. This parameter is used to filter standard or test instance.

  1. Valid value for a standalone or DBFS instance.
  2. Valid value for a standard instance that comes in the replica set or sharded cluster architecture: standard
  3. Valid value when all instances are displayed: default
default

Response parameters

ParameterTypeDescriptionExample
object
TotalCountinteger

The number of instances in the query results.

5
RequestIdstring

The request ID.

0E4FE33F-5510-5758-8FA7-A6672CDE****
PageSizeinteger

The number of entries returned on each page.

30
PageNumberinteger

The page number of the returned page.

1
DBInstancesobject []

The details of the instances.

CreationTimestring

The time when the instance was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

2021-03-25T02:18:00Z
ChargeTypestring

The billing method of the instance. Valid values:

  • PrePaid: subscription.
  • PostPaid: pay-as-you-go.
PrePaid
Tagsobject []

The details of the resource tags.

Keystring

The tag key.

test
Valuestring

The tag value.

api
VpcAuthModestring

Indicates whether password-free access within a virtual private cloud (VPC) is enabled. Valid values:

  • Open
  • Close
Close
NetworkTypestring

The network type of the instance. Valid values:

  • Classic: classic network.
  • VPC: VPC.
Classic
LockModestring

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 due to instance expiration.
  • LockByRestoration: The instance is automatically locked before the instance is rolled back.
  • LockByDiskQuota: The instance is automatically locked after the storage space is exhausted.
  • 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.
Unlock
EngineVersionstring

The database engine version of the instance.

  • 5.0
  • 4.4
  • 4.2
  • 4.0
  • 3.4
4.2
MongosListobject []

The details of the mongos node.

Note This parameter is returned if the instance is a sharded cluster instance.
NodeClassstring

The instance type of the mongos node.

dds.mongos.standard
NodeDescriptionstring

The description of the mongos node.

testmongosnode
NodeIdstring

The ID of the mongos node.

s-bp10e3b0d02f****
DBInstanceDescriptionstring

The description of the instance.

Test database
ExpireTimestring

The time when the instance expires. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC.

2021-11-25T16:00Z
DBInstanceTypestring

The architecture of the instance. Valid values:

  • sharding: sharded cluster instance.
  • replicate: replica set or standalone instance.
sharding
LastDowngradeTimestring

The date when the last downgrade operation was performed.

2021-05-08
ShardListobject []

The details of the shard node.

Note This parameter is returned if the instance is a sharded cluster instance.
NodeClassstring

The instance type of the shard node.

dds.shard.mid
NodeDescriptionstring

The description of the shard node.

testshardnode
NodeStorageinteger

The storage capacity of the shard node. Unit: GB.

10
NodeIdstring

The ID of the shard node.

d-bp1cac6f2083****
ReadonlyReplicasinteger

The number of read-only nodes in the shard node. Valid values: 0 to 5.

2
DestroyTimestring

The time when the instance data was destroyed. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Note
  • Subscription instances are released 15 days after expiration. After the instances are released, the data of the instances 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.
  • 2021-12-10T16:00:00Z
    DBInstanceStatusstring

    The status of the instance. For more information, see Instance states.

    Running
    RegionIdstring

    The region ID of the instance.

    cn-hangzhou
    DBInstanceStorageinteger

    The storage capacity of the instance.

    20
    ResourceGroupIdstring

    The ID of the resource group to which the instance belongs.

    rg-acfmyiu4ekp****
    ZoneIdstring

    The ID of the zone in which the instance resides.

    cn-hangzhou-g
    DBInstanceIdstring

    The instance ID

    dds-bp18b0934e70****
    DBInstanceClassstring

    The instance type of the instance.

    dds.mongo.mid
    Enginestring

    The database engine of the instance.

    MongoDB
    ReplicationFactorstring

    The number of nodes in the instance.

    Note This parameter is returned if the instance is a replica set instance.
    3
    KindCodestring

    The kind code of the instance. Valid values:

    • 0: physical machine.
    • 1: Elastic Compute Service (ECS) instance.
    • 2: Docker cluster.
    • 18: Kubernetes cluster.
    1
    CapacityUnitstring

    The read and write throughput consumed by the instance.

    Note This parameter is returned when the instance is a serverless instance.
    100
    StorageTypestring

    The storage type of the instance. Valid values:

    • cloud_essd: enhanced SSD (ESSD).
    • local_ssd: local SSD.
    local_ssd

    Examples

    Sample success responses

    JSONformat

    {
      "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": "testmongosnode\n",
                  "NodeId": "s-bp10e3b0d02f****"
                }
              ]
            },
            "DBInstanceDescription": "Test database\n",
            "ExpireTime": "2021-11-25T16:00Z",
            "DBInstanceType": "sharding",
            "LastDowngradeTime": "2021-05-08",
            "ShardList": {
              "ShardAttribute": [
                {
                  "NodeClass": "dds.shard.mid",
                  "NodeDescription": "testshardnode\n",
                  "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",
            "SecondaryZoneId": "cn-hangzhou-i",
            "HiddenZoneId": "cn-hangzhou-h"
          }
        ]
      }
    }

    Error codes

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2024-01-29The internal configuration of the API is changed, but the call is not affectedsee changesets
    Change itemChange content
    The internal configuration of the API is changed, but the call is not affected.
    2023-07-31The internal configuration of the API is changed, but the call is not affectedsee changesets
    Change itemChange content
    The internal configuration of the API is changed, but the call is not affected.
    2021-12-27The internal configuration of the API is changed, but the call is not affectedsee changesets
    Change itemChange content
    The internal configuration of the API is changed, but the call is not affected.
    2021-12-27The response structure of the API has changedsee changesets
    Change itemChange content
    Output ParametersThe response structure of the API has changed.