后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本篇技术指南围绕蓝鲸智云配置平台bk-cmdbBlueKing CMDB的 ESB 开放接口find_host_topo_relation展开讲解如何一次性获取指定业务下「主机 ↔ 集群 ↔ 模块」之间的挂载关系覆盖请求参数、分页约束、返回结构并深入其内部调用链hostserver → coreservice → MongoDB 模块主机关系表帮助读者在资源梳理、拓扑对齐、批量校验等场景中正确使用该接口。一、接口功能定位与权限说明find_host_topo_relation的核心能力是获取主机与拓扑的关系即在一个业务bk_biz_id范围内查询主机host、集群set、模块module三者之间的归属挂载关系。调用该接口需要业务访问权限Business access permission。该接口属于 ESB企业服务总线对外暴露的 API在仓库的 ESB 接口定义文件 docs/apidoc/cc/cc.yaml 中有明确注册对外路径/v2/cc/find_host_topo_relation/请求方式POST接口类型query查询类映射的内部路径/api/v3/host/topo/relation/read同样为POST也就是说ESB 网关收到请求后会转发到 hostserver 的/host/topo/relation/read路由。该路由在 src/scene_server/host_server/service/service_initfunc.go 中注册对应的处理函数是GetAppHostTopoRelation。二、请求参数说明2.1 通用参数每次调用需携带 ESB 鉴权与用户标识参数对应文档模板{{ common_args_desc }}字段类型必选描述bk_app_codestring是应用 ID用于 ESB 鉴权bk_app_secretstring是应用密钥bk_usernamestring是用户名bk_tokenstring是登录态 token部分调用方式下可用2.2 接口参数字段类型必选描述bk_biz_idint是业务 IDbk_set_idsarray否集群 ID 列表最多 200 条bk_module_idsarray否模块 ID 列表最多 500 条bk_host_idsarray否主机 ID 列表最多 500 条pageobject是分页信息四个筛选字段bk_biz_id、bk_set_ids、bk_module_ids、bk_host_ids可单独或组合使用。从源码角度看该请求体在 src/common/metadata/core_service.go 中被建模为HostModuleRelationRequest结构体其中还包含一个文档未展开的field字段json:field用于指定返回字段属于进阶用法。2.3 page 分页字段字段类型必选描述startint否获取数据的偏移位置从 0 开始limitint是每页数据条数限制建议值为 200分页结构体对应 src/common/metadata/page.go 中的BasePage除start、limit外还支持可选的sort排序字段与enable_count仅统计数量参数。三、请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, page: { start: 0, limit: 10 }, bk_biz_id: 2, bk_set_ids: [1, 2], bk_module_ids: [23, 24], bk_host_ids: [25, 26] }该示例同时指定了业务、集群、模块、主机四类筛选条件并开启分页含义是查询业务 2 下位于集群 1/2、模块 23/24 中且主机 ID 为 25/26 的主机拓扑关系从偏移 0 开始取 10 条。四、返回结果示例{ result: true, code: 0, data: { count: 2, data: [ { bk_biz_id: 2, bk_host_id: 2, bk_module_id: 2, bk_set_id: 2, bk_supplier_account: 0 }, { bk_biz_id: 1, bk_host_id: 1, bk_module_id: 1, bk_set_id: 1, bk_supplier_account: 0 } ], page: { limit: 10, start: 0 } }, message: success, permission: null, request_id: f5a6331d4bc2433587a63390c76ba7bf }返回结果采用蓝鲸标准响应封装request_id为本次请求的请求链 ID便于在日志中串联定位问题。五、返回结果参数说明5.1 response 顶层字段字段类型描述resultbool请求是否成功true 成功false 失败codeint错误编码0 表示 success0 表示失败messagestring请求失败时返回的错误信息permissionobject权限信息request_idstring请求链 IDdataobject请求返回的数据5.2 data 字段说明字段类型描述countint满足条件的记录条数dataobject array业务下主机与集群、模块的关系数据详情列表pageobject分页信息回显本次请求的 start、limit5.3 data.data 字段说明字段类型描述bk_biz_idint业务 IDbk_set_idint集群 IDbk_module_idint模块 IDbk_host_idint主机 IDbk_supplier_accountstring开发商供应商账号其中每条记录对应一条主机与模块的挂载关系bk_set_id、bk_module_id、bk_host_id共同定位该关系。该结构在源码中的建模为 src/common/metadata/hostcontroller.go 的ModuleHost结构体字段 JSON 标签与上表完全一致且主机、模块、业务字段在序列化时使用omitempty即值为 0 的字段不会出现在输出中。5.4 data.page 字段说明字段类型描述startint数据偏移位置limitint每页数据条数限制六、内部调用链与源码级实现原理理解接口背后的调用链有助于解释参数约束与错误行为。整体链路如下ESB 网关 /v2/cc/find_host_topo_relation/ → hostserver /host/topo/relation/read (GetAppHostTopoRelation) → hostserver Logics.GetHostModuleRelation参数校验 → coreservice Host().GetHostModuleRelation组装查询条件 → MongoDB cc_ModuleHostConfig 表模块主机关系表6.1 hostserver 层路由注册与请求解码路由注册位于 src/scene_server/host_server/service/service_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /host/topo/relation/read, Handler: s.GetAppHostTopoRelation})处理函数GetAppHostTopoRelation位于 src/scene_server/host_server/service/module.go将请求体解码为metadata.HostModuleRelationRequest后调用Logic.GetHostModuleRelation最终以ctx.RespEntity(result)返回结果。6.2 hostserver 层参数校验规则核心校验逻辑位于 src/scene_server/host_server/logics/host.go按顺序执行四道检查请求体非空校验若bk_biz_id为 0 且bk_set_ids、bk_module_ids、bk_host_ids均为空结构体的Empty()方法判定直接返回错误码CCErrCommHTTPBodyEmpty1199005对应 src/common/errInfo.go即请求体未设置有效数据。分页合法性校验调用cond.Page.IsIllegal()当start 0、limit 1000全局单页上限BKMaxPageSize 1000定义于 src/common/definitions.go或limit 0时返回CCErrCommPageLimitIsExceeded1199059。例外是limit取特殊值BKNoLimit999999999定义于同文件第 41 行时不受上限约束。集群数量校验bk_set_ids超过 200 条时返回CCErrCommXXExceedLimit1199035错误信息指明bk_set_ids超限。模块与主机数量校验bk_module_ids或bk_host_ids超过 500 条时同样返回 1199035 错误。这些校验与文档中最多 200 条 / 最多 500 条的约束一一对应是调用侧最容易触发的错误来源。6.3 coreservice 层关系数据查询校验通过后hostserver 通过 CoreService API 调用 coreservice。真正落库查询在 src/source_controller/coreservice/core/host/transfer/manager.go 的GetHostModuleRelation中完成基于condition.CreateCondition()按需拼接查询条件bk_biz_id等值、bk_host_id/bk_module_id/bk_set_id走In列表匹配通过util.SetQueryOwner注入当前调用者的bk_supplier_account供应商账号实现租户数据隔离查询目标是common.BKTableNameModuleHostConfig即模块主机关系表先Count统计总数再按start/sort/limit拉取当前页数据最终封装为HostConfigData{ Count, Info: []ModuleHost, Page }返回与文档中的data{count, data[], page}结构一致。值得注意的是查询条件中若所有筛选字段均为空coreservice 会直接返回空结果而不执行全表扫描这也解释了为什么上层要求bk_biz_id必填——避免无界查询。七、调用实战要点与注意事项分页建议文档与源码均建议limit取 200。单次上限 1000 由系统常量BKMaxPageSize决定src/common/definitions.go数据量大时应基于data.count循环翻页start limit直到取满为止。筛选条件可组合bk_set_ids、bk_module_ids、bk_host_ids为且关系传入多个集群 ID 时返回的是这些集群下全部模块的主机关系不传则查询业务下所有关系。如需精确到具体主机建议同时传bk_host_ids以缩小结果集。业务权限前置调用前需确认当前bk_username具备目标业务的访问权限否则permission字段会携带缺失的权限信息且result为 false。响应字段省略data.data中值为 0 的字段如bk_set_id在 JSON 输出中可能被省略omitempty解析响应时应按字段可能缺失处理避免直接断言字段存在。错误码速查1199005请求体为空1199035列表参数超限bk_set_ids200 或bk_module_ids/bk_host_ids5001199059分页参数非法。对应定义见 src/common/errInfo.go。八、典型应用场景主机资源梳理批量导出某业务下所有主机所属的集群与模块生成业务-集群-模块-主机四元组清单用于资产盘点拓扑一致性校验结合bk_host_ids精确核对指定主机当前挂载的模块是否与预期一致如变更发布后校验主机自动化编排在主机转移、模块变更前先查询关系快照作为操作前数据对比与操作后复核的依据源码中多处使用DistinctHostIDByTopoRelationRequest复用类似查询逻辑如 src/scene_server/host_server/logics/hostsearch.go。该接口是 bk-cmdb 提供主机拓扑关系读取能力的标准入口配合 ESB 鉴权参数即可在第三方系统运维平台、作业平台等中稳定复用。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云配置平台bk-cmdb主机与拓扑关系查询接口 find_host_topo_relation 实战指南蓝鲸智云配置平台bk cmdb主机与拓扑关系查询接口 find_host_topo_relation 实战指南 导读 find_host_topo_rela后端企业应用运维bk-cmdb 业务主线拓扑节点简要关系查询接口find_brief_biz_topo_node_relation实战指南bk cmdb 业务主线拓扑节点简要关系查询接口find_brief_biz_topo_node_relation实战指南 导读 本文围绕蓝鲸智云配置平台后端企业应用运维bk-cmdb 容器拓扑查询接口 list_kube_container_by_topo 实战指南bk cmdb 容器拓扑查询接口 list_kube_container_by_topo 实战指南 本篇指南系统讲解蓝鲸智云配置平台bk cmdb开放 AP后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
