DescribeDBClusters - PolarDB

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 clusters. You can specify keywords to implement fuzzy match.
ConnectionString	String	No	********.rwlb.polardb-pg-public.rds.aliyuncs.com	The endpoint of the database.
DBClusterStatus	String	No	Running	The state of the cluster that you want to query. For more information about valid values, see Cluster status.
DBType	String	No	MySQL	The database engine that the cluster 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: the pay-as-you-go billing method Prepaid: the subscription billing method
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 entries returned.
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 number of returned pages.
Items	Array of DBCluster		Details about the returned clusters.
DBCluster
VpcId	String	vpc-****************	The virtual private cloud (VPC) ID of the cluster.
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	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 point in time when the cluster was created.
PayType	String	Prepaid	The billing method. Valid values: Postpaid: the pay-as-you-go billing method Prepaid: the subscription billing method
StoragePayType	String	Prepaid	The billing method of the storage. Valid values: Postpaid: the pay-as-you-go billing method Prepaid: the subscription billing method
ServerlessType	String	AgileServerless	The type of the serverless cluster. The value of this parameter is fixed to AgileServerless.
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 cluster 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 due to cluster expiration.
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 cluster.
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 region ID of the cluster.
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 cluster 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: GB.
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 database engine that the cluster runs.
Category	String	Normal	The edition of the cluster. Valid values: Normal: Cluster Edition Basic: Single Node Archive: X-Engine NormalMultimaster: Multi-master Cluster (Database/Table)

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>
        <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>
        <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",
    "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,
    "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.