蓝鲸配置平台 bk-cmdb 主机详情与拓扑查询接口 `list_host_detail_topology` 实战指南
蓝鲸配置平台 bk-cmdb 主机详情与拓扑查询接口 list_host_detail_topology 实战指南
导读
list_host_detail_topology 是蓝鲸配置平台(BlueKing CMDB,bk-cmdb)对外提供的主机详情 + 所属拓扑联合查询接口:它根据主机属性条件筛选出目标主机,返回每台主机的基础属性字段,并同时返回该主机在业务主线拓扑中所处的完整层级路径(如 国家 → 省份 → 集群 → 模块)。本指南以 docs/apidoc/cc/zh_hans/list_host_detail_topology.md 为主体,结合仓库源码中的参数校验、路由注册与拓扑组装实现,帮你一次性掌握该接口的请求参数结构、host_property_filter 组合过滤规则、分页字段、返回结构与权限要求,并能在实际业务中直接组装可运行的请求与解析响应。
一、接口概览:功能、路径与权限
该接口的功能描述为:根据主机条件信息查询主机详情及其所属的拓扑信息。它面向"主机池"场景(不限定具体业务),权限要求为主机池主机查看权限。
从网关配置文件 docs/apidoc/cc/cc.yaml 可以看到该接口在蓝鲸 API 网关上注册的信息:
| 项目 | 值 |
|---|---|
| 网关路径 | POST /v2/cc/list_host_detail_topology/ |
| 内部目标路径 | POST /api/v3/findmany/hosts/detail_topo |
| 接口类型 | query |
| 调用组件 | generic.v2.cc.cc_component |
也就是说,外部调用方通过网关的 /v2/cc/list_host_detail_topology/ 发起请求后,网关将其转发到 bk-cmdb 的 hostserver(主机服务)内部路由 /findmany/hosts/detail_topo。该路由在 src/scene_server/host_server/service/service_initfunc.go 中注册,对应的处理器为 s.ListHostDetailAndTopology,其实现位于 src/scene_server/host_server/service/findhost.go。
在权限管控层面,src/ac/parser/host.go 将命中 /api/v3/findmany/hosts/detail_topo 的请求映射为 HostInstance 资源类型 + FindMany 动作,交由统一的鉴权框架校验"主机池主机查看"类权限。
二、请求参数详解
2.1 公共参数(common_args_desc)
所有蓝鲸配置平台 API 均需携带公共鉴权参数(即文档中的 {{ common_args_desc }} 占位符所描述的内容),包括:
| 字段 | 类型 | 描述 |
|---|---|---|
bk_app_code |
string | 应用 ID,即蓝鲸智云 API 网关上的应用标识 |
bk_app_secret |
string | 应用密钥,用于接口调用认证 |
bk_username |
string | 用户名 |
bk_token |
string | 登录态 token,与 bk_username 配合完成用户鉴权 |
这些公共参数的具体取值方式取决于你的网关接入形态(蓝鲸桌面登录态或 API 密钥方式),请按实际环境配置。
2.2 接口参数(Interface Parameters)
接口自身的业务参数共三个:
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
page |
dict | 是 | 查询分页条件 |
host_property_filter |
object | 否 | 主机属性组合查询条件,用于按属性过滤主机 |
fields |
array | 是 | 主机属性字段列表,控制返回结果中 host 对象包含哪些字段,按需求填写 |
其中 fields 字段在服务端是必填校验项:从 src/common/metadata/hostserver.go 的 Validate() 实现可见,若 Fields 为空数组,接口会直接返回参数无效错误。同时服务端会在 fields 基础上自动追加 bk_host_id(见 ListHostDetailAndTopology 实现中的 Fields: append(options.Fields, common.BKHostIDField),src/scene_server/host_server/service/findhost.go),因为后续组装拓扑时需要以主机 ID 关联主机与模块关系。
2.3 host_property_filter:组合过滤规则
host_property_filter 是主机属性字段的过滤规则组合,用于按主机属性字段搜索主机。它支持 AND 与 OR 两种组合方式,且可以嵌套,最多嵌套 2 层。每条过滤规则本质是一个四元组:field(字段名)、operator(操作符)、value(操作数)。
过滤规则对象结构:
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
condition |
string | 否 | 组合查询条件,取值为 AND 或 OR |
rules |
array | 否 | 规则列表,元素可以是原子规则或嵌套的组合规则 |
rules 中的原子规则:
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
field |
string | 是 | 字段名,如 bk_host_innerip、bk_os_type、bk_cloud_id |
operator |
string | 是 | 操作符,可选值:equal、not_equal、in、not_in、less、less_or_equal、greater、greater_or_equal、between、not_between |
value |
- | 否 | 操作数,不同的 operator 对应不同的 value 格式 |
关于"最多嵌套 2 层"的说明,可以从源码中得到精确印证:在 src/common/querybuilder/types.go 中定义了 MaxDeep = 3,注释明确写着"嵌套层级的深度按树的高度计算,查询条件最大深度为 3 即最多嵌套 2 层"。同时 src/common/metadata/hostserver.go 在 host_property_filter 非空时会调用 QueryFilter.Validate()(要求数组元素类型一致)并校验 GetDeep() > querybuilder.MaxDeep,超出即返回参数错误。这套过滤规则底层由 src/common/querybuilder 模块实现,它将 JSON 形式的规则树解析并最终转换为 MongoDB 查询条件(Rule 接口的 ToMgo() 方法),支持 src/common/querybuilder/README.md 中列出的完整操作符族(除文档所列通用操作符外,还包括时间比较、字符串匹配、空值判断、字段存在判断等扩展操作符)。
2.4 page:分页参数
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
start |
int | 是 | 记录开始位置(偏移量,从 0 开始) |
limit |
int | 是 | 每页限制条数,最大值为 500 |
sort |
string | 否 | 排序字段,如 bk_host_id |
limit 的最大值 500 在源码中有明确约束:常量 BKMaxInstanceLimit = 500 定义于 src/common/definitions.go,而 ListHostsDetailAndTopoOption.Validate() 中会检查 option.Page.Limit > common.BKMaxInstanceLimit 并返回参数错误(src/common/metadata/hostserver.go)。因此分页查询超过 500 条时需要按页码(如 start: 500、start: 1000)分多次拉取。
2.5 with_biz 扩展参数(源码补充)
从源码数据结构 src/common/metadata/hostserver.go 可以看出,该接口的请求选项 ListHostsDetailAndTopoOption 还支持一个 with_biz(bool)字段——当它为 true 时,返回的拓扑会包含业务(business)层节点信息,并且服务端在 ArrangeHostDetailAndTopology 返回业务 ID 列表后,会对这些业务做"查看业务"资源级别的二次鉴权(见 src/scene_server/host_server/service/findhost.go)。文档正文未展开该参数,但如果你需要拿到"业务 → 集群 → 模块"完整链路(而不仅是自定义层级模型到模块),可以显式携带 with_biz: true。
三、请求参数示例(可直接复用)
{
"bk_app_code": "esb_test",
"bk_app_secret": "xxx",
"bk_username": "xxx",
"bk_token": "xxx",
"page": {
"start": 0,
"limit": 10,
"sort": "bk_host_id"
},
"fields": [
"bk_host_id",
"bk_host_innerip"
],
"host_property_filter": {
"condition": "AND",
"rules": [
{
"field": "bk_host_innerip",
"operator": "equal",
"value": "192.168.1.1"
},
{
"condition": "OR",
"rules": [
{
"field": "bk_os_type",
"operator": "not_in",
"value": [
"3"
]
},
{
"field": "bk_cloud_id",
"operator": "equal",
"value": 0
}
]
}
]
}
}
这个示例本身就是一个标准的两层嵌套过滤:最外层用 AND 组合两条规则——① 内网 IP 等于 192.168.1.1;② 一个 OR 组合,表示操作系统类型不在 ["3"] 中 或 管控区域等于 0。整体语义为:bk_host_innerip == "192.168.1.1" AND (bk_os_type NOT IN ["3"] OR bk_cloud_id == 0)。
注意组合规则与原子规则在结构上的差别:组合节点(带 condition + rules)不写 field/operator/value,而原子节点(带 field/operator/value)不写 condition/rules。这一点在 src/common/querybuilder/README.md 的 demo 中同样如此,组装时可以参照该 README 中的示例继续扩展。
四、返回结果示例
4.1 完整响应样例
{
"result": true,
"code": 0,
"message": "success",
"permission": null,
"request_id": "e43da4ef221746868dc4c837d36f3807",
"data": {
"count": 2,
"info": [
{
"host": {
"bk_host_id": 2,
"bk_host_innerip": "192.168.1.1"
},
"topo": [
{
"inst": {
"obj": "nation",
"name": "中国",
"id": 30
},
"children": [
{
"inst": {
"obj": "province",
"name": "prov-xxx",
"id": 31
},
"children": [
{
"inst": {
"obj": "set",
"name": "set-xxx",
"id": 20
},
"children": [
{
"inst": {
"obj": "module",
"name": "mod-xxx",
"id": 52
},
"children": null
},
{
"inst": {
"obj": "module",
"name": "mod-yy",
"id": 53
},
"children": null
}
]
}
]
}
]
},
{
"inst": {
"obj": "nation",
"name": "国家",
"id": 29
},
"children": [
{
"inst": {
"obj": "province",
"name": "prv1",
"id": 26
},
"children": [
{
"inst": {
"obj": "set",
"name": "set11",
"id": 19
},
"children": [
{
"inst": {
"obj": "module",
"name": "m22",
"id": 51
},
"children": null
}
]
}
]
}
]
}
]
},
{
"host": {
"bk_host_id": 4,
"bk_host_innerip": "192.168.1.2"
},
"topo": [
{
"inst": {
"obj": "set",
"name": "空闲机池",
"id": 2
},
"children": [
{
"inst": {
"obj": "module",
"name": "故障机",
"id": 4
},
"children": null
}
]
}
]
}
]
}
}
从返回样例可以读出三条重要信息:
data.count为命中总数,data.info数组元素与查询结果一一对应;即便info为空,服务端也会返回count: 0与空数组(见 src/scene_server/host_server/service/findhost.go)。- 每台主机的
topo可能包含多条树路径——一台主机可以同时挂载在多个模块/集群下,每条路径都从最顶层的自定义层级模型(如nation国家)一路下钻到set(集群)与module(模块)。 - 位于主机池(资源池)中的主机(如示例中的
空闲机池 → 故障机),其topo从set开始,即资源池本身以集群/模块形态参与拓扑,且不包含自定义层级模型节点。
4.2 响应顶层字段说明(response)
| 字段 | 类型 | 描述 |
|---|---|---|
result |
bool | 请求成功与否。true 表示请求成功,false 表示请求失败 |
code |
int | 错误编码。0 表示 success,>0 表示失败错误 |
message |
string | 请求失败时返回的错误信息 |
permission |
object | 权限信息 |
request_id |
string | 请求链 ID,用于链路追踪与问题排查 |
data |
object | 请求返回的数据 |
4.3 data 与 data.info 结构
data:
| 字段 | 类型 | 描述 |
|---|---|---|
count |
int | 记录条数 |
info |
array | 主机数据和拓扑信息 |
data.info 数组中的每个元素:
| 字段 | 类型 | 描述 |
|---|---|---|
host |
dict | 主机实际数据(字段由请求中的 fields 控制) |
topo |
array | 主机拓扑信息,即该主机所属的拓扑节点树 |
五、返回字段详解
5.1 data.info.host:主机属性字段
下表是系统内置主机属性字段的说明;除此之外,返回值还取决于你在平台上自定义的主机属性字段(模型中扩展的属性)。host 中实际出现的字段由请求参数 fields 决定,未在 fields 中声明的字段不会返回。
| 字段 | 类型 | 描述 |
|---|---|---|
bk_host_name |
string | 主机名 |
bk_host_innerip |
string | 内网 IP |
bk_host_id |
int | 主机 ID |
bk_cloud_id |
int | 管控区域 |
import_from |
string | 主机导入来源,以 api 方式导入为 3 |
bk_asset_id |
string | 固资编号 |
bk_cloud_inst_id |
string | 云主机实例 ID |
bk_cloud_vendor |
string | 云厂商 |
bk_cloud_host_status |
string | 云主机状态 |
bk_comment |
string | 备注 |
bk_cpu |
int | CPU 逻辑核心数 |
bk_cpu_architecture |
string | CPU 架构 |
bk_cpu_module |
string | CPU 型号 |
bk_disk |
int | 磁盘容量(GB) |
bk_host_outerip |
string | 主机外网 IP |
bk_host_innerip_v6 |
string | 主机内网 IPv6 |
bk_host_outerip_v6 |
string | 主机外网 IPv6 |
bk_isp_name |
string | 所属运营商 |
bk_mac |
string | 主机内网 MAC 地址 |
bk_mem |
int | 主机内存容量(MB) |
bk_os_bit |
string | 操作系统位数 |
bk_os_name |
string | 操作系统名称 |
bk_os_type |
string | 操作系统类型 |
bk_os_version |
string | 操作系统版本 |
bk_outer_mac |
string | 主机外网 MAC 地址 |
bk_province_name |
string | 所在省份 |
bk_service_term |
int | 质保年限 |
bk_sla |
string | SLA 级别 |
bk_sn |
string | 设备 SN |
bk_state |
string | 当前状态 |
bk_state_name |
string | 所在国家 |
operator |
string | 主要维护人 |
bk_bak_operator |
string | 备份维护人 |
注意:此处的返回值仅对系统内置的属性字段做了说明,其余返回值取决于用户自己定义的属性字段。
5.2 data.info.topo:拓扑树节点
topo 是一棵(或多棵)嵌套树,每个节点包含实例信息与子节点列表:
| 字段 | 类型 | 描述 |
|---|---|---|
inst |
object | 该节点实例的详情信息 |
inst.obj |
string | 该节点的模型类型,如 set/module 及自定义层级模型类型 |
inst.name |
string | 该节点的实例名 |
inst.id |
int | 该节点的实例 ID |
children |
object array | 当前实例节点的子节点详情信息,可能有多个 |
children.inst |
object | 该子节点的实例详情信息 |
children.children |
string | 该节点的子节点详情信息 |
这棵树的内部数据模型对应源码中的 HostDetailWithTopo / HostTopoNode / NodeInstance(src/common/metadata/hostserver.go):
type HostDetailWithTopo struct {
Host map[string]interface{} `json:"host"`
Topo []*HostTopoNode `json:"topo"`
}
type HostTopoNode struct {
Instance *NodeInstance `json:"inst"`
Children []*HostTopoNode `json:"children"`
}
type NodeInstance struct {
Object string `json:"obj"`
InstName interface{} `json:"name"`
InstID interface{} `json:"id"`
}
children 为 null 表示该节点已经是树的叶子(如 module 层),一个节点下可以挂多个 children(如一个集群下挂多个模块)。
六、服务端实现链路:从请求到响应
理解接口的服务端处理流程,有助于排查返回结果与预期不符的问题。核心处理函数 ListHostDetailAndTopology(src/scene_server/host_server/service/findhost.go)的执行步骤如下:
- 参数解析与校验:将请求体解码为
ListHostsDetailAndTopoOption,调用Validate()校验page、fields、host_property_filter(深度与规则合法性),校验失败即返回参数错误。 - 设置读偏好:
ctx.SetReadPreference(common.SecondaryPreferredMode),即优先从 MongoDB 从节点读取,降低主库压力。 - 查询主机列表:构造
ListHosts(HostPropertyFilter+Fields(自动补bk_host_id) +Page),调用CoreAPI.CoreService().Host().ListHosts查出分页后的主机集合;若结果为空,直接返回count: 0与空数组。 - 组装拓扑:调用
Logic.ArrangeHostDetailAndTopology(kit, withBiz, hosts.Info)为每台主机拼装所属拓扑树。该函数(src/scene_server/host_server/logics/host.go)内部依次执行:- 读取主线拓扑层级顺序(
getTopologyRank,决定返回树从哪层模型开始); - 按主机 ID 批量查询"主机-模块"关系(
GetHostRelations),得到每台主机归属的模块列表; - 批量查询业务、集群、模块的详情(
getInnerObjectDetails); - 逐层向上补齐自定义层级模型的实例信息(
getCustomTopoInfo); - 最终按层级重新组织成
HostDetailWithTopo树(rearrangeHostDetailAndTopo),并将rank反转为"顶层 → 底层"的展示顺序。
- 读取主线拓扑层级顺序(
- 业务级二次鉴权(可选):若
with_biz为true且启用了鉴权管理,会对涉及的业务实例执行"查看业务"授权校验。 - 返回结果:通过
RespEntityWithCount(count, topo)输出data.count与data.info。
值得一提的是,同一套拓扑组装逻辑也被主机搜索相关接口复用(如 src/scene_server/host_server/logics/host.go 处同样调用了 ArrangeHostDetailAndTopology),因此本接口返回的 topo 结构与平台其他"主机带拓扑"查询结果保持一致。
七、常见问题与注意事项
fields不能为空:服务端将空fields视为参数错误(src/common/metadata/hostserver.go);即使你只想拿拓扑,也至少需要传入一个字段(如bk_host_id)。limit上限 500:单页超过 500 条会被拒绝,需要配合start翻页(src/common/definitions.go)。- 过滤规则最多嵌套 2 层:
querybuilder.MaxDeep = 3按树高度计算即两层嵌套(src/common/querybuilder/types.go),超出会返回host_property_filter exceeded max allowed deep之类的参数错误。 value类型需与字段匹配:host_property_filter校验要求同一数组内的元素类型一致(NeedSameSliceElementType: true,见 src/common/metadata/hostserver.go);如in/not_in的数组内不能混用字符串与数字。- 一台主机可能返回多条
topo路径:因为主机可同时归属多个集群/模块,解析响应时不要假设topo只有一条。 - 资源池主机的拓扑从
set开始:主机池中的主机(如"空闲机池/故障机")没有业务与自定义层级模型上下文,topo路径较短。 host返回字段由fields决定:未在fields中声明的内置属性不会返回;自定义属性同理,需显式声明。- 权限要求:调用方需具备主机池主机查看权限;携带
with_biz: true时还会对返回涉及的业务做"查看业务"鉴权,调用前请确认账号权限充足。
结语
list_host_detail_topology 将"主机属性检索"与"拓扑归属查询"合并为一次调用,是 bk-cmdb 中构建"主机视角"资产视图的高频接口。结合本文的请求/返回结构说明与服务端实现链路,你可以准确构造过滤条件、控制返回字段与分页,并正确解析嵌套的拓扑树结果。如需进一步掌握过滤规则的完整操作符体系(时间比较、字符串匹配、空值判断等),可继续阅读仓库内的 src/common/querybuilder/README.md;本接口完整文档以 docs/apidoc/cc/zh_hans/list_host_detail_topology.md 为准。