bk-cmdb 实例关联关系查询进阶指南:find_instassociation_with_inst 接口详解
bk-cmdb 实例关联关系查询进阶指南:find_instassociation_with_inst 接口详解
本文围绕蓝鲸智云配置平台(bk-cmdb)中"查询模型实例关联关系并携带源/目标实例详情"的 API——find/instassociation/object/{bk_obj_id}/inst/detail(文档接口名 find_instassociation_with_inst,v3.10.11+)展开,完整讲解其请求参数、过滤规则组装、分页与返回结构,并深入对应源码实现原理。读者读完后可直接构造可运行的查询请求,理解 condition.asst_filter 过滤规则的嵌套机制与 src_detail/dst_detail 的底层执行路径。
1. 接口概述与适用场景
在 bk-cmdb 中,模型(对象)之间通过"实例关联"(Instance Association)表达数据关系,例如交换机实例 bk_switch 通过 connect 关系关联到主机实例 host。常规的 find_instance_association 接口(API 文档)只能返回关联关系本身(bk_inst_id、bk_asst_inst_id 等),调用方若需同时拿到源实例、目标实例的属性,还得再发查询。
find_instassociation_with_inst 解决了这一问题:一次请求同时返回关联关系、源模型实例详情与目标模型实例详情。它的核心特性:
- 版本要求:v3.10.11 及以上;
- 权限要求:模型实例查询权限(
HasFindModelInstAuth,源码见 topo_server/service/association.go); - 能力扩展:
- 用
asst_filter(querybuilder 组合过滤规则)按关联关系属性过滤; - 用
asst_fields/src_fields/dst_fields分别裁剪三类返回字段; - 用
src_detail/dst_detail控制是否返回源/目标实例详情; - 分页对象为关联关系,非实例。
- 用
从路由注册看(service_business_initfunc.go),该接口实际挂载在 topo_server 上:
POST /find/instassociation/object/{bk_obj_id}/inst/detail
2. 请求参数结构
接口采用 POST + JSON 方式调用,除公共鉴权参数(bk_app_code、bk_app_secret、bk_username、bk_token 等)外,接口参数如下:
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| bk_obj_id | string | 是 | 模型唯一标识,如 bk_switch(也作为路由 Path 参数) |
| condition | map | 是 | 查询参数,内含过滤、字段裁剪与详情开关 |
| page | map | 是 | 分页条件(分页对象为关联关系) |
2.1 condition 子参数
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| asst_filter | map | 是 | 查询关联关系的组合过滤规则(缺失该字段将直接校验失败) |
| asst_fields | array | 否 | 关联关系需要返回的字段,不填返回全部 |
| src_fields | array | 否 | 源模型需要返回的属性,不填返回全部 |
| dst_fields | array | 否 | 目标模型需要返回的属性,不填返回全部 |
| src_detail | bool | 否 | 默认 false,为 true 时返回源模型实例详情 |
| dst_detail | bool | 否 | 默认 false,为 true 时返回目标模型实例详情 |
注意:在标准 API 网关入参中,
src_detail/dst_detail字段名为src_fields/dst_fields之外的布尔开关;二者默认均为false,只有显式传true才会额外查询并返回实例详情。
请求结构在源码中对应 metadata.InstAndAssocRequest(association.go),其中 AsstFilter 类型为 *querybuilder.QueryFilter,这正是"组合过滤规则"(AND/OR 可嵌套)的数据模型。
3. asst_filter:基于 querybuilder 的关联过滤规则
asst_filter 是查询关联关系属性的过滤规则组合,支持 AND 与 OR 两种组合方式,可嵌套,最多嵌套 2 层(对应源码中 MaxDeep = 3,深度按树的高度计算,即最多嵌套 2 层,见 querybuilder/types.go)。
过滤规则为四元组 field / operator / value:
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| condition | string | 是 | 查询条件的组合方式:AND 或 OR(仅这两种取值合法,见 types.go 的 Condition.Validate) |
| rules | array | 是 | 包含所有查询条件的集合,每个元素为一条原子规则或一层子组合 |
3.1 rules 原子规则
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| field | string | 是 | 关联关系属性字段,例如 bk_obj_id、bk_asst_obj_id、bk_inst_id |
| operator | string | 是 | 查询方式,如 equal、in、nin 等 |
| value | string | 是 | 查询条件对应的值(数值、字符串或数组,按操作符而定) |
3.2 可用操作符清单
bk-cmdb 的 querybuilder 模块(src/common/querybuilder)定义了完整操作符集合:
- 通用比较:
equal、not_equal; - 数组操作:
in、not_in、is_empty、is_not_empty; - 数值比较:
less、less_or_equal、greater、greater_or_equal; - 时间比较(
RFC3339格式):datetime_less、datetime_less_or_equal、datetime_greater、datetime_greater_or_equal; - 字符串匹配:
begins_with、not_begins_with、contains、not_contains、ends_with、not_ends_with; - 空值判断:
is_null、is_not_null; - 字段存在性:
exist、not_exist。
注意:querybuilder 不支持 between / not_between,可用基础比较操作符组合实现;in/not_in 的数组元素类型需一致(请求校验时 NeedSameSliceElementType: true,见 association.go)。equal/not_equal 的 value 为基本数据类型(数值/bool/字符串),is_* 类操作符不接收参数。
组合规则示例(来自 querybuilder README 的 demo,README.md):
{
"condition": "AND",
"rules": [
{ "field": "price", "operator": "less", "value": 10.25 },
{
"condition": "OR",
"rules": [
{ "field": "category", "operator": "equal", "value": 2 },
{
"condition": "AND",
"rules": [ { "field": "name", "operator": "not_in", "value": ["a", "b"] } ]
}
]
}
]
}
3.3 过滤规则在服务端的执行
在 topo_server 的实现中(association.go),asst_filter 会先经 request.Condition.AsstFilter.ToMgo() 转换为 MongoDB 查询条件,再封装为 metadata.InstAsstQueryCondition 调用 CoreService 的 ReadInstAssociation 读取关联关系:
assocFilter, errKey, err := request.Condition.AsstFilter.ToMgo()
// ...
cond := &metadata.InstAsstQueryCondition{ObjID: objID, Cond: metadata.QueryCondition{
Condition: assocFilter,
Fields: request.Condition.AsstFields,
Page: request.Page,
DisableCounter: true,
}}
assocRsp, err := s.Engine.CoreAPI.CoreService().Association().ReadInstAssociation(...)
从代码可推断:asst_fields 用于裁剪关联关系返回字段、page 直接作用于关联关系分页;ToMgo() 是 querybuilder 规则接口(Rule)的核心方法之一(另两个为 GetDeep 与 Validate,见 types.go)。
4. page:分页参数
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| start | int | 否 | 记录开始位置(默认 0) |
| limit | int | 是 | 每页限制条数,最大 200 |
| sort | string | 否 | 排序字段,如 -bk_asst_inst_id(负号表示倒序) |
limit 必填且不能超过 200,校验逻辑见 association.go:超过 200 返回 CCErrCommPageLimitIsExceeded,等于 0 返回 CCErrCommParamsNeedSet。
分页对象为关联关系,而非实例详情;排序也作用于关联关系列表(如按 bk_asst_inst_id 排序,示例中倒序排列使 bk_asst_inst_id 从大到小返回)。
5. 完整请求示例(可运行)
以下示例查询模型 bk_switch(交换机)中实例 ID 为 1 的实例,与 host(主机)模型之间的 connect 关联关系,同时返回源实例(交换机)的 bk_inst_id、bk_inst_name 和目标实例(主机)的 bk_host_innerip:
{
"bk_app_code": "esb_test",
"bk_app_secret": "xxx",
"bk_username": "xxx",
"bk_token": "xxx",
"bk_obj_id": "bk_switch",
"condition": {
"asst_filter": {
"condition": "AND",
"rules": [
{
"field": "bk_obj_id",
"operator": "equal",
"value": "bk_switch"
},
{
"field": "bk_inst_id",
"operator": "equal",
"value": 1
},
{
"field": "bk_asst_obj_id",
"operator": "equal",
"value": "host"
}
]
},
"src_fields": [
"bk_inst_id",
"bk_inst_name"
],
"dst_fields": [
"bk_host_innerip"
],
"src_detail": true,
"dst_detail": true
},
"page": {
"start": 0,
"limit": 20,
"sort": "-bk_asst_inst_id"
}
}
要点提示:
asst_filter.rules中的三条equal规则在AND下共同限定"源模型 = bk_switch、源实例 ID = 1、目标模型 = host";src_detail与dst_detail均置true,因此返回体中才会出现src、dst两个数组;- 若不填
src_fields/dst_fields则返回实例全部属性;asst_fields不填则返回关联关系全部字段。
6. 返回结果示例与字段说明
6.1 返回示例
{
"result": true,
"code": 0,
"message": "success",
"permission": null,
"request_id": "e43da4ef221746868dc4c837d36f3807",
"data": {
"association": [
{
"id": 3,
"bk_inst_id": 1,
"bk_obj_id": "bk_switch",
"bk_asst_inst_id": 3,
"bk_asst_obj_id": "host",
"bk_obj_asst_id": "bk_switch_connect_host",
"bk_asst_id": "connect"
},
{
"id": 2,
"bk_inst_id": 1,
"bk_obj_id": "bk_switch",
"bk_asst_inst_id": 2,
"bk_asst_obj_id": "host",
"bk_obj_asst_id": "bk_switch_connect_host",
"bk_asst_id": "connect"
},
{
"id": 1,
"bk_inst_id": 1,
"bk_obj_id": "bk_switch",
"bk_asst_inst_id": 1,
"bk_asst_obj_id": "host",
"bk_obj_asst_id": "bk_switch_connect_host",
"bk_asst_id": "connect"
}
],
"src": [
{
"bk_inst_id": 1,
"bk_inst_name": "s1"
}
],
"dst": [
{
"bk_host_innerip": "10.11.11.1"
},
{
"bk_host_innerip": "10.11.11.2"
},
{
"bk_host_innerip": "10.11.11.3"
}
]
}
}
6.2 公共响应字段
| 字段 | 类型 | 描述 |
|---|---|---|
| result | bool | 请求成功与否:true 成功;false 失败 |
| code | int | 错误码:0 表示 success,>0 表示失败错误 |
| message | string | 请求失败时返回的错误信息 |
| permission | object | 权限信息 |
| request_id | string | 请求链 ID |
| data | object | 请求结果 |
6.3 data 结构
data 对应源码中的 metadata.InstAndAssocDetailData(association.go),由三个数组组成:
| 字段 | 类型 | 描述 |
|---|---|---|
| association | array | 查询到的关联关系详情,按分页排序参数排序 |
| src | array | 源模型实例的详情(仅当 src_detail=true 时返回) |
| dst | array | 目标模型实例的详情(仅当 dst_detail=true 时返回) |
association 数组元素类型为 InstAsst(association.go),字段与响应一一对应:
| 字段 | 类型 | 描述 |
|---|---|---|
| id | int64 | 关联 ID |
| bk_inst_id | int64 | 源模型实例 ID |
| bk_obj_id | string | 关联关系源模型 ID |
| bk_asst_inst_id | int64 | 目标模型实例 ID |
| bk_asst_obj_id | string | 目标模型 ID |
| bk_obj_asst_id | string | 自动生成的模型关联关系 ID(如 bk_switch_connect_host) |
| bk_asst_id | string | 关系名称(如 connect) |
src 数组元素示例字段:
| 字段 | 类型 | 描述 |
|---|---|---|
| bk_inst_name | string | 实例名 |
| bk_inst_id | int | 实例 ID |
dst 数组元素示例字段(目标为主机模型时):
| 字段 | 类型 | 描述 |
|---|---|---|
| bk_host_inner_ip | string | 主机内网 IP |
说明:
src/dst中的字段由src_fields/dst_fields决定;示例中dst请求字段为bk_host_innerip,而响应文档字段表中写作bk_host_inner_ip,实际返回以实例属性字段名为准。src/dst的具体内容按请求裁剪的字段返回,不固定为表格中的两个字段。
7. 源码级实现原理
7.1 处理主流程
SearchInstAssociationAndInstDetail(association.go)的处理链路为:
- 反序列化请求体为
metadata.InstAndAssocRequest; - 执行
request.Validate():校验asst_filter非空、过滤规则合法性(querybuilder.RuleOption{NeedSameSliceElementType: true})、page.limit范围; AsstFilter.ToMgo()将组合过滤规则转换为 MongoDB 查询条件;- 用路径参数
bk_obj_id做模型实例查询权限鉴权(HasFindModelInstAuth); - 携带
asst_filter转换结果、asst_fields、page调用 CoreServiceReadInstAssociation获取关联关系; - 若
src_detail与dst_detail均为 false,直接返回 association 数组(短路,避免无谓的实例查询); - 否则遍历关联关系,按源模型/目标模型分组收集实例 ID(
srcObjInst/dstObjInst),并对所有涉及的模型做一次实例查询鉴权; - 调用
getInstDetail分别按src_fields/dst_fields拉取源、目标实例详情,填入resp.Src/resp.Dst。
7.2 实例详情的获取与鉴权差异
getInstDetail 与 searchInstForAssocDetail(association.go)展示了两个实现细节:
- 主模型(mainline)与普通模型的鉴权不同:普通模型使用
FindMany(模型实例查询)动作;主模型对象(如bk_host)需要校验其所属业务的ViewBusinessResource权限——对主机先通过GetHostModuleRelation取业务 ID,对其他主模型对象则查询bk_biz_id字段; - 实例查询:按
{objID: {bk_$in: insts}}构造条件、DisableCounter: true关闭计数、Fields: fields裁剪字段,通过InstOperation().FindInst获取实例列表。
从代码注释(association.go)还可确认,该接口源于 issue #5807 的"一次返回关联关系+源/目标实例详情"需求,属于对 find_instance_association 的能力增强版本。
7.3 关联关系数据模型
关联关系集合中的每条记录以 InstAsst 表示,关键字段与 JSON 键一一对应(association.go):id(序列 ID)、bk_inst_id(源实例 ID)、bk_obj_id(源模型 ID)、bk_asst_inst_id(目标实例 ID)、bk_asst_obj_id(目标模型 ID)、bk_obj_asst_id(模型关联关系 ID)、bk_asst_id(关联类型 ID)、bk_biz_id(业务 ID)、bk_supplier_account(开发商账号)。GetInstID(objID) 方法可依据模型 ID 从一条关联记录中解析出对应侧的实例 ID。
8. 实践建议与注意事项
- 过滤规则深度:
asst_filter最多嵌套 2 层组合,超深会校验失败;单条OR组合下原子规则条数默认上限 20(DefaultMaxConditionOrRulesCount,见 types.go)。 - 分页作用于关联关系:当关联关系数量多、
limit小时,src/dst只覆盖当前页关联关系涉及到的实例;若需全量实例详情,请适当调大limit或分页遍历。 - 按需开启详情:
src_detail/dst_detail默认关闭;仅在需要实例属性时开启,可显著减少下游查询。 - 字段裁剪:建议始终通过
src_fields/dst_fields/asst_fields指定所需字段,减少网络与计算开销;不填时返回全部字段。 - 权限前提:调用者需具备相关模型的实例查询权限;涉及主模型(如主机)时还要求对实例所属业务拥有相应资源查看权限,否则接口返回无权限。
- 版本与网关:该能力自 v3.10.11 起提供,实际路径为
POST /find/instassociation/object/{bk_obj_id}/inst/detail;通过 API 网关(ESB)调用时按标准蓝鲸应用鉴权参数传入即可。