All Products
Search
Document Center

ApsaraDB for MongoDB:DescribeDBInstances

更新時間:Sep 03, 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:DescribeDBInstancesget
  • Instance
    acs:dds:{#regionId}:{#accountId}:dbinstance/*
  • Instance
    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.

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****
Tagarray<object>No

The tags of the instance.

objectNo
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
DBInstancesarray<object>

The details of the instance.

object
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
Tagsarray<object>

The details of the tag.

object

The details of the resource tags.

Keystring

The tag key.

test
Valuestring

The tag value.

api
VpcAuthModestring

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

  • Open: Password-free access over VPC is enabled.
  • Close: Password-free access over VPC is disabled.
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 cluster is unlocked.
  • 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 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. Valid values:

  • 7.0
  • 6.0
  • 5.0
  • 4.4
  • 4.2
  • 4.0
  • 3.4
4.2
MongosListarray<object>

The details of the mongos node.

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

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.

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

The date when the last downgrade operation was performed.

2021-05-08
ShardListarray<object>

The details of the shard node.

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

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 is destroyed. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Note
  • For a subscription instance, the computing resources of the instance are released on the 16th day after expiration, and the data of the instance is retained for seven days. The data is deleted on the 23th day after expiration and cannot be restored.
  • For a pay-as-you-go instance, the computing resources of the instance are released on the 16th day after the payment becomes overdue, and the data of the instance is retained for seven days. The data is deleted on the 23th day after the payment becomes overdue 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 zone ID of the instance.

    cn-hangzhou-g
    DBInstanceIdstring

    The instance ID.

    dds-bp18b0934e70****
    DBInstanceClassstring

    The instance type of the instance.

    dds.mongo.mid
    Enginestring

    The 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 I/O throughput consumed by the instance.

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

    The storage type of the instance. Valid values:

    • cloud_essd: Enterprise SSD (ESSD)
    • local_ssd: local SSD
    local_ssd
    BackupRetentionPolicyinteger

    The backup retention policy configured for the instance. Valid values:

    • 0: All backup sets of the instance are immediately deleted when the instance is released.
    • 1: A backup set of the instance is automatically backed up and retained for a long period of time when the instance is released.
    • 2: All backup sets of the instance are automatically backed up and retained for a long period of time when the instance is released.
    1
    ReleaseTimestring

    The time when the instance was released.

    2024-06-17T07:01Z

    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",
            "BackupRetentionPolicy": 1,
            "ReleaseTime": "2024-06-17T07:01Z"
          }
        ]
      }
    }

    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 affectedView Change Details
    2023-07-31The internal configuration of the API is changed, but the call is not affectedView Change Details
    2021-12-27The internal configuration of the API is changed, but the call is not affectedView Change Details
    2021-12-27The response structure of the API has changedView Change Details