bk-cmdb 实例关联关系查询 API 详解:find_instassociation_with_inst 的过滤、分页与详情联查
bk-cmdb 实例关联关系查询 API 详解:find_instassociation_with_inst 的过滤、分页与详情联查
导读
find_instassociation_with_inst 是蓝鲸智云配置平台(bk-cmdb)开放 API 中用于查询模型实例关联关系的接口,它在基础关联关系查询能力之上,额外支持一次性返回源模型实例与目标模型实例的详情数据,减少"查关联、再查实例"的多次往返调用。本文以 官方 API 文档 为主体骨架,结合仓库内 toposerver 的路由注册、apimachinery 的 SDK 封装、coreservice 的底层实现与集成测试用例,完整讲解该接口的请求参数、asst_filter 过滤规则、分页约束、响应结构与源码调用链。读完本文,你将能够独立构造并调用该接口,理解 src_fields / dst_fields / src_detail / dst_detail 的组合用法,并掌握其背后的 Query Builder 过滤机制与参数校验规则。
一、接口能力与适用范围
该接口用于查询指定模型(bk_obj_id)的实例关联关系,核心特性如下:
| 特性 | 说明 |
|---|---|
| 版本要求 | v3.10.11+ |
| 权限要求 | 模型实例查询权限 |
| 请求方式 | POST |
| 核心能力 | 查询实例关联关系,并可选返回源/目标模型实例详情 |
从仓库源码可以确认,该接口对应的服务端路由注册在 service_business_initfunc.go:
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/find/instassociation/object/{bk_obj_id}/inst/detail",
Handler: s.SearchInstAssociationAndInstDetail})
即实际 HTTP 路径为 /find/instassociation/object/{bk_obj_id}/inst/detail,其中 bk_obj_id 作为路径参数传入。apimachinery 中的 SDK 封装位于 association.go:
func (asst *Association) SearchInstAssocAndInstDetail(ctx context.Context, header http.Header, objID string,
input *metadata.InstAndAssocRequest) (*metadata.InstAndAssocDetailResult, error) {
resp := new(metadata.InstAndAssocDetailResult)
subPath := "/find/instassociation/object/%s/inst/detail"
err := asst.client.Post().WithContext(ctx).Body(input).
SubResourcef(subPath, objID).WithHeaders(header).Do().Into(resp)
...
}
与仅返回关联关系本身的 /find/instassociation/object/{bk_obj_id}(SearchInstByAssociation)不同,本接口在路径末段多了 inst/detail,对应"关联 + 实例详情"的联合查询语义。
二、请求参数总览
请求体为 JSON,包含三个顶层字段:
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| bk_obj_id | string | 是 | 模型唯一标识 |
| condition | map | 是 | 查询参数(关联过滤、字段裁剪、详情开关) |
| page | map | 是 | 分页条件(作用于关联关系记录) |
2.1 condition 查询条件
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| asst_filter | map | 是 | 关联关系过滤条件 |
| asst_fields | array | 否 | 关联关系记录需要返回的字段,不填则返回全部 |
| src_fields | array | 否 | 源模型实例需要返回的属性,不填则返回全部 |
| dst_fields | array | 否 | 目标模型实例需要返回的属性,不填则返回全部 |
| src_detail | bool | 否 | 是否返回源模型实例详情,默认 false |
| dst_detail | bool | 否 | 是否返回目标模型实例详情,默认 false |
关键语义说明:
src_detail/dst_detail是"详情开关":只有将其置为true,响应中才会出现src/dst数组;两个都为false时,接口只返回关联关系本身。这一点在服务端实现中有直接体现——association.go 中:
resp := metadata.InstAndAssocDetailData{Asst: assocRsp.Info}
if !request.Condition.SrcDetail && !request.Condition.DstDetail {
ctx.RespEntity(resp)
return
}
src_fields/dst_fields与详情开关配合使用:开启对应详情后,用于裁剪源/目标实例返回的属性字段,属于"投影"优化手段,可有效控制响应体大小。asst_fields裁剪关联关系记录字段,对应InstAsst结构体中的各属性。
2.2 asst_filter 关联过滤规则
asst_filter 是一组针对关联关系属性字段的过滤规则组合,用于按关联关系属性检索关联关系:
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| condition | string | 是 | 查询条件组合方式,AND 或 OR |
| rules | array | 是 | 包含所有查询条件的集合 |
rules 单条规则(四元组 field / operator / value):
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| field | string | 是 | 查询条件字段,如 bk_obj_id、bk_asst_obj_id、bk_inst_id |
| operator | string | 是 | 查询方式,如 equal、in、nin 等 |
| value | string | 是 | 查询条件对应的值 |
组合约束:asst_filter 支持 AND / OR 两种组合方式,规则可嵌套,最大嵌套深度为 2。例如规则可以是 {condition: "AND", rules: [rule1, {condition: "OR", rules: [rule2, rule3]}]} 这类两层结构。
2.3 page 分页条件
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| start | int | 否 | 记录起始位置 |
| limit | int | 是 | 每页记录数,最大 200 |
| sort | string | 否 | 排序字段 |
需要特别强调:分页对象针对的是关联关系记录本身(即 data.association 数组),而非源/目标实例详情。排序字段直接作用于关联关系记录,例如示例中的 "-bk_asst_inst_id" 表示按目标实例 ID 降序排列。
2.4 操作符全集(Query Builder)
asst_filter.rules<a href="https://link.gitcode.com/i/40d94fdf72d05c376fd6c67bb26b8315" target="_blank">].operator 支持的取值来自 bk-cmdb 的查询参数解析模块 Query Builder([README),其操作符常量定义于 types.go:
| 分类 | 操作符 | 含义与 Value 格式 |
|---|---|---|
| 通用比较 | equal | 相等比较,Value 为基本数据类型(数值/bool/字符串) |
| 通用比较 | not_equal | 不等比较,Value 为基本数据类型 |
| 数组 | in | 字段值在指定集合中,Value 为同类型数组 |
| 数组 | not_in | 字段值不在指定集合中,Value 为同类型数组 |
| 数组 | is_empty | 字段值为空数组,不接受参数 |
| 数组 | is_not_empty | 字段值为非空数组,不接受参数 |
| 数值 | less / less_or_equal / greater / greater_or_equal | 大小比较,Value 为数值 |
| 时间 | datetime_less / datetime_less_or_equal / datetime_greater / datetime_greater_or_equal | 时间比较,仅支持 RFC3339 格式字符串 |
| 字符串 | begins_with / not_begins_with / contains / not_contains / ends_with / not_ends_with | 字符串匹配,Value 为非空字符串 |
| 空值 | is_null / is_not_null | 字段是否为 null,不接受参数 |
| 存在性 | exist / not_exist | 字段是否存在,不接受参数 |
原文档中的 Query Builder 说明指向外部 GitHub 链接,仓库内对应的本地说明文档为 bk-cmdb Query Builder 使用说明,其中也明确了两点设计差异:Query Builder 不支持 type 字段(所有 value 统一按基本类型解析),也不支持 between / not_between 运算符(可基于比较运算符组合实现)。
三、请求示例
以下为官方文档给出的完整请求示例,查询 bk_switch 模型中实例 ID 为 1 的实例,与 host(主机)模型实例之间、关联类型为 connect(连接)的全部关联关系,同时返回源实例(交换机)与目标实例(主机)的详情:
{
"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使用 AND 组合三条规则,限定源模型为bk_switch、源实例 ID 为 1、目标模型为host,等价于"查询某台交换机连接的所有主机"。src_fields只返回源实例的bk_inst_id、bk_inst_name;dst_fields只返回目标实例的bk_host_innerip。src_detail、dst_detail均为true,启用两端实例详情。page从第 0 条开始取 20 条,按bk_asst_inst_id(目标实例 ID)降序。
集成测试 asst_test.go 中给出了 Go SDK 侧的等价构造方式,同样使用 asst_filter + src_detail: true + page.limit: 200,可对照理解:
input := &metadata.InstAndAssocRequest{}
input.Condition.AsstFilter = &querybuilder.QueryFilter{Rule: querybuilder.CombinedRule{
Condition: querybuilder.ConditionAnd,
Rules: []querybuilder.Rule{
&querybuilder.AtomRule{Field: common.BKObjIDField, Operator: querybuilder.OperatorEqual, Value: "bk_router"},
&querybuilder.AtomRule{Field: common.BKInstIDField, Operator: querybuilder.OperatorEqual, Value: routerInstId1},
},
}}
input.Condition.SrcDetail = true
input.Page.Limit = 200
rsp, err := asstClient.SearchInstAssocAndInstDetail(context.Background(), header, "bk_router", input)
四、响应结构与字段说明
4.1 响应示例
{
"result": true,
"code": 0,
"message": "success",
"permission": null,
"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"
}
]
}
}
4.2 响应参数
| 名称 | 类型 | 说明 |
|---|---|---|
| result | bool | 请求是否成功,true 成功,false 失败 |
| code | int | 错误码,0 表示成功,>0 表示失败错误码 |
| message | string | 失败时返回的错误信息 |
| permission | object | 权限信息 |
| data | object | 请求返回的数据 |
data
| 名称 | 类型 | 说明 |
|---|---|---|
| association | array | 查询到的关联关系详情,按分页排序参数排序 |
| src | array | 源模型实例详情 |
| dst | array | 目标模型实例详情 |
association(关联关系记录字段)
| 名称 | 类型 | 说明 |
|---|---|---|
| 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_asst_id | string | 关系名称 |
src(源实例详情)
| 名称 | 类型 | 说明 |
|---|---|---|
| bk_inst_name | string | 实例名称 |
| bk_inst_id | int | 实例 ID |
dst(目标实例详情)
| 名称 | 类型 | 说明 |
|---|---|---|
| bk_host_inner_ip | string | 主机内网 IP |
上述 association 字段与 InstAsst 结构体的定义一一对应(见 association.go),例如 id 对应自增序列 ID、bk_obj_asst_id 对应 ObjectAsstID(如 bk_switch_connect_host,由源模型 ID + 关系名 + 目标模型 ID 拼接)、bk_asst_id 对应 AssociationKindID(如 connect)。响应中的 data.association / src / dst 三块结构则对应 InstAndAssocDetailData:
type InstAndAssocDetailData struct {
Asst []InstAsst `field:"association" json:"association"`
Src []mapstr.MapStr `field:"src" json:"src"`
Dst []mapstr.MapStr `field:"dst" json:"dst"`
}
需要提醒的是,文档的请求示例中 dst_fields 传入的是 bk_host_innerip,而响应参数表写作 bk_host_inner_ip,两者在文档内并不完全一致;实际使用时以你所在版本的模型属性实际字段名为准。
五、源码级原理:请求如何被处理
该接口的完整调用链为:
开放 API 网关 → toposerver 路由 /find/instassociation/object/{bk_obj_id}/inst/detail
→ SearchInstAssociationAndInstDetail(参数校验 + 鉴权 + 关联查询)
→ coreservice ReadInstAssociation(底层 Mongo 查询)
→ getInstDetail(按需拉取源/目标实例详情)
服务端核心处理逻辑位于 association.go,可归纳为四个阶段:
阶段一:参数校验。 request.Validate() 依次检查:
condition.asst_filter不能为空,否则返回参数非法错误;asst_filter需通过 Query Builder 的规则校验(NeedSameSliceElementType: true要求同层数组元素类型一致);page.limit不能超过 200,否则返回CCErrCommPageLimitIsExceeded;page.limit不能为 0,否则返回CCErrCommParamsNeedSet。
该校验逻辑定义在 association.go 的 InstAndAssocRequest.Validate() 中,与文档声明的"limit 最大 200、必填"完全一致。
阶段二:过滤条件转 Mongo 查询。 request.Condition.AsstFilter.ToMgo() 将 Query Builder 规则转换为 MongoDB 查询条件,这一步决定了过滤的最终形态——嵌套组合规则在这里被递归解析成 MongoDB 的 $and / $or 表达式。
阶段三:鉴权与关联查询。 先通过 HasFindModelInstAuth 校验当前用户对源模型 bk_obj_id 的实例查询权限;随后调用 CoreAPI.CoreService().Association().ReadInstAssociation 读取关联关系,并设置 SecondaryPreferred 读偏好以减轻主库压力;分页参数 start / limit / sort 在这里直接作用于关联关系记录。
阶段四:详情联查。 若 src_detail 或 dst_detail 为 true,则按源/目标实例 ID 分组聚合(map[string][]int64),对涉及的所有模型再次进行实例查询权限校验,最后调用 searchInstForAssocDetail 按 src_fields / dst_fields 裁剪字段后返回 src 与 dst 数组。
六、边界约束与常见错误
结合源码校验与测试用例,调用本接口时需注意以下约束:
| 约束 | 说明 | 源码/测试依据 |
|---|---|---|
| limit 必填且 ≤ 200 | 缺省或超出均报错 | Validate |
| asst_filter 必填 | 缺失直接返回参数非法 | Validate |
| 过滤规则可嵌套,最大深度 2 | 由 Query Builder 规则深度校验保证 | querybuilder/README.md |
| 同层 rules 数组元素类型需一致 | NeedSameSliceElementType: true |
Validate |
| limit 传 201 时接口报错 | 集成测试明确断言该场景 | asst_test.go |
集成测试 asst_test.go 中还验证了正常场景(limit: 200 时返回 2 条关联、1 条源实例详情)与越界场景(limit: 201 时 err != nil),可作为接口行为的事实依据。
七、总结
find_instassociation_with_inst 是 bk-cmdb 中"关联查询 + 实例详情"二合一的实用接口:通过 asst_filter(Query Builder 过滤规则,支持 AND/OR 两层嵌套)精准定位关联关系,通过 src_detail / dst_detail 与 src_fields / dst_fields 组合控制详情的开启与字段裁剪,通过 page 对关联记录进行分页与排序。其请求模型、校验逻辑与响应结构在仓库中均有完整的源码与测试支撑,开发者可以直接参照本文示例构造请求,也可以基于 apimachinery 的 SDK 封装 在 Go 项目中以类型安全的方式调用该接口。