All Products
Search

This Product

    ApsaraDB for MongoDB:DescribeDBInstances

    Document Center

    ApsaraDB for MongoDB:DescribeDBInstances

    Last Updated:Jan 17, 2023

    Queries the 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 the list of sharded cluster instances, you must set the DBInstanceType parameter to sharding.

    Authorization information

    The following table is the authorization information corresponding to the API, which can be found in the RAM permission policy statement.Action Used in the element to grant the RAM user or RAM role permission to call this API. The specific instructions are as follows:

    • 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 keyword: refers to the condition keyword defined by the cloud product itself.
    • 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.
    Operate access level Resource type conditional keyword Association operation
    dds:DescribeDBInstances LIST
    • MongoDB
      acs:dds:{#regionId}:{#accountId}:dbinstance/*
    • MongoDB
      acs:dds:{#regionId}:{#accountId}:dbinstance/{#dbinstanceId}
      without
    		without

    Request parameters

    Parameter Type Required Description Example
    RegionId string No

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

    		 cn-hangzhou
    PageNumber integer No

    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
    PageSize integer No

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

    • 30
    • 50
    • 100
    		 30
    DBInstanceId string No

    The ID of the instance.

    		 dds-bp199659b178****
    ReplicationFactor string No

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

    • 3
    • 5
    • 7
    		 3
    DBInstanceDescription string No

    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.
    		 test database
    ExpireTime string No

    The time when the instance expires.

    		 2019-12-26T16:00Z
    DBInstanceStatus string No

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

    		 Running
    DBInstanceType string No

    The architecture of the instance. Default value: replicate. Valid values:

    • sharding: sharded cluster instance
    • replicate: replica set or standalone instance
    		 sharding
    DBInstanceClass string No

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

    		 dds.mongo.mid
    Engine string No

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

    		 MongoDB
    EngineVersion string No

    The database engine version of the instance. Valid values:

    • 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: Virtual Private Cloud (VPC)
    		 VPC
    VpcId string No

    The ID of the VPC.

    		 vpc-bp1n3i15v90el48nx****
    VSwitchId string No

    The ID of the vSwitch.

    		 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 of the instance. You can call the DescribeRegions operation to query the most recent zone list.

    		 cn-hangzhou-b
    Expired string No

    Specifies whether the instance has expired. Valid values:

    • true: The instance has expired.
    • false: The instance has not expired.
    		 true
    ConnectionDomain string No

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

    		 dds-bp1ea17b41abecf43****.mongodb.rds.aliyuncs.com
    ResourceGroupId string No

    The ID of the resource group.

    		 rg-acfmyiu4ekp****
    Tag array No

    The tags of instances.
    object No
    Key string No

    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.
    		 testdatabase
    Value string No

    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.
    		 apitest
    DBNodeType string No

    Used to filter standard instances or test instances

    1. Single node instance and dbfs instance: customized
    2. Standard instance (replicaset and shard cluster): standard
    3. Default (showing all instances): default
    		 default

    Response parameters

    Parameter Type Description Example
    object
    TotalCount integer

    The number of instances in the query results.

    		 5
    RequestId string

    The ID of the request.

    		 0E4FE33F-5510-5758-8FA7-A6672CDE****
    PageSize integer

    The number of entries to return on each page.

    		 30
    PageNumber integer

    The number of the returned page.

    		 1
    DBInstances array

    Details of the instances.
    object
    CreationTime string

    The time when the instance was created. The time is in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in 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 array

    Details of the resource tags.
    object
    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 within a VPC is enabled. Valid values:

    • Open: Password-free access is enabled.
    • Close: Password-free access is disabled.
    		 Close
    NetworkType string

    The network type of the instance. Valid values:

    • Classic: classic network
    • VPC: VPC
    		 Classic
    LockMode string

    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.
    		 Unlock
    EngineVersion string

    The database engine version of the instance. Valid values:

    • 5.0
    • 4.4
    • 4.2
    • 4.0
    • 3.4
    		 4.2
    MongosList array

    Details of the mongos nodes.

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

    The type of the mongos node.

    		 dds.mongos.standard
    NodeDescription string

    The description of the mongos node.

    		 mongos1
    NodeId string

    The ID of the mongos node.

    		 s-bp10e3b0d02f****
    DBInstanceDescription string

    The description of the instance.

    		 db for test.
    ExpireTime string

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

    		 2021-11-25T16:00Z
    DBInstanceType string

    The architecture of the instance.

    • sharding: sharded cluster instance
    • replicate: replica set or standalone instance
    		 sharding
    LastDowngradeTime string

    The date when the last downgrade operation was performed.

    		 2021-05-08
    ShardList array

    Details of the shard nodes.

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

    The type of the shard node.

    		 dds.shard.mid
    NodeDescription string

    The description of the shard node.

    		 testshard
    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 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.
    •
    		2021-12-10T16:00:00Z
    DBInstanceStatus string

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

    		 Running
    RegionId string

    The region ID of the instance.

    		 cn-hangzhou
    DBInstanceStorage integer

    The storage capacity of the instance.

    		 20
    ResourceGroupId string

    The ID of the resource group.

    		 rg-acfmyiu4ekp****
    ZoneId string

    The zone ID of the instance.

    		 cn-hangzhou-g
    DBInstanceId string

    The ID of the instance.

    		 dds-bp18b0934e70****
    DBInstanceClass string

    The instance type.

    		 dds.mongo.mid
    Engine string

    The database engine of the instance.

    		 MongoDB
    ReplicationFactor string

    The number of nodes in the instance.

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

    The kind code of the instance. Valid values:

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

    The I/O throughput consumed by the instance.

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

    The storage type of the instance. Valid values:

    • cloud_essd: enhanced SSD (ESSD)
    • local_ssd: local SSD
    		 local_ssd
    SecondaryZoneId string

    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).
    		 cn-hangzhou-i
    HiddenZoneId string

    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).
    		 cn-hangzhou-h

    Example

    Normal return example

    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": "mongos1",
              "NodeId": "s-bp10e3b0d02f****"
            }
          ]
        },
        "DBInstanceDescription": "db for test.",
        "ExpireTime": "2021-11-25T16:00Z",
        "DBInstanceType": "sharding",
        "LastDowngradeTime": "2021-05-08",
        "ShardList": {
          "ShardAttribute": [
            {
              "NodeClass": "dds.shard.mid",
              "NodeDescription": "testshard",
              "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 API error center.

    Change history

    Change time Summary of changes Operate
    2021-12-27 The internal configurations of the API operation has changed but you can still call the operation.
    Change item Change content
    The internal configurations of the API operation has changed but you can still call the operation.
    2021-12-27 The response structure of the API operation has changed
    Change item Change content
    Output Parameters The response structure of the API operation has changed