全部产品
Search

搜索本产品

    云原生数据库 PolarDB：DescribeDBInstanceTopology - 查询实例拓扑信息

    文档中心

    云原生数据库 PolarDB：DescribeDBInstanceTopology - 查询实例拓扑信息

    更新时间：Sep 10, 2026

    调用DescribeDBInstanceTopology接口获取实例拓扑信息。

    调试

    您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

    调试

    授权信息

    下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

    • 操作：是指具体的权限点。

    • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

    • 资源类型：是指操作中支持授权的资源类型。具体说明如下：

      • 对于必选的资源类型，用前面加 * 表示。

      • 对于不支持资源级授权的操作，用全部资源表示。

    • 条件关键字：是指云产品自身定义的条件关键字。

    • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

    操作

    访问级别

    资源类型

    条件关键字

    关联操作

    polardbx:DescribeDBInstanceTopology

    get

    *全部资源

    *

    		 无 无

    请求参数

    名称

    类型

    必填

    描述

    示例值
    RegionId

    string

    是

    实例所属的地域 ID。

    cn-hangzhou
    DBInstanceName

    string

    是

    实例 ID。

    pxc-********
    StartTime

    string

    否

    查询拓扑中历史实例范围开始时间，格式为 yyyy-MM-dd HH:mm:ss。

    2021-10-21T10:30:45Z 04:00:00
    EndTime

    string

    否

    查询拓扑中历史实例范围结束时间，格式为 yyyy-MM-dd HH:mm:ss。

    2021-10-22T10:30:45Z 04:00:00
    MinuteSimple

    boolean

    否

    是否查询历史拓扑。

    true

    返回参数

    名称

    类型

    描述

    示例值

    object

    RequestId

    string

    请求 ID。

    C458B1E8-1683-3645-B154-6BA32080EEA
    Data

    object

    数据结构体。

    LogicInstanceTopology

    object

    拓扑信息。

    DBInstanceName

    string

    实例名称。

    pxc-sprcym7g7w****
    DBInstanceCreateTime

    string

    实例创建时间，格式为 yyyy-MM-dd HH:mm:ss。

    2021-10-21T10:30:45Z 04:00:00
    MaintainStartTime

    string

    运维开始时间，格式为 HH:mm:ss。

    04:00:00
    MaintainEndTime

    string

    运维结束时间，格式为 HH:mm:ss。

    05:00:00
    LockReason

    string

    锁定原因。

    欠费
    DBInstanceStatus

    integer

    实例状态。

    8
    LockMode

    integer

    锁定状态 ：

    • 0：未锁定；

    • 1：锁定。

    0
    EngineVersion

    string

    引擎版本，默认 2.0。

    2.0
    DBInstanceStorage

    integer

    存储节点个数。

    1
    DBInstanceConnType

    string

    表示用 lvs 做负载均衡。

    lvs
    DBInstanceId

    string

    实例 ID。

    304726047
    Engine

    string

    引擎， 默认：polarx。

    polarx
    DBInstanceDescription

    string

    实例描述。

    pxc-sprcym7******
    DBInstanceStatusDescription

    string

    实例状态描述。

    TDE_MODIFYING
    Items

    array<object>

    节点列表。

    array<object>

    节点信息。

    DBInstanceCreateTime

    string

    实例创建时间。

    2021-10-21T10:30:45Z
    DBInstanceName

    string

    实例名称。

    pxc-i-tk6t4z****
    CharacterType

    string

    节点属性，取值如下：

    • polarx_cn：计算节点；

    • polarx_store：数据节点；

    • polarx_gms：GMS 节点。

    节点角色
    MaintainStartTime

    string

    运维开始时间。

    不展示
    DiskSize

    integer

    磁盘大小。

    3145728
    MaintainEndTime

    string

    运维结束时间。

    不展示
    LockReason

    string

    锁定原因。

    不展示
    DBInstanceStatus

    integer

    实例状态。

    8
    LockMode

    integer

    是否锁定，取值如下：

    • 0：未锁定；

    • 1：锁定。

    0
    EngineVersion

    string

    引擎版本，默认 2.0。

    5.7
    DBInstanceConnType

    integer

    连接类型。

    不展示
    MaxConnections

    integer

    最大连接数。

    4000
    DBInstanceId

    string

    实例 ID。

    304726049
    Engine

    string

    引擎版本，取值如下：

    • **mysql **

    • polarx_cdc

    • polarx_dn

    mysql
    MaxIops

    integer

    最大 Iops。

    7000
    DBInstanceDescription

    string

    实例描述。

    不展示
    DBInstanceStatusDescription

    string

    实例状态描述。

    不展示
    ConnectionIp

    array<object>

    数据结构体。

    object

    连接信息。

    Port

    string

    端口。

    3306
    DBInstanceNetType

    integer

    内部连接的方式，固定取值为 1，表示经典网络。

    1
    ConnectionString

    string

    连接信息。

    pxc-xdb-m-pxcdym7g7w********.mysql.singapore.rds.aliyuncs.com
    Region

    string

    节点所属地域，如果为 RDS 节点，多个子节点的地域以 ';' 分割。

    cn-hangzhou
    Azone

    string

    节点所属可用区，如果为 RDS 节点，多个子节点的可用区以';'分割。

    cn-hangzhou-a
    Role

    string

    节点角色，取值如下：

    • master：主节点

    • standby：备节点

    master
    Activated

    boolean

    节点是否启用，计算层仅启用主可用区节点，在实例执行主备切换后计算层备用节点会切换为主节点，所有存储层节点均启用。

    true
    AzoneRoleList

    array<object>

    RDS 三节点的数据信息列表。

    object

    Azone

    string

    RDS 三节点中某个节点所属可用区。

    cn-hangzhou-a
    Role

    string

    RDS 三节点中某个节点的角色，取值如下：

    • leader：主节点

    • follower：从节点

    • logger：日志节点

    leader
    Status

    string

    节点状态：

    • 0：运行中

    • 1：创建中

    • 2：异常

    • 3：已过期

    • 4：释放中

    • 5：已释放

    • 6：锁定

    0
    NodeClass

    string

    节点规格：

    • polarx.x4.medium.2e：2 核 8 GB

    • polarx.x4.large.2e：4 核 16 GB

    • polarx.x8.large.2e：4 核 32 GB

    • polarx.x4.xlarge.2e：8 核 32 GB

    • polarx.x8.xlarge.2e：8 核 64 GB

    • polarx.x4.2xlarge.2e：16 核 64 GB

    • polarx.x8.2xlarge.2e：16 核 128 GB

    • polarx.x4.4xlarge.2e：32 核 128 GB

    • polarx.x8.4xlarge.2e：32 核 256 GB

    • polarx.st.8xlarge.2e：60 核 470 GB

    • polarx.st.12xlarge.2e：90 核 720 GB

    polarx.x4.large.2e
    Version

    string

    日志节点版本。

    polarx-cdc-kernel-2.0.0-3985896
    PhyInstanceName

    string

    物理实例名

    pxc-unrbk8oyz**********
    StorageUsed

    string

    存储空间的使用量，单位为 MB。

    16681
    InstanceClusterName

    string

    实例 CN 集群名称，例如 default

    ReadType

    string

    读写类型，例如 ReadWrite

    HistoryItems

    array<object>

    历史节点列表。

    object

    CharacterType

    string

    节点属性，取值如下：

    • polarx_cn：计算节点；

    • polarx_store：数据节点；

    • polarx_gms：GMS 节点。

    节点角色
    Role

    string

    节点角色，取值如下：

    • master：主节点

    • standby：备节点

    master
    DBInstanceName

    string

    实例名称。

    pxc-sprcym7g7w****
    DBInstanceId

    string

    实例 ID。

    304726049
    Region

    string

    节点所属地域，如果为 RDS 节点，多个子节点的地域以 ';' 分割。

    cn-hangzhou
    Azone

    string

    节点所属可用区，如果为 RDS 节点，多个子节点的可用区以';'分割。

    cn-hangzhou-a
    Activated

    boolean

    节点是否启用，计算层仅启用主可用区节点，在实例执行主备切换后计算层备用节点会切换为主节点，所有存储层节点均启用。

    true
    PhyInstanceName

    string

    物理实例名。

    pxc-unrbk8oyz**********

    示例

    正常返回示例

    JSON格式

    {
  "RequestId": "C458B1E8-1683-3645-B154-6BA32080EEA",
  "Data": {
    "LogicInstanceTopology": {
      "DBInstanceName": "pxc-sprcym7g7w****",
      "DBInstanceCreateTime": "2021-10-21T10:30:45Z 04:00:00",
      "MaintainStartTime": "04:00:00",
      "MaintainEndTime": "05:00:00",
      "LockReason": "欠费",
      "DBInstanceStatus": 8,
      "LockMode": 0,
      "EngineVersion": "2.0",
      "DBInstanceStorage": 1,
      "DBInstanceConnType": "lvs",
      "DBInstanceId": "304726047",
      "Engine": "polarx",
      "DBInstanceDescription": "pxc-sprcym7******",
      "DBInstanceStatusDescription": "TDE_MODIFYING",
      "Items": [
        {
          "DBInstanceCreateTime": "2021-10-21T10:30:45Z",
          "DBInstanceName": "pxc-i-tk6t4z****",
          "CharacterType": "节点角色",
          "MaintainStartTime": "不展示",
          "DiskSize": 3145728,
          "MaintainEndTime": "不展示",
          "LockReason": "不展示",
          "DBInstanceStatus": 8,
          "LockMode": 0,
          "EngineVersion": "5.7",
          "DBInstanceConnType": 0,
          "MaxConnections": 4000,
          "DBInstanceId": "304726049",
          "Engine": "mysql",
          "MaxIops": 7000,
          "DBInstanceDescription": "不展示",
          "DBInstanceStatusDescription": "不展示",
          "ConnectionIp": [
            {
              "Port": "3306",
              "DBInstanceNetType": 1,
              "ConnectionString": "pxc-xdb-m-pxcdym7g7w********.mysql.singapore.rds.aliyuncs.com"
            }
          ],
          "Region": "cn-hangzhou",
          "Azone": "cn-hangzhou-a",
          "Role": "master",
          "Activated": true,
          "AzoneRoleList": [
            {
              "Azone": "cn-hangzhou-a",
              "Role": "leader"
            }
          ],
          "Status": "0",
          "NodeClass": "polarx.x4.large.2e",
          "Version": "polarx-cdc-kernel-2.0.0-3985896",
          "PhyInstanceName": "pxc-unrbk8oyz**********",
          "StorageUsed": "16681",
          "InstanceClusterName": "",
          "ReadType": ""
        }
      ],
      "HistoryItems": [
        {
          "CharacterType": "节点角色",
          "Role": "master",
          "DBInstanceName": "pxc-sprcym7g7w****",
          "DBInstanceId": "304726049",
          "Region": "cn-hangzhou",
          "Azone": "cn-hangzhou-a",
          "Activated": true,
          "PhyInstanceName": "pxc-unrbk8oyz**********"
        }
      ]
    }
  }
}

    错误码

    HTTP status code

    错误码

    错误信息

    描述
    403 RAM.Permission.Denied RAM authentication failed. RAM鉴权失败
    404 InvalidDBInstance.NotFound The specified DB instance does not exist. 数据库实例不存在

    访问错误中心查看更多错误码。

    变更历史

    更多信息，参考变更详情。