Queries AnalyticDB for MySQL clusters in a specific region.

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 DescribeDBClusters

The operation that you want to perform. Set the value to DescribeDBClusters.

RegionId String Yes cn-hangzhou

The ID of the region.

Note You can call the DescribeRegions operation to query the most recent region list.
DBClusterIds String No am-bp1r053byu48p****

The ID of the cluster.

DBClusterDescription String No test

The description of the cluster.

  • The description cannot start with http:// or https.
  • The description must be 2 to 256 characters in length.
DBClusterStatus String No Running

The state of the cluster. Valid values:

  • Preparing: The cluster is being prepared.
  • Creating: The cluster is being created.
  • Restoring: The cluster is being restored from a backup.
  • Running: The cluster is running.
  • Deleting: The cluster is being deleted.
  • ClassChanging: The cluster specification is being changed.
  • NetAddressCreating: A network connection is being created.
  • NetAddressDeleting: The network connection is being deleted.
PageSize Integer No 30

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

  • 30
  • 50
  • 100
PageNumber Integer No 1

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

ResourceGroupId String No rg-4690g37929XXXX

The ID of the resource group.

Tag.N.Key String No tag1

The key of tag N, which can be used to filter clusters. A tag is a key-value pair. You can specify up to 20 tags in one request. The letter N specifies the sequence number of each key-value pair and must be unique. The values of N must be consecutive integers that start from 1. Each value of Tag.N.Key is paired with a value of Tag.N.Value.

Note The tag key can be up to 64 characters in length and cannot start with aliyun, acs:, http://, or https://.
Tag.N.Value String No test1

The value of tag N, which can be used to filter clusters. A tag is a key-value pair. You can specify up to 20 tags in one request. The letter N specifies the sequence number of each key-value pair and must be unique. The values of N must be consecutive integers that start from 1. Each value of Tag.N.Key is paired with a value of Tag.N.Value.

Note The tag value can be up to 64 characters in length and cannot start with aliyun, acs:, http://, or https://.

Response parameters

Parameter Type Example Description
TotalCount Integer 1

The total number of entries.

PageSize Integer 30

The number of entries returned on each page.

RequestId String D65A809F-34CE-4550-9BC1-0ED21ETG380

The ID of the request.

PageNumber Integer 1

The page number of the returned page.

Items Array of DBCluster

Details of the clusters.

DBCluster
DtsJobId String dtsb1578j90XXXX

The ID of the Data Transmission Service (DTS) synchronization task. This parameter is returned only for MySQL analytic instances.

DBNodeCount Long 1

The number of node groups.

Expired String false

Indicates whether the cluster has expired. Valid values:

  • true: The instance has expired.
  • false: The instance has not expired.
CreateTime String 2021-04-01T09:50:18Z

The time when the cluster was created. The time is displayed in UTC. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. Example: 2021-04-01T09:50:18Z.

PayType String Postpaid

The billing method of the cluster. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: subscription
DiskType String cloud_essd

The type of the disk. Valid values:

  • local_ssd: local disk
  • cloud: basic disk
  • cloud_ssd: standard SSD
  • cloud_efficiency: ultra disk
  • cloud_essd: enhanced SSD (ESSD) at performance level 1 (PL1)
  • cloud_essd2: ESSD at performance level 2 (PL2)
  • cloud_essd3: ESSD at performance level 3 (PL3)
Note For more information about ESSDs, see ESSDs.
Tags Array of Tag

Details of the tags.

Tag
Key String tag1

The key of the tag.

Note You can call the TagResources operation to add a tag to the cluster.
Value String test1

The value of the tag.

Mode String flexible

The mode of the cluster. Valid values:

  • flexible: the elastic mode
  • reserver: the reserved mode
Note
  • For more information about cluster modes, see Editions.
Port String 3306

The port number that is used to connect to the cluster. Default value: 3306.

LockMode String Unlock

The lock mode of the cluster. Valid values:

  • Unlock: The cluster is not locked.
  • ManualLock: The cluster is manually locked.
  • LockByExpiration: The cluster is automatically locked after it expires.
  • LockByRestoration: The cluster is automatically locked before a rollback.
  • LockByDiskQuota: The cluster is automatically locked when it has used 90% of its storage.
StorageResource String 8Core32GB

The specifications of storage resources in elastic mode. These resources are used to read and write data. You can increase the value of this parameter to improve the read and write capabilities of the cluster.

ExecutorCount String 1

The number of compute nodes that are used by the cluster in elastic mode.

DBClusterId String am-bp163885f8q21****

The ID of the cluster.

ConnectionString String am-bp11q28kvl6882h5cXXXX20o.ads.aliyuncs.com

The public endpoint of the cluster.

RdsInstanceId String rm-bp11q28kvl688****

The ID of the ApsaraDB RDS instance from which data is synchronized to the cluster. This parameter is returned only for MySQL analytic instances.

DBClusterType String Common

The type of the cluster. Valid values:

  • Common: common cluster
  • RDS_ANALYSIS: MySQL analytic instance
CommodityCode String ads

The commodity code. ads is returned.

ExpireTime String 2999-09-08T16:00:00Z

The time when the cluster expired. The time is displayed in UTC. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. Example: 2999-09-08T16:00:00Z.

Note
  • If the billing method of the cluster is subscription, the actual expiration time is returned.
  • If the billing method of the cluster is pay-as-you-go, 2999-09-08T16:00:00Z is returned.
DBNodeStorage Long 300

The storage capacity of the cluster. Unit: GB.

DBNodeClass String E8

The specifications of the node.

LockReason String instance_expired

The reason why the cluster is locked.

Note This parameter is returned only when the cluster is locked. The value is instance_expire.
VPCId String vpc-bp13h7uzhulpuxvnpXXXX

The ID of the virtual private cloud (VPC).

RegionId String cn-hangzhou

The region ID of the cluster.

ComputeResource String 8Core32GB

The specifications of computing resources in elastic mode. The increase of computing resources can speed up queries. You can adjust the value of this parameter to scale the cluster.

ElasticIOResource Integer 0

The elastic I/O unit (EIU). For more information, see EIUs.

Note This parameter is returned only for clusters in elastic mode.
VSwitchId String vsw-bp1syh8vvw8yech7nXXXX

The ID of the vSwitch.

DBVersion String 3.0

The version of the database engine. Only 3.0 is supported.

VPCCloudInstanceId String am-bp163885f8q21****-controller

The ID of the instance that is deployed in the VPC.

DBClusterStatus String Running

The state of the cluster. For more information, see Cluster states.

ResourceGroupId String rg-acfmyiu4ekp****

The ID of the resource group.

DBClusterNetworkType String vpc

The network type of the cluster. Only VPC is supported.

DBClusterDescription String adb_test

The description of the cluster.

ZoneId String cn-hangzhou-h

The zone ID of the cluster.

Category String MIXED_STORAGE

The edition of the cluster. Valid values:

  • BASIC: reserved mode for Basic Edition
  • CLUSTER: reserved mode for Cluster Edition
  • MIXED_STORAGE: elastic mode for Cluster Edition
Note For more information about cluster editions, see Editions.
Engine String AnalyticDB

The engine of the cluster. AnalyticDB is returned.

Examples

Sample requests

http(s)://adb.aliyuncs.com/?Action=DescribeDBClusters
&RegionId=cn-hangzhou
&DBClusterIds=am-bp1r053byu48p****
&DBClusterDescription=test
&DBClusterStatus=Running
&PageSize=30
&PageNumber=1
&ResourceGroupId=rg-4690g37929XXXX
&Tag=[{"Key":"tag1","Value":"test1"}]
&<Common request parameters>

Sample success responses

XML format

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

<DescribeDBClustersResponse>
    <TotalCount>1</TotalCount>
    <PageSize>30</PageSize>
    <RequestId>D65A809F-34CE-4550-9BC1-0ED21ETG380</RequestId>
    <PageNumber>1</PageNumber>
    <Items>
        <DtsJobId>dtsb1578j90XXXX</DtsJobId>
        <DBNodeCount>1</DBNodeCount>
        <Expired>false</Expired>
        <CreateTime>2021-04-01T09:50:18Z</CreateTime>
        <PayType>Postpaid</PayType>
        <DiskType>cloud_essd</DiskType>
        <Tags>
            <Key>tag1</Key>
            <Value>test1</Value>
        </Tags>
        <Mode>flexible</Mode>
        <Port>3306</Port>
        <LockMode>Unlock</LockMode>
        <StorageResource>8Core32GB</StorageResource>
        <ExecutorCount>1</ExecutorCount>
        <DBClusterId>am-bp163885f8q21****</DBClusterId>
        <ConnectionString>am-bp11q28kvl6882h5cXXXX20o.ads.aliyuncs.com</ConnectionString>
        <RdsInstanceId>rm-bp11q28kvl688****</RdsInstanceId>
        <DBClusterType>Common</DBClusterType>
        <CommodityCode>ads</CommodityCode>
        <ExpireTime>2999-09-08T16:00:00Z</ExpireTime>
        <DBNodeStorage>300</DBNodeStorage>
        <DBNodeClass>E8</DBNodeClass>
        <LockReason>instance_expired</LockReason>
        <VPCId>vpc-bp13h7uzhulpuxvnpXXXX</VPCId>
        <RegionId>cn-hangzhou</RegionId>
        <ComputeResource>8Core32GB</ComputeResource>
        <ElasticIOResource>0</ElasticIOResource>
        <VSwitchId>vsw-bp1syh8vvw8yech7nXXXX</VSwitchId>
        <DBVersion>3.0</DBVersion>
        <VPCCloudInstanceId>am-bp163885f8q21****-controller</VPCCloudInstanceId>
        <DBClusterStatus>Running</DBClusterStatus>
        <ResourceGroupId>rg-acfmyiu4ekp****</ResourceGroupId>
        <DBClusterNetworkType>vpc</DBClusterNetworkType>
        <DBClusterDescription>adb_test</DBClusterDescription>
        <ZoneId>cn-hangzhou-h</ZoneId>
        <Category>MIXED_STORAGE</Category>
        <Engine>AnalyticDB</Engine>
    </Items>
</DescribeDBClustersResponse>

JSON format

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

{
  "TotalCount" : 1,
  "PageSize" : 30,
  "RequestId" : "D65A809F-34CE-4550-9BC1-0ED21ETG380",
  "PageNumber" : 1,
  "Items" : {
    "DtsJobId" : "dtsb1578j90XXXX",
    "DBNodeCount" : 1,
    "Expired" : false,
    "CreateTime" : "2021-04-01T09:50:18Z",
    "PayType" : "Postpaid",
    "DiskType" : "cloud_essd",
    "Tags" : {
      "Key" : "tag1",
      "Value" : "test1"
    },
    "Mode" : "flexible",
    "Port" : 3306,
    "LockMode" : "Unlock",
    "StorageResource" : "8Core32GB",
    "ExecutorCount" : 1,
    "DBClusterId" : "am-bp163885f8q21****",
    "ConnectionString" : "am-bp11q28kvl6882h5cXXXX20o.ads.aliyuncs.com",
    "RdsInstanceId" : "rm-bp11q28kvl688****",
    "DBClusterType" : "Common",
    "CommodityCode" : "ads",
    "ExpireTime" : "2999-09-08T16:00:00Z",
    "DBNodeStorage" : 300,
    "DBNodeClass" : "E8",
    "LockReason" : "instance_expired",
    "VPCId" : "vpc-bp13h7uzhulpuxvnpXXXX",
    "RegionId" : "cn-hangzhou",
    "ComputeResource" : "8Core32GB",
    "ElasticIOResource" : 0,
    "VSwitchId" : "vsw-bp1syh8vvw8yech7nXXXX",
    "DBVersion" : 3,
    "VPCCloudInstanceId" : "am-bp163885f8q21****-controller",
    "DBClusterStatus" : "Running",
    "ResourceGroupId" : "rg-acfmyiu4ekp****",
    "DBClusterNetworkType" : "vpc",
    "DBClusterDescription" : "adb_test",
    "ZoneId" : "cn-hangzhou-h",
    "Category" : "MIXED_STORAGE",
    "Engine" : "AnalyticDB"
  }
}

Error codes

HTTP status code Error code Error message Description
500 InternalError An error occurred while processing your request. The error message returned because an internal error has occurred. Try again later.
503 ServiceUnavailable An error occurred while processing your request. The error message returned because the service is unavailable. Try again later.

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