bk-cmdb 实例关联关系查询 API 详解:find_instassociation_with_inst 的过滤、分页与详情联查

原创2026-10-12 20:12:211,901 阅读
文章标签:后端企业应用微服务

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"
    }
}

要点拆解:

  1. asst_filter 使用 AND 组合三条规则,限定源模型为 bk_switch、源实例 ID 为 1、目标模型为 host,等价于"查询某台交换机连接的所有主机"。
  2. src_fields 只返回源实例的 bk_inst_id、bk_inst_name;dst_fields 只返回目标实例的 bk_host_innerip。
  3. src_detail、dst_detail 均为 true,启用两端实例详情。
  4. 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() 依次检查:

  1. condition.asst_filter 不能为空,否则返回参数非法错误;
  2. asst_filter 需通过 Query Builder 的规则校验(NeedSameSliceElementType: true 要求同层数组元素类型一致);
  3. page.limit 不能超过 200,否则返回 CCErrCommPageLimitIsExceeded;
  4. 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 项目中以类型安全的方式调用该接口。

登录后查看全文
bk-cmdb