DescribeDBClusters - PolarDB - Alibaba Cloud Documentation Center

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 region ID of the cluster. Note You can call the DescribeRegions operation to query available regions.
DBClusterIds	String	No	pc-****************	The ID of the cluster. Separate cluster IDs with commas (,).
DBClusterDescription	String	No	pc-****************	The description of the cluster. Fuzzy match is supported.
ConnectionString	String	No	********.rwlb.polardb-pg-public.rds.aliyuncs.com	The endpoint of the cluster.
DBClusterStatus	String	No	Running	The state of the cluster that you want to query. For more information about valid values, see Cluster states.
DBType	String	No	MySQL	The database engine that the clusters runs. Valid values: MySQL PostgreSQL Oracle
DBVersion	String	No	5.6	The version of the database engine that the cluster runs.
RecentCreationInterval	Integer	No	7	Filters clusters created in the last N days. Valid values: 0 to 15.
RecentExpirationInterval	Integer	No	6	Filters clusters that expire after N days. Valid values: 0 to 15.
Expired	Boolean	No	true	Specifies whether the cluster has expired. Valid values: true false
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 of this parameter must be an integer that is greater than 0. Default value: 1.
ResourceGroupId	String	No	rg-**********	The ID of the resource group.
Tag.N.Key	String	No	MySQL	The keys of the tags. 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. Note The value of this parameter can be up to 64 characters in length and cannot start with `aliyun`, `acs:`, `http://`, or `https://`.
PayType	String	No	Postpaid	The billing method. Valid values: Postpaid: pay-as-you-go Prepaid: subscription
DBNodeIds	String	No	pi-***************	The ID of the node. You can specify multiple node IDs. Separate multiple node IDs with commas (,).

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 total number of returned pages.
Items	Array of DBCluster		Details about the returned clusters.
DBCluster
VpcId	String	vpc-****************	The VPC ID of the cluster.
ExpireTime	String	2020-11-14T16:00:00Z	The time at which 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	Indicates whether the cluster has expired. Valid values: Valid values: true false Note This parameter is returned only for clusters that use the subscription billing method.
DBNodeNumber	Integer	2	The number of nodes.
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: pay-as-you-go. Prepaid: subscription.
StoragePayType	String	Prepaid	The billing method of the storage. Valid values: Valid values: Postpaid: pay-as-you-go Prepaid: subscription.
ServerlessType	String	AgileServerless	The type of the cluster. AgileServerless indicates a serverless cluster. An empty value indicates a common cluster.
StrictConsistency	String	ON	Indicates whether multi-zone data consistency is enabled for the cluster. Valid values: ON: indicates that multi-zone data consistency is enabled, which is suitable for Standard Edition clusters of Multi-zone Edition. OFF: indicates that multi-zone data consistency is not enabled.
DBNodeClass	String	polar.mysql.x4.large	The specifications of the node.
Tags	Array of Tag		Details about the returned 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 clusters runs.
LockMode	String	Unlock	The state of the cluster lock. Valid values: Unlock: The cluster is not locked. ManualLock: The instance is manually locked. LockByExpiration: The cluster is automatically locked because the cluster has expired.
DBNodes	Array of DBNode		Details about nodes.
DBNode
DBNodeClass	String	polar.mysql.x4.large	The specifications of the node.
ZoneId	String	cn-hangzhou-i	The zone ID of the node.
DBNodeRole	String	Reader	The role of the node. Valid values: Writer: the primary node. Reader: the read-only node.
DBNodeId	String	pi-****************	The ID of the node.
RegionId	String	cn-hangzhou	The region ID of the node.
Serverless	String	ON	Indicates whether the serverless feature is enabled for the current node. ON indicates whether the serverless feature is enabled. An empty value indicates that the serverless feature is not enabled.
RegionId	String	cn-hangzhou	The region ID of the cluster.
DeletionLock	Integer	0	The protection state of the cluster. Valid values: 0: The cluster is not locked. 1: The cluster is locked. Note The cluster cannot be deleted if the cluster is locked.
DBVersion	String	5.6	The version of the database engine that the node runs.
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.
StorageUsed	Long	3009413120	The storage used by the cluster. Unit: bytes.
StorageSpace	Long	50	The storage space that uses the subscription billing method. Unit: bytes.
DBClusterNetworkType	String	VPC	The network type of the cluster.
DBClusterDescription	String	GDN-1	The description of the cluster.
ZoneId	String	cn-hangzhou-i	The zone ID of the cluster.
Engine	String	POLARDB	The version of the database engine that the cluster runs.
Category	String	Normal	The edition of the cluster. Valid values: Normal: Cluster Edition Basic: Single Node Edition Archive: X-Engine Edition NormalMultimaster: Multi-master Cluster (Database/Table) Edition

Examples

Sample requests

http(s)://polardb.aliyuncs.com/?Action=DescribeDBClusters
&RegionId=cn-hangzhou
&DBClusterIds=pc-****************
&DBClusterDescription=pc-****************
&ConnectionString=********.rwlb.polardb-pg-public.rds.aliyuncs.com
&DBClusterStatus=Running
&DBType=MySQL
&DBVersion=5.6
&RecentCreationInterval=7
&RecentExpirationInterval=6
&Expired=true
&PageSize=30
&PageNumber=10
&ResourceGroupId=rg-**********
&Tag=[{"Key":"MySQL","Value":"5.6"}]
&PayType=Postpaid
&DBNodeIds=pi-***************
&<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>
        <StoragePayType>Prepaid</StoragePayType>
        <ServerlessType>AgileServerless</ServerlessType>
        <StrictConsistency>ON</StrictConsistency>
        <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>
            <Serverless>ON</Serverless>
        </DBNodes>
        <RegionId>cn-hangzhou</RegionId>
        <DeletionLock>0</DeletionLock>
        <DBVersion>5.6</DBVersion>
        <DBClusterId>pc-****************</DBClusterId>
        <DBClusterStatus>Running</DBClusterStatus>
        <ResourceGroupId>rg-************</ResourceGroupId>
        <StorageUsed>3009413120</StorageUsed>
        <StorageSpace>50</StorageSpace>
        <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",
    "StoragePayType" : "Prepaid",
    "ServerlessType" : "AgileServerless",
    "StrictConsistency" : "ON",
    "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",
      "Serverless" : "ON"
    } ],
    "RegionId" : "cn-hangzhou",
    "DeletionLock" : 0,
    "DBVersion" : "5.6",
    "DBClusterId" : "pc-****************",
    "DBClusterStatus" : "Running",
    "ResourceGroupId" : "rg-************",
    "StorageUsed" : 3009413120,
    "StorageSpace" : 50,
    "DBClusterNetworkType" : "VPC",
    "DBClusterDescription" : "GDN-1",
    "ZoneId" : "cn-hangzhou-i",
    "Engine" : "POLARDB",
    "Category" : "Normal"
  } ]
}

Error codes


HTTP status code	Error code	Error message	Description
400	InvalidRegionId.Malformed	The specified parameter RegionId is not valid.	The error message returned because the specified RegionId parameter is invalid.
400	InvalidPageSize.Malformed	The specified parameter PageSize is not valid.	The error message returned because the specified PageSize parameter is invalid.
400	InvalidPageNumber.Malformed	The specified parameter PageNumber is not valid.	The error message returned because the specified PageNumber parameter is invalid.
500	InternalError	The request processing has failed due to some unknown error, exception or failure.	The error message returned because an internal error has occurred.
503	ServiceUnavailable	The request has failed due to a temporary failure of the server.	The error message returned because a temporary server failure has occurred.

For a list of error codes, see Service error codes.