Queries information about all PolarDB clusters or specified PolarDB clusters that you can access.

Debugging

Alibaba Cloud provides OpenAPI Explorer to simplify API usage. 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 where the clusters that you want to query are deployed.

Note You can call the DescribeRegions operation to query information about regions.
DBClusterIds String No pc-****************

The ID of each cluster that you want to query. Separate cluster IDs with commas (,).

DBClusterDescription String No pc-****************

The description of clusters that you want to query. You can specify keywords to implement fuzzy match.

DBClusterStatus String No Running

The state of the clusters that you want to query. For information about valid values, see Cluster status.

DBType String No MySQL

The database engine that databases in the clusters run. Valid values:

  • MySQL
  • PostgreSQL
  • Oracle
PageSize Integer No 30

The number of entries to return on each page. Valid values: 30, 50, or 100.

Default value: 30.

PageNumber Integer No 10

The number of the page to return. The value must be a positive integer that does not exceed the maximum value of the INTEGER data type. Default value: 1.

ResourceGroupId String No rg-**********

The ID of the resource group to which the clusters that you want to query belong.

Tag.N.Key String No MySQL

The keys of the tags that you want to use to query clusters. You can use tags to filter clusters. You can specify up to 20 tags. N specifies the serial number of each tag. The values that you specify for N must be unique and be consecutive integers that start from 1. The values of the Tag.N.Key parameter and the values of the Tag.N.Value parameter must be from the same key-value pairs.

Note The value of this parameter can be up to 64 characters in length and cannot start with aliyun, acs:, http://, or https://.
Tag.N.Value String No 5.6

The values of the tags that you want to use to query clusters.

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

Response parameters

Parameter Type Example Description
TotalRecordCount Integer 16

The total number of returned entries.

PageRecordCount Integer 5

The number of clusters returned per page.

RequestId String 9B7BFB11-C077-4FE3-B051-F69CEB******

The ID of the request.

PageNumber Integer 12

The page number of the returned page.

Items Array of DBCluster

The list of clusters.

DBCluster
VpcId String vpc-****************

The ID of the virtual private cloud (VPC) in which the cluster is deployed.

ExpireTime String 2020-11-14T16:00:00Z

The time when the cluster expires.

Note Expiration time is returned only for clusters that use the subscription billing method. An empty string is returned for clusters that use the pay-as-you-go billing method.
Expired String false

This parameter indicates whether the cluster is expired.

Note This parameter is returned only for clusters that use the subscription billing method.
DBNodeNumber Integer 2

The number of nodes that are contained in the cluster.

CreateTime String 2020-08-14T05:58:42Z

The time when the cluster was created.

PayType String Prepaid

The billing method of the cluster. Valid values:

  • Postpaid: the pay-as-you-go billing method
  • Prepaid: the subscription billing method
DBNodeClass String polar.mysql.x4.large

The node type.

Tags Array of Tag

The list of tags.

Tag
Key String MySQL

The key of the tag.

Value String 5.6

The value of the tag.

DBType String MySQL

The database engine that the database runs.

LockMode String Unlock

The state of the cluster lock. Valid values:

  • Unlock: The cluster is not locked.
  • ManualLock: The cluster is manually locked.
  • LockByExpiration: The cluster is automatically locked because the subscription duration of the cluster expires.
DBNodes Array of DBNode

The list of nodes.

DBNode
DBNodeClass String polar.mysql.x4.large

The node type.

ZoneId String cn-hangzhou-i

The ID of the zone where the node is deployed.

DBNodeRole String Reader

The role of the node. Valid values:

  • Writer: The node is the primary node.
  • Reader: The node is a read-only node.
DBNodeId String pi-****************

The ID of the node.

RegionId String cn-hangzhou

The ID of the region where the node is deployed.

RegionId String cn-hangzhou

The ID of the region where the cluster is deployed.

DeletionLock Integer 0

The protection state of the cluster. Valid values:

  • 0: The cluster is not locked.
  • 1: The cluster is locked.
    Note You cannot delete the cluster if the cluster is locked.
DBVersion String 5.6

The version of the database engine that databases in the cluster run.

DBClusterId String pc-****************

The ID of the cluster.

DBClusterStatus String Running

The state of the cluster.

ResourceGroupId String rg-************

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

StorageUsed Long 3009413120

The storage usage.

DBClusterNetworkType String VPC

The network type of the cluster.

DBClusterDescription String GDN-1

The description of the cluster.

ZoneId String cn-hangzhou-i

The ID of the zone where the cluster is deployed.

Engine String POLARDB

The database engine that databases in the cluster run.

Category String Normal

The edition of the cluster. Valid values:

  • Normal: Cluster Edition
  • Basic: Single Node Edition
  • Archive: Archive Database Edition

Examples

Sample requests

http(s)://polardb.aliyuncs.com/?Action=DescribeDBClusters
&RegionId=cn-hangzhou
&<Common request parameters>

Sample success responses

XML format

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

<DescribeDBClustersResponse>
    <TotalRecordCount>16</TotalRecordCount>
    <PageRecordCount>5</PageRecordCount>
    <RequestId>9B7BFB11-C077-4FE3-B051-F69CEB******</RequestId>
    <PageNumber>12</PageNumber>
    <Items>
        <VpcId>vpc-****************</VpcId>
        <ExpireTime>2020-11-14T16:00:00Z</ExpireTime>
        <Expired>false</Expired>
        <DBNodeNumber>2</DBNodeNumber>
        <CreateTime>2020-08-14T05:58:42Z</CreateTime>
        <PayType>Prepaid</PayType>
        <DBNodeClass>polar.mysql.x4.large</DBNodeClass>
        <Tags>
            <Key>MySQL</Key>
            <Value>5.6</Value>
        </Tags>
        <DBType>MySQL</DBType>
        <LockMode>Unlock</LockMode>
        <DBNodes>
            <DBNodeClass>polar.mysql.x4.large</DBNodeClass>
            <ZoneId>cn-hangzhou-i</ZoneId>
            <DBNodeRole>Reader</DBNodeRole>
            <DBNodeId>pi-****************</DBNodeId>
            <RegionId>cn-hangzhou</RegionId>
        </DBNodes>
        <RegionId>cn-hangzhou</RegionId>
        <DeletionLock>0</DeletionLock>
        <DBVersion>5.6</DBVersion>
        <DBClusterId>pc-****************</DBClusterId>
        <DBClusterStatus>Running</DBClusterStatus>
        <ResourceGroupId>rg-************</ResourceGroupId>
        <StorageUsed>3009413120</StorageUsed>
        <DBClusterNetworkType>VPC</DBClusterNetworkType>
        <DBClusterDescription>GDN-1</DBClusterDescription>
        <ZoneId>cn-hangzhou-i</ZoneId>
        <Engine>POLARDB</Engine>
        <Category>Normal</Category>
    </Items>
</DescribeDBClustersResponse>

JSON format

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

{
  "TotalRecordCount" : 16,
  "PageRecordCount" : 5,
  "RequestId" : "9B7BFB11-C077-4FE3-B051-F69CEB******",
  "PageNumber" : 12,
  "Items" : [ {
    "VpcId" : "vpc-****************",
    "ExpireTime" : "2020-11-14T16:00:00Z",
    "Expired" : "false",
    "DBNodeNumber" : 2,
    "CreateTime" : "2020-08-14T05:58:42Z",
    "PayType" : "Prepaid",
    "DBNodeClass" : "polar.mysql.x4.large",
    "Tags" : [ {
      "Key" : "MySQL",
      "Value" : "5.6"
    } ],
    "DBType" : "MySQL",
    "LockMode" : "Unlock",
    "DBNodes" : [ {
      "DBNodeClass" : "polar.mysql.x4.large",
      "ZoneId" : "cn-hangzhou-i",
      "DBNodeRole" : "Reader",
      "DBNodeId" : "pi-****************",
      "RegionId" : "cn-hangzhou"
    } ],
    "RegionId" : "cn-hangzhou",
    "DeletionLock" : 0,
    "DBVersion" : "5.6",
    "DBClusterId" : "pc-****************",
    "DBClusterStatus" : "Running",
    "ResourceGroupId" : "rg-************",
    "StorageUsed" : 3009413120,
    "DBClusterNetworkType" : "VPC",
    "DBClusterDescription" : "GDN-1",
    "ZoneId" : "cn-hangzhou-i",
    "Engine" : "POLARDB",
    "Category" : "Normal"
  } ]
}

Error codes

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