后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载业务集Business Set是蓝鲸智云配置平台bk-cmdb用于跨业务聚合管理拓扑与主机的核心概念。list_business_set_topo接口用于在指定业务集范围内按父节点查询其下一层拓扑节点模型实例的 ID 与名称信息是搭建业务集拓扑树的基础数据源。本文基于当前仓库的接口文档、API 网关配置与服务端源码完整讲解该接口的请求参数、返回结构、底层实现原理与典型调用场景读完即可独立接入并正确解析返回值。接口概述接口路径ESB 版/v2/cc/list_business_set_topo/底层转发路径CMDB 版/api/v3/find/biz_set/topo_path请求方法POST功能查询业务集拓扑即按父节点返回其子层拓扑节点的实例 ID、实例名称等信息版本要求v3.10.12权限要求业务集访问访问该接口需要具备对应业务集的访问权限该接口在 ESB 组件清单 docs/apidoc/cc/cc.yaml 中有明确登记api_type: query查询类接口suggest_method: POST网关组件为generic.v2.cc.cc_component转发目标是dest_path: /api/v3/find/biz_set/topo_path。在 API 网关开放资源定义 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中/api/v3/find/biz_set/topo_path对应的operationId即为list_business_set_topo并配置了默认限流策略1 秒 100 个令牌。请求参数详解请求体中除通用鉴权参数bk_app_code、bk_app_secret、bk_username、bk_token外接口参数如下字段类型必选描述bk_biz_set_idint是业务集 IDbk_parent_obj_idstring是需要查询模型的 parent 对象 ID父节点的模型 ID如bk_biz_set_obj、biz、set、module或自定义主线模型bk_parent_idint是需要查询模型的 parent ID父节点实例 ID请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_set_id: 3, bk_parent_obj_id: bk_biz_set_obj, bk_parent_id: 344 }参数校验逻辑服务端对三个必选字段逐一进行非空校验见 src/common/metadata/toposerver.go 中FindBizSetTopoOption.Validate()的实现bk_biz_set_id、bk_parent_id为 0 或bk_parent_obj_id为空字符串时会返回参数缺失错误CCErrCommParamsNeedSet。因此业务集 ID 与拓扑实例 ID 都是从 1 开始的正整数调用时务必确保三个字段同时给出。返回结果详解返回结果示例{ result: true, code: 0, message: success, permission: null, data: [ { bk_obj_id: bk_biz_set_obj, bk_inst_id: 5, bk_inst_name: xxx, default: 0 }, { bk_obj_id: bk_biz_set_obj, bk_inst_id: 6, bk_inst_name: xxx, default: 0 } ], request_id: dsda1122adasadadada2222 }response 字段说明字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataarray请求返回的数据request_idstring请求链 id用于全链路日志追踪data 字段说明data为拓扑节点数组每个元素对应一个子层拓扑实例字段类型描述bk_obj_idstring模型对象 ID如biz、set、module或自定义主线模型 IDbk_inst_idint模型实例 IDbk_inst_namestring模型实例名称defaultint模型实例分类默认 01表示内置默认实例如业务下的空闲机池默认集群等从返回结构可以看出该接口返回的是子层拓扑节点的摘要信息ID、名称、分类而非完整实例字段。前端拿到bk_inst_id与bk_obj_id后可继续下钻逐层展开业务集拓扑树。底层实现原理服务端处理流程服务端路由注册在 src/scene_server/topo_server/service/service_initfunc.go核心逻辑位于 src/scene_server/topo_server/service/inst_business_set.go 的FindBizSetTopo处理器与findBizSetTopo业务函数L823-L912。其处理流程可概括为解析并校验请求体将 JSON 反序列化为metadata.FindBizSetTopoOption随后调用Validate()校验必填参数。解析业务集范围scope根据bk_biz_set_id读取业务集配置将其Scope匹配范围match_all全量匹配或filter条件过滤转换为 Mongo 查询条件见getBizSetBizCondinst_business_set.go。转换时默认排除资源池业务default字段非1与已停用业务data_status非disabled。判断父节点类型并确定子节点模型父节点为业务集bk_biz_set_obj时要求bk_parent_id必须等于bk_biz_set_id直接返回该业务集范围内的业务biz节点列表父节点为业务biz时子节点为集群set父节点为集群set时子节点为模块module父节点为模块module时禁止继续查询模块的子节点是主机主机不属于主线拓扑对象直接返回参数错误其他自定义模型通过主线关联association_kind_id mainline查询其子模型若父模型不是主线模型同样返回参数错误见 inst_business_set.go。校验父节点归属调用checkTopoNodeInBizSetL914-L951确认父节点实例所属的业务确实在业务集范围内防止越权/越界查询。查询子层节点摘要调用getTopoBriefInfoL953-L982按父 ID 查询子层实例仅返回bk_obj_id、bk_inst_id、bk_inst_name、default四个字段并按实例 ID 升序排序。一个值得注意的细节当业务存在自定义主线层级时业务biz下会同时存在默认集群和自定义主线子节点两类子层服务端会合并返回见 inst_business_set.go并在查询集群节点时默认排除资源池集群default为2的空闲机池所在集群。客户端封装仓库为各服务提供了统一的 Go 客户端封装FindBizSetTopo见 src/apimachinery/toposerver/inst/biz_set.go它向/find/biz_set/topo_path发起POST请求并将响应解析为[]mapstr.MapStr。接口声明位于 src/apimachinery/toposerver/inst/api.go。前端 Web 页面同样封装了该方法findChildren见 src/ui/src/service/business-set/topology.js业务集拓扑树组件逐层调用它以展开节点。集成测试验证仓库在 src/test/topo_server/biz_set_test.go 提供了完整的接口集成测试用例覆盖了主要行为与异常路径查询业务集下的业务列表返回 2 个业务节点bk_obj_id均为biz查询业务下的子层拓扑返回默认集群 自定义主线节点验证biz 下同时存在 set 与自定义主线子层的合并返回逻辑沿自定义主线逐层下钻自定义主线节点 → set → module验证自定义主线模型的递归查询能力异常场景业务集 ID 不存在、bk_parent_id与bk_biz_set_id不匹配、父对象为普通对象host、父节点不在业务集范围内均返回错误。这些用例可直接作为接入调试的参考正确的入参组合是bk_parent_obj_id取业务集/业务/集群/模块或自定义主线模型 ID且bk_parent_id必须真实存在于该业务集的范围内。典型调用场景该接口最典型的应用是渲染业务集拓扑树以业务集为根节点先传bk_parent_obj_id: bk_biz_set_obj、bk_parent_id: 业务集ID拿到业务列表再对每个业务传bk_parent_obj_id: biz、bk_parent_id: 业务ID拿到集群与自定义主线子层随后逐层下钻集群set、模块module与自定义主线模型即可完整还原业务集范围内的拓扑结构。返回值中的default字段可用于区分内置默认实例与普通实例配合bk_inst_id/bk_inst_name即可在前端展示节点标识。调用时需注意接口有版本门槛v3.10.12且需要具备对应业务集的访问权限bk_parent_id对应的父节点必须位于该业务集范围内否则服务端会返回参数校验错误。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐bk-cmdb 容器拓扑查询接口 list_kube_container_by_topo 实战指南bk cmdb 容器拓扑查询接口 list_kube_container_by_topo 实战指南 本篇指南系统讲解蓝鲸智云配置平台bk cmdb开放 AP后端企业应用运维蓝鲸 CMDBbk-cmdb查询业务拓扑树简要信息接口 find_biz_tree_brief_info 实战指南蓝鲸 CMDBbk cmdb查询业务拓扑树简要信息接口 find_biz_tree_brief_info 实战指南 本文深入讲解蓝鲸智云配置平台BlueK后端企业应用运维bk-cmdb 主机拓扑查询接口实战ListBizHostsTopo 完整使用指南bk cmdb 主机拓扑查询接口实战ListBizHostsTopo 完整使用指南 导读 本文围绕蓝鲸智云配置平台bk cmdb的 ListBizHost后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考