后端企業(yè)應(yīng)用運(yùn)維【免費(fèi)下載鏈接】bk-cmdb藍(lán)鯨智云配置平臺(tái)(BlueKing CMDB)項(xiàng)目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb點(diǎn)擊查看免費(fèi)下載本篇技術(shù)指南圍繞藍(lán)鯨智云配置平臺(tái)bk-cmdbBlueKing CMDB的 ESB 開(kāi)放接口find_host_topo_relation展開(kāi)講解如何一次性獲取指定業(yè)務(wù)下「主機(jī) ? 集群 ? 模塊」之間的掛載關(guān)系覆蓋請(qǐng)求參數(shù)、分頁(yè)約束、返回結(jié)構(gòu)并深入其內(nèi)部調(diào)用鏈hostserver → coreservice → MongoDB 模塊主機(jī)關(guān)系表幫助讀者在資源梳理、拓?fù)鋵?duì)齊、批量校驗(yàn)等場(chǎng)景中正確使用該接口。一、接口功能定位與權(quán)限說(shuō)明find_host_topo_relation的核心能力是獲取主機(jī)與拓?fù)涞年P(guān)系即在一個(gè)業(yè)務(wù)bk_biz_id范圍內(nèi)查詢主機(jī)host、集群set、模塊module三者之間的歸屬掛載關(guān)系。調(diào)用該接口需要業(yè)務(wù)訪問(wèn)權(quán)限Business access permission。該接口屬于 ESB企業(yè)服務(wù)總線對(duì)外暴露的 API在倉(cāng)庫(kù)的 ESB 接口定義文件 docs/apidoc/cc/cc.yaml 中有明確注冊(cè)對(duì)外路徑/v2/cc/find_host_topo_relation/請(qǐng)求方式POST接口類型query查詢類映射的內(nèi)部路徑/api/v3/host/topo/relation/read同樣為POST也就是說(shuō)ESB 網(wǎng)關(guān)收到請(qǐng)求后會(huì)轉(zhuǎn)發(fā)到 hostserver 的/host/topo/relation/read路由。該路由在 src/scene_server/host_server/service/service_initfunc.go 中注冊(cè)對(duì)應(yīng)的處理函數(shù)是GetAppHostTopoRelation。二、請(qǐng)求參數(shù)說(shuō)明2.1 通用參數(shù)每次調(diào)用需攜帶 ESB 鑒權(quán)與用戶標(biāo)識(shí)參數(shù)對(duì)應(yīng)文檔模板{{ common_args_desc }}字段類型必選描述bk_app_codestring是應(yīng)用 ID用于 ESB 鑒權(quán)bk_app_secretstring是應(yīng)用密鑰bk_usernamestring是用戶名bk_tokenstring是登錄態(tài) token部分調(diào)用方式下可用2.2 接口參數(shù)字段類型必選描述bk_biz_idint是業(yè)務(wù) IDbk_set_idsarray否集群 ID 列表最多 200 條bk_module_idsarray否模塊 ID 列表最多 500 條bk_host_idsarray否主機(jī) ID 列表最多 500 條pageobject是分頁(yè)信息四個(gè)篩選字段bk_biz_id、bk_set_ids、bk_module_ids、bk_host_ids可單獨(dú)或組合使用。從源碼角度看該請(qǐng)求體在 src/common/metadata/core_service.go 中被建模為HostModuleRelationRequest結(jié)構(gòu)體其中還包含一個(gè)文檔未展開(kāi)的field字段json:field用于指定返回字段屬于進(jìn)階用法。2.3 page 分頁(yè)字段字段類型必選描述startint否獲取數(shù)據(jù)的偏移位置從 0 開(kāi)始limitint是每頁(yè)數(shù)據(jù)條數(shù)限制建議值為 200分頁(yè)結(jié)構(gòu)體對(duì)應(yīng) src/common/metadata/page.go 中的BasePage除start、limit外還支持可選的sort排序字段與enable_count僅統(tǒng)計(jì)數(shù)量參數(shù)。三、請(qǐng)求參數(shù)示例{ 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] }該示例同時(shí)指定了業(yè)務(wù)、集群、模塊、主機(jī)四類篩選條件并開(kāi)啟分頁(yè)含義是查詢業(yè)務(wù) 2 下位于集群 1/2、模塊 23/24 中且主機(jī) ID 為 25/26 的主機(jī)拓?fù)潢P(guān)系從偏移 0 開(kāi)始取 10 條。四、返回結(jié)果示例{ 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 }返回結(jié)果采用藍(lán)鯨標(biāo)準(zhǔn)響應(yīng)封裝request_id為本次請(qǐng)求的請(qǐng)求鏈 ID便于在日志中串聯(lián)定位問(wèn)題。五、返回結(jié)果參數(shù)說(shuō)明5.1 response 頂層字段字段類型描述resultbool請(qǐng)求是否成功true 成功false 失敗codeint錯(cuò)誤編碼0 表示 success0 表示失敗messagestring請(qǐng)求失敗時(shí)返回的錯(cuò)誤信息permissionobject權(quán)限信息request_idstring請(qǐng)求鏈 IDdataobject請(qǐng)求返回的數(shù)據(jù)5.2 data 字段說(shuō)明字段類型描述countint滿足條件的記錄條數(shù)dataobject array業(yè)務(wù)下主機(jī)與集群、模塊的關(guān)系數(shù)據(jù)詳情列表pageobject分頁(yè)信息回顯本次請(qǐng)求的 start、limit5.3 data.data 字段說(shuō)明字段類型描述bk_biz_idint業(yè)務(wù) IDbk_set_idint集群 IDbk_module_idint模塊 IDbk_host_idint主機(jī) IDbk_supplier_accountstring開(kāi)發(fā)商供應(yīng)商賬號(hào)其中每條記錄對(duì)應(yīng)一條主機(jī)與模塊的掛載關(guān)系bk_set_id、bk_module_id、bk_host_id共同定位該關(guān)系。該結(jié)構(gòu)在源碼中的建模為 src/common/metadata/hostcontroller.go 的ModuleHost結(jié)構(gòu)體字段 JSON 標(biāo)簽與上表完全一致且主機(jī)、模塊、業(yè)務(wù)字段在序列化時(shí)使用omitempty即值為 0 的字段不會(huì)出現(xiàn)在輸出中。5.4 data.page 字段說(shuō)明字段類型描述startint數(shù)據(jù)偏移位置limitint每頁(yè)數(shù)據(jù)條數(shù)限制六、內(nèi)部調(diào)用鏈與源碼級(jí)實(shí)現(xiàn)原理理解接口背后的調(diào)用鏈有助于解釋參數(shù)約束與錯(cuò)誤行為。整體鏈路如下ESB 網(wǎng)關(guān) /v2/cc/find_host_topo_relation/ → hostserver /host/topo/relation/read (GetAppHostTopoRelation) → hostserver Logics.GetHostModuleRelation參數(shù)校驗(yàn) → coreservice Host().GetHostModuleRelation組裝查詢條件 → MongoDB cc_ModuleHostConfig 表模塊主機(jī)關(guān)系表6.1 hostserver 層路由注冊(cè)與請(qǐng)求解碼路由注冊(cè)位于 src/scene_server/host_server/service/service_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /host/topo/relation/read, Handler: s.GetAppHostTopoRelation})處理函數(shù)GetAppHostTopoRelation位于 src/scene_server/host_server/service/module.go將請(qǐng)求體解碼為metadata.HostModuleRelationRequest后調(diào)用Logic.GetHostModuleRelation最終以ctx.RespEntity(result)返回結(jié)果。6.2 hostserver 層參數(shù)校驗(yàn)規(guī)則核心校驗(yàn)邏輯位于 src/scene_server/host_server/logics/host.go按順序執(zhí)行四道檢查請(qǐng)求體非空校驗(yàn)若bk_biz_id為 0 且bk_set_ids、bk_module_ids、bk_host_ids均為空結(jié)構(gòu)體的Empty()方法判定直接返回錯(cuò)誤碼CCErrCommHTTPBodyEmpty1199005對(duì)應(yīng) src/common/errInfo.go即請(qǐng)求體未設(shè)置有效數(shù)據(jù)。分頁(yè)合法性校驗(yàn)調(diào)用cond.Page.IsIllegal()當(dāng)start 0、limit 1000全局單頁(yè)上限BKMaxPageSize 1000定義于 src/common/definitions.go或limit 0時(shí)返回CCErrCommPageLimitIsExceeded1199059。例外是limit取特殊值BKNoLimit999999999定義于同文件第 41 行時(shí)不受上限約束。集群數(shù)量校驗(yàn)bk_set_ids超過(guò) 200 條時(shí)返回CCErrCommXXExceedLimit1199035錯(cuò)誤信息指明bk_set_ids超限。模塊與主機(jī)數(shù)量校驗(yàn)bk_module_ids或bk_host_ids超過(guò) 500 條時(shí)同樣返回 1199035 錯(cuò)誤。這些校驗(yàn)與文檔中最多 200 條 / 最多 500 條的約束一一對(duì)應(yīng)是調(diào)用側(cè)最容易觸發(fā)的錯(cuò)誤來(lái)源。6.3 coreservice 層關(guān)系數(shù)據(jù)查詢校驗(yàn)通過(guò)后hostserver 通過(guò) CoreService API 調(diào)用 coreservice。真正落庫(kù)查詢?cè)?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列表匹配通過(guò)util.SetQueryOwner注入當(dāng)前調(diào)用者的bk_supplier_account供應(yīng)商賬號(hào)實(shí)現(xiàn)租戶數(shù)據(jù)隔離查詢目標(biāo)是common.BKTableNameModuleHostConfig即模塊主機(jī)關(guān)系表先Count統(tǒng)計(jì)總數(shù)再按start/sort/limit拉取當(dāng)前頁(yè)數(shù)據(jù)最終封裝為HostConfigData{ Count, Info: []ModuleHost, Page }返回與文檔中的data{count, data[], page}結(jié)構(gòu)一致。值得注意的是查詢條件中若所有篩選字段均為空coreservice 會(huì)直接返回空結(jié)果而不執(zhí)行全表掃描這也解釋了為什么上層要求bk_biz_id必填——避免無(wú)界查詢。七、調(diào)用實(shí)戰(zhàn)要點(diǎn)與注意事項(xiàng)分頁(yè)建議文檔與源碼均建議limit取 200。單次上限 1000 由系統(tǒng)常量BKMaxPageSize決定src/common/definitions.go數(shù)據(jù)量大時(shí)應(yīng)基于data.count循環(huán)翻頁(yè)start limit直到取滿為止。篩選條件可組合bk_set_ids、bk_module_ids、bk_host_ids為且關(guān)系傳入多個(gè)集群 ID 時(shí)返回的是這些集群下全部模塊的主機(jī)關(guān)系不傳則查詢業(yè)務(wù)下所有關(guān)系。如需精確到具體主機(jī)建議同時(shí)傳bk_host_ids以縮小結(jié)果集。業(yè)務(wù)權(quán)限前置調(diào)用前需確認(rèn)當(dāng)前bk_username具備目標(biāo)業(yè)務(wù)的訪問(wèn)權(quán)限否則permission字段會(huì)攜帶缺失的權(quán)限信息且result為 false。響應(yīng)字段省略data.data中值為 0 的字段如bk_set_id在 JSON 輸出中可能被省略omitempty解析響應(yīng)時(shí)應(yīng)按字段可能缺失處理避免直接斷言字段存在。錯(cuò)誤碼速查1199005請(qǐng)求體為空1199035列表參數(shù)超限bk_set_ids200 或bk_module_ids/bk_host_ids5001199059分頁(yè)參數(shù)非法。對(duì)應(yīng)定義見(jiàn) src/common/errInfo.go。八、典型應(yīng)用場(chǎng)景主機(jī)資源梳理批量導(dǎo)出某業(yè)務(wù)下所有主機(jī)所屬的集群與模塊生成業(yè)務(wù)-集群-模塊-主機(jī)四元組清單用于資產(chǎn)盤(pán)點(diǎn)拓?fù)湟恢滦孕ｒ?yàn)結(jié)合bk_host_ids精確核對(duì)指定主機(jī)當(dāng)前掛載的模塊是否與預(yù)期一致如變更發(fā)布后校驗(yàn)主機(jī)自動(dòng)化編排在主機(jī)轉(zhuǎn)移、模塊變更前先查詢關(guān)系快照作為操作前數(shù)據(jù)對(duì)比與操作后復(fù)核的依據(jù)源碼中多處使用DistinctHostIDByTopoRelationRequest復(fù)用類似查詢邏輯如 src/scene_server/host_server/logics/hostsearch.go。該接口是 bk-cmdb 提供主機(jī)拓?fù)潢P(guān)系讀取能力的標(biāo)準(zhǔn)入口配合 ESB 鑒權(quán)參數(shù)即可在第三方系統(tǒng)運(yùn)維平臺(tái)、作業(yè)平臺(tái)等中穩(wěn)定復(fù)用。贊分享后端企業(yè)應(yīng)用運(yùn)維【免費(fèi)下載鏈接】bk-cmdb藍(lán)鯨智云配置平臺(tái)(BlueKing CMDB)項(xiàng)目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb點(diǎn)擊查看免費(fèi)下載相關(guān)推薦藍(lán)鯨智云配置平臺(tái)bk-cmdb主機(jī)與拓?fù)潢P(guān)系查詢接口 find_host_topo_relation 實(shí)戰(zhàn)指南藍(lán)鯨智云配置平臺(tái)bk cmdb主機(jī)與拓?fù)潢P(guān)系查詢接口 find_host_topo_relation 實(shí)戰(zhàn)指南 導(dǎo)讀 find_host_topo_rela后端企業(yè)應(yīng)用運(yùn)維bk-cmdb 業(yè)務(wù)主線拓?fù)涔?jié)點(diǎn)簡(jiǎn)要關(guān)系查詢接口find_brief_biz_topo_node_relation實(shí)戰(zhàn)指南bk cmdb 業(yè)務(wù)主線拓?fù)涔?jié)點(diǎn)簡(jiǎn)要關(guān)系查詢接口find_brief_biz_topo_node_relation實(shí)戰(zhàn)指南 導(dǎo)讀 本文圍繞藍(lán)鯨智云配置平臺(tái)后端企業(yè)應(yīng)用運(yùn)維bk-cmdb 容器拓?fù)洳樵兘涌?list_kube_container_by_topo 實(shí)戰(zhàn)指南bk cmdb 容器拓?fù)洳樵兘涌?list_kube_container_by_topo 實(shí)戰(zhàn)指南 本篇指南系統(tǒng)講解藍(lán)鯨智云配置平臺(tái)bk cmdb開(kāi)放 AP后端企業(yè)應(yīng)用運(yùn)維創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考