All Products
Search
Document Center

AnalyticDB:DescribeDBClusters

Last Updated:Aug 30, 2024

Queries the information about AnalyticDB for MySQL Data Lakehouse Edition clusters within a region.

Operation description

For information about the endpoints of AnalyticDB for MySQL, see Endpoints .

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
adb:DescribeDBClusterslist
  • DBClusterLakeVersion
    acs:adb:{#regionId}:{#accountId}:dbcluster/{#DBClusterId}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID of the cluster.

Note You can call the DescribeRegions operation to query the most recent region list.
cn-hangzhou
DBClusterIdsstringNo

The ID of the AnalyticDB for MySQL Data Lakehouse Edition (V3.0) cluster.

If you do not specify this parameter, the information about all clusters that reside in the region is returned.

amv-bp1r053byu48p****
DBClusterDescriptionstringNo

The description of the cluster.

  • The description cannot start with http:// or https://.
  • The description must be 2 to 256 characters in length
test
DBClusterStatusstringNo

The state of the cluster. Valid values:

  • Preparing
  • Creating
  • Running
  • Deleting
  • Restoring
  • ClassChanging
  • NetAddressCreating
  • NetAddressDeleting
  • NetAddressModifying
Running
PageSizeintegerNo

The number of entries per page. Valid values:

  • 30 (default)
  • 50
  • 100
30
PageNumberintegerNo

The page number. Pages start from page 1. Default value: 1.

1
ResourceGroupIdstringNo

The resource group ID. If you do not specify this parameter, the information about all resource groups in the cluster is returned.

rg-4690g37929****
Tagarray<object>No

The tags that are added to the cluster.

objectNo
KeystringNo

The tag key.

tag1
ValuestringNo

The tag value.

test1

Response parameters

ParameterTypeDescriptionExample
object
TotalCountinteger

The total number of entries returned.

1
PageSizeinteger

The number of entries per page.

30
RequestIdstring

The request ID.

A5EDBA27-AF3E-5966-9503-FD1557E19167
PageNumberinteger

The page number.

1
Itemsarray<object>

The queried clusters.

object

The information about the cluster.

Expiredstring

Indicates whether the subscription cluster has expired. Valid values:

  • true
  • false
Note
  • If the cluster has expired, the system locks or releases the cluster within a period of time. We recommend that you renew the expired cluster. For more information, see Renewal policy.

  • This parameter is not returned for pay-as-you-go clusters.

false
CreateTimestring

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

2022-04-01T09:50:18Z
PayTypestring

The billing method of the cluster. Valid values:

  • Postpaid: pay-as-you-go.
  • Prepaid: subscription.
Prepaid
Modestring

The mode of the cluster. By default, flexible is returned, which indicates that the cluster is in elastic mode.

flexible
Portstring

The port number that is used to connect to the cluster.

3306
LockModestring

The lock status of the cluster. Valid values:

  • Unlock: The cluster is not locked.
  • ManualLock: The cluster is manually locked.
  • LockByExpiration: The cluster is automatically locked due to cluster expiration.
Unlock
StorageResourcestring

The specifications of reserved storage resources. Each AnalyticDB compute unit (ACU) is approximately equal to 1 core and 4 GB memory. Storage resources are used to read and write data. The increase in the storage resources can improve the read and write performance of the cluster.

24ACU
DBClusterIdstring

The ID of the AnalyticDB for MySQL Data Lakehouse Edition (V3.0) cluster.

amv-bp163885f8q21****
ConnectionStringstring

The public endpoint that is used to connect to the cluster.

amv-bp163885f8q21****.ads.aliyuncs.com
DBClusterTypestring

The type of the cluster. By default, Common is returned, which indicates a common cluster.

Common
CommodityCodestring

The billing method of the cluster. Valid values:

  • ads: pay-as-you-go.
  • ads_pre: subscription.
ads_pre
ExpireTimestring

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

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, null is returned.

2022-07-01T09:50:18Z
LockReasonstring

The reason why the cluster is locked.

Note This parameter is returned only when the cluster was locked. instance_expire is returned.
instance_expire
VPCIdstring

The virtual private cloud (VPC) ID of the cluster.

vpc-bp13h7uzhulpuxvnp****
RegionIdstring

The region ID of the cluster.

cn-hangzhou
ComputeResourcestring

The specifications of reserved computing resources. Each ACU is approximately equal to 1 core and 4 GB memory. Computing resources are used to compute data. The increase in the computing resources can accelerate queries. You can scale computing resources based on your business requirements.

16ACU
VSwitchIdstring

The vSwitch ID of the cluster.

vsw-bp1syh8vvw8yech7n****
DBVersionstring

The engine version of the AnalyticDB for MySQL Data Lakehouse Edition cluster. 5.0 is returned.

5.0
DBClusterStatusstring

The status of the cluster. Valid values:

  • Preparing
  • Creating
  • Running
  • Deleting
  • Restoring
  • ClassChanging
  • NetAddressCreating
  • NetAddressDeleting
  • NetAddressModifying
Running
ResourceGroupIdstring

The resource group ID.

rg-acfmyiu4ekp****
DBClusterNetworkTypestring

The network type of the cluster. VPC is returned.

VPC
DBClusterDescriptionstring

The description of the cluster.

adb_test
ZoneIdstring

The zone ID of the cluster.

cn-hangzhou-h
Enginestring

The engine of the cluster. AnalyticDB is returned.

AnalyticDB
ReservedACUstring

The remaining reserved computing resources that are available in the cluster. Each ACU is approximately equal to 1 core and 4 GB memory.

32ACU
Tagsarray<object>

The tags that are added to the cluster.

object
Keystring

The tag key.

Note You can call the TagResources operation to add tags to a cluster.
tag1
Valuestring

The tag value.

test1

Examples

Sample success responses

JSONformat

{
  "TotalCount": 1,
  "PageSize": 30,
  "RequestId": "A5EDBA27-AF3E-5966-9503-FD1557E19167",
  "PageNumber": 1,
  "Items": {
    "DBCluster": [
      {
        "Expired": "false",
        "CreateTime": "2022-04-01T09:50:18Z",
        "PayType": "Prepaid",
        "Mode": "flexible",
        "Port": "3306",
        "LockMode": "Unlock",
        "StorageResource": "24ACU",
        "DBClusterId": "amv-bp163885f8q21****",
        "ConnectionString": "amv-bp163885f8q21****.ads.aliyuncs.com",
        "DBClusterType": "Common",
        "CommodityCode": "ads_pre",
        "ExpireTime": "2022-07-01T09:50:18Z",
        "LockReason": "instance_expire",
        "VPCId": "vpc-bp13h7uzhulpuxvnp****",
        "RegionId": "cn-hangzhou",
        "ComputeResource": "16ACU",
        "VSwitchId": "vsw-bp1syh8vvw8yech7n****",
        "DBVersion": "5.0",
        "DBClusterStatus": "Running",
        "ResourceGroupId": "rg-acfmyiu4ekp****",
        "DBClusterNetworkType": "VPC",
        "DBClusterDescription": "adb_test",
        "ZoneId": "cn-hangzhou-h",
        "Engine": "AnalyticDB",
        "ReservedACU": "32ACU",
        "Tags": {
          "Tag": [
            {
              "Key": "tag1",
              "Value": "test1"
            }
          ]
        },
        "Category": "",
        "InnerPort": "",
        "VPCCloudInstanceId": "",
        "InnerIp": "",
        "DtsJobId": "",
        "ElasticIOResource": 0,
        "RdsInstanceId": "",
        "ExecutorCount": "",
        "DBNodeClass": "",
        "DiskType": "",
        "DBNodeStorage": 0,
        "DBNodeCount": 0,
        "TaskInfo": {
          "Name": "",
          "Status": "",
          "Progress": "",
          "StepList": {
            "StepList": [
              {
                "StepName": "",
                "StepDesc": "",
                "StepStatus": "",
                "StepProgress": "",
                "StartTime": "",
                "EndTime": ""
              }
            ]
          }
        },
        "ProductForm": "",
        "ProductVersion": "",
        "ReservedNodeSize": "",
        "ReservedNodeCount": 0
      }
    ]
  }
}

Error codes

HTTP status codeError codeError messageDescription
500InternalErrorAn error occurred while processing your request.An internal error occurred. Please try again later.
503ServiceUnavailableAn error occurred while processing your request.The system is unavailable. Please try again later.

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

Change history

Change timeSummary of changesOperation
2024-05-28The Error code has changed. The response structure of the API has changedView Change Details
2024-05-09The Error code has changed. The request parameters of the API has changed. The response structure of the API has changedView Change Details
2023-07-27The Error code has changed. The request parameters of the API has changed. The response structure of the API has changedView Change Details