查询集群列表 - 云平台 OCP V4.3.0

查询集群列表

更新时间：2026-04-14 11:55:54

编辑

功能说明

该接口用于查询 OCP 所管理的 OceanBase 集群信息。

可以通过集群名的关键词、集群的状态等条件来限定查询范围。主备部署模式时，返回结果同时包含了主集群与备集群，可以通过其属性确认集群的角色。

调用说明

接口约束

调用者需至少是 CLUSTER_VIEWER 角色。
调用者需要通过 OCP 应用服务鉴权。

请求路径

GET /api/v2/ob/clusters

请求参数

body：

参数	类型	必选	示例值	描述
page	Integer	否	1	请求数据的分页页码。值从 1 开始，默认值：1。
size	Integer	否	10	请求数据的分页大小。默认值：10，最大值：2000。
sort	String	否	name,asc	请求数据的排序规则。
name	String	否	foo	集群名的关键词，匹配不区分大小写。
status	StringArray	否	CREATING,RUNNING	集群的状态。取值范围： RUNNING：运行中。 CREATING：创建中。 DELETING：删除中。 STARTING：启动中。 RESTARTING：重启中。 STOPPING：停止中。 STOPPED：已停止。 TAKINGOVER：接管中。 MOVINGOUT：迁出中。 SWITCHOVER：主备集群切换中。 FAILOVER：备集群故障恢复中。 OPERATING 运维中。
withStandby	-	-	-	已废弃，后续将从环境中删除。

返回结果

参数	类型	说明
data	Object	ObCluster 的数据结构，详情请参考下表。
├─ contents	Array	集群信息（包含主从）的数组，详细数据结构见下表。
├─ page	Object	分页信息。
├─ totalElements	Integer	总记录数。
├─ totalPage	Integer	总页数。
├─ number	Integer	当前页码。
├─ size	Integer	当前页大小。
successful	Boolean	请求是否成功。
timestamp	Datetime	服务端完成请求的时间戳。
duration	Integer	服务端处理请求的时间（毫秒）。
status	Integer	符合 HTTP Status 规范的编码。
traceId	String	请求的 Trace ID，用于排查问题。
server	String	响应请求的应用服务的地址。

ObCluster 的数据结构

参数	类型	说明
primaryCluster	Object	当前集群的主集群。
standbyClusters	Array	当前集群的备集群数组。
id	Integer	集群在 OCP 端的 ID。
name	String	集群的名称。
obClusterId	Integer	集群在 OceanBase 端的 ID。
obVersion	String	集群的版本。
status	String	集群的状态，取值范围： RUNNING：运行中 CREATING：创建中 DELETING：删除中 STARTING：启动中 RESTARTING：重启中 STOPPING：停止中 STOPPED：已停止 TAKINGOVER：接管中 MOVINGOUT：迁出中 SWITCHOVER：主备集群切换中 FAILOVER：备集群故障恢复中 OPERATING：运维中
regionCount	Integer	地区个数。
rootServers	Array	Root Server 的信息。
├─ address	String	Root Server 的地址，格式为 `IP:Port`。
├─ role	String	Root Server 的角色，取值范围： LEADER：Leader FOLLOWER：Follower
├─ sql_port	Integer	SQL 端口。
type	String	集群类型，取值范围： PRIMARY：主集群 STANDBY：备集群
regionCount	Integer	Region 数量。
tenantCount	Integer	租户数量。
partitionCount	Integer	分区数量。
serverCount	Integer	OBServer 数量。
delayTime	Float	备库延迟，单位：秒。
syncStatus	String	主备同步状态，取值范围： VALID：有效状态 DISABLED：禁止同步状态 SYNCHRONIZING：同步中
zones	Array	Zone 列表。
createTime	DateTime	创建时间。
updateTime	DateTime	更新时间。
creator	String	创建者。
deadLockDetectionEnabled	Boolean	是否开启自动死锁检测。
failToQueryFromObReason	-	已废弃，后续版本将删除该参数。

Zone 数据结构

参数	类型	说明
name	String	Zone 名。
idcName	String	所属机房名。
regionName	String	所属地域。
servers	Array	Server 列表。
clusterId	Long	集群在 OCP 端的 ID。
obClusterId	Long	集群在 OceanBase 端的 ID。
serverCount	Integer	Server 数。
hostCount	Integer	主机数。

示例

请求示例

查询集群信息的列表，查询第一页且分页大小为 10 。

GET /api/v2/ob/clusters?page=1&size=10

返回示例

{
    "data":{
        "contents":[
            {
                "createTime":"2020-11-29T22:23:12+08:00",
                "creator":"admin",
                "id":1000002,
                "name":"test",
                "obClusterId":4,
                "obVersion":"2.2.73",
                "regionCount":1,
                "rootServers":[
                    {
                        "address":"xxx.xxx.xxx.xxx:2882",
                        "role":"LEADER",
                        "sql_port":2881
                    }
                ],
                "serverCount":1,
                "standbyClusters":[

                ],
                "status":"RUNNING",
                "tenantCount":0,
                "type":"PRIMARY",
                "zones":[
                    {
                        "idcId":1,
                        "idcName":"hz",
                        "innerStatus":"ACTIVE",
                        "name":"zone1",
                        "operateStatus":"NORMAL",
                        "regionName":"hz",
                        "serverCount":1,
                        "servers":[

                        ],
                        "status":"RUNNING"
                    }
                ]
            }
        ],
        "page":{
            "number":1,
            "size":10,
            "totalElements":1,
            "totalPages":1
        }
    },
    "duration":108,
    "server": "a83ad33525",
    "status":200,
    "successful":true,
    "timestamp":"2020-12-02T20:03:58.233+08:00",
    "traceId":"3cfec9a5180748ff"
}