bk-cmdb 实例关联关系查询进阶指南:find_instassociation_with_inst 接口详解

原创2026-10-14 13:33:411,925 阅读
文章标签:后端企业应用微服务

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)的处理链路为:

  1. 反序列化请求体为 metadata.InstAndAssocRequest;
  2. 执行 request.Validate():校验 asst_filter 非空、过滤规则合法性(querybuilder.RuleOption{NeedSameSliceElementType: true})、page.limit 范围;
  3. AsstFilter.ToMgo() 将组合过滤规则转换为 MongoDB 查询条件;
  4. 用路径参数 bk_obj_id 做模型实例查询权限鉴权(HasFindModelInstAuth);
  5. 携带 asst_filter 转换结果、asst_fields、page 调用 CoreService ReadInstAssociation 获取关联关系;
  6. 若 src_detail 与 dst_detail 均为 false,直接返回 association 数组(短路,避免无谓的实例查询);
  7. 否则遍历关联关系,按源模型/目标模型分组收集实例 ID(srcObjInst/dstObjInst),并对所有涉及的模型做一次实例查询鉴权;
  8. 调用 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. 实践建议与注意事项

  1. 过滤规则深度:asst_filter 最多嵌套 2 层组合,超深会校验失败;单条 OR 组合下原子规则条数默认上限 20(DefaultMaxConditionOrRulesCount,见 types.go)。
  2. 分页作用于关联关系:当关联关系数量多、limit 小时,src/dst 只覆盖当前页关联关系涉及到的实例;若需全量实例详情,请适当调大 limit 或分页遍历。
  3. 按需开启详情:src_detail/dst_detail 默认关闭;仅在需要实例属性时开启,可显著减少下游查询。
  4. 字段裁剪:建议始终通过 src_fields/dst_fields/asst_fields 指定所需字段,减少网络与计算开销;不填时返回全部字段。
  5. 权限前提:调用者需具备相关模型的实例查询权限;涉及主模型(如主机)时还要求对实例所属业务拥有相应资源查看权限,否则接口返回无权限。
  6. 版本与网关:该能力自 v3.10.11 起提供,实际路径为 POST /find/instassociation/object/{bk_obj_id}/inst/detail;通过 API 网关(ESB)调用时按标准蓝鲸应用鉴权参数传入即可。
登录后查看全文
bk-cmdb