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