后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读list_biz_hosts_topo是蓝鲸智云配置平台BlueKing CMDB即 bk-cmdb对外提供的 OpenAPI 网关接口之一用于按业务 ID 一次性查询该业务下的主机明细及其所属的集群、模块拓扑关系并支持对集群、模块、主机三个维度的属性进行组合过滤。读完本文你将掌握该接口的完整请求参数结构、querybuilder组合查询规则的写法含嵌套与操作符取值、返回数据结构语义以及它在host_server服务内部的完整执行链路与底层实现原理可直接据此编写可运行的调用代码。本文对应接口文档为 docs/apidoc/apigw/open/zh/list_biz_hosts_topo.md英文版见 docs/apidoc/apigw/open/en/list_biz_hosts_topo.md。接口文档按 API Gateway 资源文档规范组织存放于仓库的 API Gateway 接口文档目录参见 docs/apidoc/apigw/README.md。接口概述项说明接口名称list_biz_hosts_topo请求方法POST路由host_server 内部/hosts/app/{bk_biz_id}/list_hosts_topo权限业务访问权限Business Access Permission核心能力按业务查询主机明细 主机所属集群/模块拓扑三个维度可叠加过滤该接口的路由注册位于 src/scene_server/host_server/service/service_initfunc.go处理函数为ListBizHostsTopo定义于 src/scene_server/host_server/service/findhost.go。输入参数说明顶层参数参数名称参数类型必选描述pageobject是分页查询条件返回的主机数据按照bk_host_id排序bk_biz_idint是业务 ID同时作为 URL 路径参数{bk_biz_id}set_property_filterobject否集群属性组合查询条件module_property_filterobject否模块属性组合查询条件host_property_filterobject否主机属性组合查询条件fieldsarray是主机属性列表控制返回结果的主机里有哪些字段能够加速接口请求和减少网络流量传输需要说明的是bk_biz_id同时出现在请求体与路径中。从源码看处理函数优先从路径参数解析业务 IDfindhost.go因此调用时务必保证路径与请求体中的业务 ID 一致。page 分页参数参数名称参数类型必选描述startint是记录开始位置limitint是每页限制条数最大 500分页校验在参数结构体ListBizHostsTopoParameter.Validate中完成src/common/metadata/hostserver.gopage.limit必须设置不能为 0且不能超过常量common.BKMaxInstanceLimit即 500否则返回参数校验错误。返回的主机数据按bk_host_id排序。set_property_filter / module_property_filter / host_property_filter这三个参数结构完全一致分别作用于集群、模块、主机三层维度用于根据某层属性字段筛选出该层实例再定位其下/其上的主机。组合支持AND和OR两种方式可以嵌套最多嵌套 2 层过滤规则为四元组field、operator、value。组合节点condition / rules参数名称参数类型必选描述conditionstring否组合查询条件取值AND/ORrulesarray否规则数组元素可以是原子规则也可以是嵌套的组合节点原子规则rules 元素参数名称参数类型必选描述fieldstring是字段名operatorstring是操作符可选值equal,not_equal,in,not_in,less,less_or_equal,greater,greater_or_equal,between,not_betweenvalue-否操作数不同 operator 对应不同的 value 格式组装规则的完整语法与操作符语义可参考 src/common/querybuilder/README.md以及对应实现 src/common/querybuilder/types.go 与 src/common/querybuilder/parser.go。组合查询规则querybuilder详解接口文档中提到的三个*_property_filter参数在底层均由configcenter/src/common/querybuilder包解析。QueryFilter的 JSON/BSON 反序列化即调用ParseRule将请求数据解析为规则树parser.go因此文档给出的嵌套 JSON 可以直接被接口解析。规则模型原子规则与组合规则从源码types.go可以看到规则树由两种节点组成原子规则AtomRule叶子节点由field、operator、value三元组构成是任何过滤规则的基础组合规则CombinedRule非叶子节点由conditionAND/OR与rules可继续嵌套的规则数组构成组合的节点可以是原子规则或组合规则。每个节点实现了统一的Rule接口GetDeep()返回规则深度、Validate()做合法性校验、ToMgo()将规则转换为 MongoDB 查询条件、Match()用于内存匹配。这就是查询条件本质上是过滤规则树的底层模型。嵌套深度限制的真相文档说最多嵌套 2 层其实现依据是MaxDeep 3常量types.go注释明确说明嵌套层级的深度按树的高度计算查询条件最大深度为 3 即最多嵌套 2 层。在 ListBizHostsTopoParameter.Validate 中三个 filter 分别调用GetDeep()并与MaxDeep比较超限即返回host_property_filter.rules/set_property_filter.rules/module_property_filter.rules超限错误。操作符说明接口文档给出的操作符可选值为equal、not_equal、in、not_in、less、less_or_equal、greater、greater_or_equal、between、not_between。需要指出的是src/common/querybuilder/README.md 中明确说明该模块不支持between与not_between运算符这类运算可以基于基本比较运算符组合实现。与此同时实现还额外支持时间操作符datetime_less等仅支持 RFC3339 格式、字符串操作符begins_with、contains、ends_with等、空值操作符is_null、is_not_null、字段存在操作符exist、not_exist以及数组空值操作符is_empty、is_not_empty详见 README 的 Operator 章节 与 types.go 的校验与转换实现。各操作符与 value 格式的对应关系如下操作符含义value 格式equal相等比较基本数据类型数值/bool/字符串not_equal不等比较基本数据类型数值/bool/字符串in字段值在指定集合中同类型基本数据类型组成的数组not_in字段值不在指定集合中同类型基本数据类型组成的数组less字段值 value数值less_or_equal字段值 value数值greater字段值 value数值greater_or_equal字段值 value数值is_empty / is_not_empty数组为空 / 非空不接受参数is_null / is_not_null字段值为 null / 非 null不接受参数exist / not_exist字段存在 / 不存在不接受参数begins_with / not_begins_with以某字符串开头 / 不以某字符串开头非空字符串contains / not_contains包含 / 不包含某字符串非空字符串ends_with / not_ends_with以某字符串结尾 / 不以某字符串结尾非空字符串datetime_less / datetime_less_or_equal / datetime_greater / datetime_greater_or_equal时间早于 / 不晚于 / 晚于 / 不早于RFC3339 格式字符串校验规则可参见 types.go 的validateValueByOperator数组类操作符要求数组元素类型一致接口通过RuleOption{NeedSameSliceElementType: true}开启该校验数值类操作符要求 value 为数值字符串类操作符要求非空字符串。转换到 MongoDB 查询条件时equal/not_equal/in/not_in会先调用ConvertIpv6ToFullWord做 IPv6 全字格式转换types.go这保证了 IPv6 地址字段过滤的正确性。调用示例以下为接口文档给出的完整请求体可直接用于 POST 调用{ page: { start: 0, limit: 10 }, bk_biz_id: 3, fields: [ bk_host_id, bk_cloud_id, bk_host_innerip, bk_os_type, bk_mac ], set_property_filter: { condition: AND, rules: [ { field: bk_set_name, operator: not_equal, value: test }, { condition: OR, rules: [ { field: bk_set_id, operator: in, value: [ 1, 2, 3 ] }, { field: bk_service_status, operator: equal, value: 1 } ] } ] }, module_property_filter: { condition: OR, rules: [ { field: bk_module_name, operator: equal, value: test }, { condition: AND, rules: [ { field: bk_module_id, operator: not_in, value: [ 1, 2, 3 ] }, { field: bk_module_type, operator: equal, value: 1 } ] } ] }, host_property_filter: { condition: AND, rules: [ { field: bk_host_innerip, operator: equal, value: 127.0.0.1 }, { condition: OR, rules: [ { field: bk_os_type, operator: not_in, value: [ 3 ] }, { field: bk_cloud_id, operator: equal, value: 0 } ] } ] } }示例语义拆解page从第 0 条开始每页最多返回 10 条按bk_host_id排序bk_biz_id业务 ID 为 3fields只返回bk_host_id、bk_cloud_id、bk_host_innerip、bk_os_type、bk_mac五个主机字段减少网络传输set_property_filter集群名不等于test且集群 ID 在 1/2/3 中 或 服务状态等于1module_property_filter模块名等于test或模块 ID 不在 1/2/3 中 且 模块类型等于1host_property_filter内网 IP 等于127.0.0.1且系统类型不在[3]中 或 管控区域等于0。该示例同时演示了三个 filter 各自带一层嵌套AND下挂OR或OR下挂AND正好落在最多嵌套 2 层的约束之内。响应示例{ result: true, code: 0, message: success, permission: null, data: { count: 3, info: [ { host: { bk_cloud_id: 0, bk_host_id: 1, bk_host_innerip: 192.168.15.18, bk_mac: , bk_os_type: null }, topo: [ { bk_set_id: 11, bk_set_name: set1, module: [ { bk_module_id: 56, bk_module_name: m1 } ] } ] }, { host: { bk_cloud_id: 0, bk_host_id: 2, bk_host_innerip: 192.168.15.4, bk_mac: , bk_os_type: null }, topo: [ { bk_set_id: 11, bk_set_name: set1, module: [ { bk_module_id: 56, bk_module_name: m1 } ] } ] }, { host: { bk_cloud_id: 0, bk_host_id: 3, bk_host_innerip: 192.168.15.12, bk_mac: , bk_os_type: null }, topo: [ { bk_set_id: 10, bk_set_name: 空闲机池, module: [ { bk_module_id: 54, bk_module_name: 空闲机 } ] } ] } ] } }从响应可以看到每台主机通过host对象携带其实际属性数据通过topo数组携带所属的集群与模块信息未分配具体业务模块的主机如第 3 台会出现在空闲机池 / 空闲机这类默认拓扑节点下。响应参数说明公共响应包装参数名称参数类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataobject请求返回的数据data参数名称参数类型描述countint记录条数infoarray主机数据和拓扑信息data.info参数名称参数类型描述hostdict主机实际数据topoarray主机拓扑信息data.info.host系统内置主机属性参数名称参数类型描述bk_host_namestring主机名bk_host_inneripstring内网 IPbk_host_idint主机 IDbk_cloud_idint管控区域import_fromstring主机导入来源以 api 方式导入为 3bk_asset_idstring固资编号bk_cloud_inst_idstring云主机实例 IDbk_cloud_vendorstring云厂商bk_cloud_host_statusstring云主机状态bk_commentstring备注bk_cpuintCPU 逻辑核心数bk_cpu_architecturestringCPU 架构bk_cpu_modulestringCPU 型号bk_diskint磁盘容量GBbk_host_outeripstring主机外网 IPbk_host_innerip_v6string主机内网 IPv6bk_host_outerip_v6string主机外网 IPv6bk_isp_namestring所属运营商bk_macstring主机内网 MAC 地址bk_memint内存容量MBbk_os_bitstring操作系统位数bk_os_namestring操作系统名称bk_os_typestring操作系统类型bk_os_versionstring操作系统版本bk_outer_macstring主机外网 MAC 地址bk_province_namestring所在省份bk_service_termint质保年限bk_slastringSLA 级别bk_snstring设备 SNbk_statestring当前状态bk_state_namestring所在国家operatorstring主要维护人bk_bak_operatorstring备份维护人注意此处的返回值仅对系统内置的属性字段做了说明其余返回值取决于用户自己定义的属性字段。也就是说如果业务中为主机模型扩展了自定义属性只要出现在请求的fields中同样会返回。data.info.topo参数名称参数类型描述bk_set_idint主机所属的集群 IDbk_set_namestring主机所属的集群名字modulearray主机所属的集群下模块信息data.info.topo.module参数名称参数类型描述bk_module_idint模块 IDbk_module_namestring模块名字上述响应结构在源码中对应 src/common/metadata/hostserver.go 的HostTopoResult、HostTopo、Topo、Module四个结构体其 JSON tag 与文档参数一一对应。源码级执行链路解析接口处理函数ListBizHostsTopo的内部流程可以划分为六个阶段对应 findhost.go路径参数解析与鉴权从路径中解析bk_biz_id为 0 或非法时直接报参数错误随后调用authHostUnderBiz校验当前用户的业务访问权限无权限时返回RespNoAuth请求体反序列化与校验将请求体解析为meta.ListBizHostsTopoParameter调用其Validate方法校验分页参数与三个过滤条件hostserver.go集群维度预过滤调用parseHostsTopoFilterfindhost.go将set_property_filter通过ToMgo()转换为 MongoDB 条件并与bk_biz_id组成 AND 条件查询集群实例得到符合条件的setIDs与setMapID 到名称的映射。若配置了该过滤条件但结果为空直接返回count0的空列表避免后续查询模块维度预过滤同样的逻辑处理module_property_filter得到moduleIDs与moduleMap主机查询以bizID setIDs moduleIDs host_property_filter组装meta.ListHosts查询条件调用CoreService().Host().ListHosts查询主机列表。注意这里会把fields与bk_host_id合并后传给底层保证后续拓扑组装有主机 ID 可用并设置 MongoDB 从节点读偏好SecondaryPreferredMode拓扑组装调用rearrangeBizHostTopofindhost.go补齐拓扑信息——先按主机 ID 集合查询主机-模块关系GetHostRelations生成主机ID - 集群ID - 模块ID列表的映射再对尚未出现在setMap/moduleMap中的集群、模块实例做一次补充查询getOtherInstInfofindhost.go最后按HostTopoResult{count, info:[{host, topo:[{bk_set_id, bk_set_name, module:[{bk_module_id, bk_module_name}]}]}]}的格式组装输出。其中集群/模块实例的查询由GetInstIDNameInfo完成src/scene_server/host_server/logics/instance.go按objID解析实例 ID 与名称字段如 set 的bk_set_id/bk_set_name一次查询出ID - 名称映射供拓扑输出使用。客户端调用方式在 Go 侧apimachinery 提供了封装好的客户端方法ListBizHostsToposrc/apimachinery/hostserver/apis.go其内部即向/hosts/app/%d/list_hosts_topo发起 POST 请求。仓库的集成测试 src/test/host_server/host_test.go 给出了典型的调用与断言模式先通过TransferHostModule将主机转移至目标模块再调用ListBizHostsTopo并断言响应中同时包含count、两台主机的bk_host_id、所属bk_set_id与bk_module_id。这也验证了该接口主机 拓扑一次返回的核心行为。使用建议与注意事项善用 fields 裁剪字段文档明确说明fields用于控制返回的主机字段能加速接口请求并减少网络流量。只声明本次业务需要的字段即可服务端还会在内部追加bk_host_id用于拓扑组装。保持分页参数在约束内page.limit必填且最大 500start从 0 开始结果按bk_host_id排序适合游标式翻页。三过滤器是逐层收窄关系从执行链路看集群过滤与模块过滤会先各自筛出符合条件的实例 ID 集合再与主机属性过滤一起作为主机查询的约束条件三者共同决定最终返回的主机集合而返回的topo则是主机实际所属的完整集群/模块关系。注意嵌套深度与操作符边界组合条件最多嵌套 2 层源码层面对应MaxDeep3的树高限制同时按 src/common/querybuilder/README.md 的说明between/not_between未被该模块实现如需区间查询请用greater_or_equalless_or_equal组合表达。权限前置接口要求业务访问权限无权限的调用会在进入数据查询前被拦截findhost.go。相关资源索引接口中文文档docs/apidoc/apigw/open/zh/list_biz_hosts_topo.md接口英文文档docs/apidoc/apigw/open/en/list_biz_hosts_topo.md组合查询规则说明src/common/querybuilder/README.mdquerybuilder 规则模型与操作符实现src/common/querybuilder/types.go、src/common/querybuilder/parser.go接口处理实现src/scene_server/host_server/service/findhost.go参数与响应结构体src/common/metadata/hostserver.go客户端封装src/apimachinery/hostserver/apis.go集成测试src/test/host_server/host_test.go赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb主机详情与拓扑树查询接口findmany/hosts/detail_topo实战指南蓝鲸配置平台 bk cmdb主机详情与拓扑树查询接口findmany/hosts/detail_topo实战指南 本文基于蓝鲸智云配置平台BlueKin后端企业应用运维蓝鲸智云配置平台 bk-cmdb 主机身份查询接口 search_hostidentifier 实战指南蓝鲸智云配置平台 bk cmdb 主机身份查询接口 search_hostidentifier 实战指南 本指南以蓝鲸智云配置平台bk cmdb对外 API后端企业应用运维蓝鲸智云配置平台bk-cmdbAPI 实战查询主机详情及其拓扑信息list_host_detail_topology蓝鲸智云配置平台bk cmdbAPI 实战查询主机详情及其拓扑信息list_host_detail_topology 本文面向蓝鲸智云配置平台Blu后端企业应用运维上一篇order-book-dynamics性能调优10个提升预测准确率的技巧下一篇import-http vs Deno现代JavaScript模块加载方案对比分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考