后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读search_instance_associations是蓝鲸智云配置平台bk-cmdb提供的通用模型实例关系实例关联查询接口用于按条件检索任意两个模型实例之间已建立的关联关系记录。它允许调用方以bk_obj_id如bk_switch为入口通过组合查询条件AND/OR 嵌套精准筛选出源实例与目标实例的关联明细是构建拓扑视图、实例关联分析、资产对账等场景的基础能力。读完本文你将掌握该接口的完整请求参数、组合查询规则、分页排序用法、返回数据结构以及其在 topo_server 中的底层实现链路。接口概述接口名称通用模型实例关系查询Search Instance Associations适用版本v3.10.1 及以上所需权限模型实例查询权限源码中通过HasFindModelInstAuth完成鉴权见 service/association.goHTTP 方法 / 路径POST /search/instance_associations/object/{bk_obj_id}该接口的路由注册在 service_business_initfunc.go与count/instance_associations/object/{bk_obj_id}实例关联计数接口相邻二者共用同一套组合条件解析逻辑区别仅在于前者返回明细、后者返回数量。从调用链看该接口由topo_server承接经过 logics/inst/association.go 的业务逻辑层将条件转换为 MongoDB 查询再下发给coreservice的ReadInstAssociation见 apimachinery/coreservice/association/api.go完成最终数据读取。请求参数详解通用参数common_args_desc所有蓝鲸 CMDB API 请求都需携带蓝鲸智云开放平台通用鉴权参数包括bk_app_code、bk_app_secret、bk_username/bk_token等用于标识应用身份与操作用户。接口专属参数字段类型必填说明bk_biz_idint否业务 ID查询主线模型Mainline Model时必须传入bk_obj_idstring是模型 ID对象 ID指定要查询哪一类模型的实例关联例如bk_switch、hostconditionsobject否组合查询条件支持 AND 与 OR 两种逻辑可嵌套最多支持 3 层每个 OR 条件内最多 20 条规则不传表示匹配全部即 conditions 为 nullfieldsarray否指定需要返回的字段不存在的字段会被忽略不指定则返回全部字段返回全部字段会影响性能建议按需返回pageobject是分页设置必填上述结构与源码中的CommonSearchFilter一一对应见 common.goObjectID对应bk_obj_idConditions对应conditions*querybuilder.QueryFilter类型Fields对应fieldsPage对应page。其中还包含一个可选字段TimeConditiontime_condition仅用于时间过滤且与conditions是“与”关系供需要按时间维度筛选用。conditions 组合条件结构conditions由两层结构组成conditions字段类型必填说明conditionstring是规则操作符取值为AND或ORrulesarray是作用于所选业务的筛选条件规则数组conditions.rulesrules数组中的每一条规则可以是原子规则包含field、operator、value或嵌套的组合规则包含condition与rules从而实现多级嵌套字段类型必填说明fieldstring是条件字段可选值id、bk_inst_id、bk_obj_id、bk_asst_inst_id、bk_asst_obj_id、bk_obj_asst_id、bk_asst_idoperatorstring是操作符可选值equal、not_equal、in、not_in、less、less_or_equal、greater、greater_or_equal、between、not_between等value-否条件字段的期望值不同操作符对应不同取值格式数组类型的 value 最多支持 500 个元素字段含义速查对应源码InstAsst结构见 association.goid实例关联记录的自增序列 IDbk_inst_id源模型实例 IDbk_obj_id源模型关联起点的模型 IDbk_asst_inst_id目标模型实例 IDbk_asst_obj_id目标模型关联终点的模型 IDbk_obj_asst_id自动生成的模型关联 ID如bk_switch_connect_hostbk_asst_id关联类型 ID如connect、runpage 分页参数字段类型必填说明startint是记录起始位置从 0 开始limitint是每页返回记录数默认值为 500sortstring否检索排序遵循 MongoDB 语义格式{KEY}:{ORDER}默认按创建时间排序limit上限受BKMaxInstanceLimit约束超过上限会返回分页超限错误CCErrCommPageLimitIsExceeded相关校验见 common.go。组合查询规则querybuilder深度解析conditions的组装规则由 bk-cmdb 内置的查询构建器query builder解析详细设计可参考 src/common/querybuilder/README.md。该模块的作用是把前端/API 传入的类 jQuery-QueryBuilder 结构参数转换为 MongoDB 过滤条件。核心约束如下均可在源码中验证嵌套深度组合条件最大深度为 3即最多嵌套 2 层常量MaxDeep 3定义于 types.go超出会返回exceed max query condition deepth错误OR 条件规则数单个 OR 组合内最多 20 条规则常量DefaultMaxConditionOrRulesCount 20types.go数组值上限数组类型 value 最多 500 个元素常量DefaultMaxSliceElementsCount 500types.go类型一致性数组元素类型需保持一致校验选项NeedSameSliceElementType: true见 common.go。querybuilder 支持的操作符分为以下几类类别操作符说明Value 格式通用equal/not_equal相等 / 不等比较基本数据类型数值、bool、字符串数组in/not_in字段值在 / 不在指定集合中同类型基本数据组成的数组数组is_empty/is_not_empty字段值为空 / 非空数组不接受参数数字less/less_or_equal/greater/greater_or_equal大小比较数值时间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前后缀与包含匹配非空字符串空值is_null/is_not_null字段值为 / 不为null不接受参数字段存在exist/not_exist记录包含 / 不包含该字段不接受参数需要特别说明between/not_between这类区间操作符在 querybuilder 中不直接支持见 README.md 与 jQuery-QueryBuilder 的差异说明官方建议基于基本比较操作符greater_or_equalless_or_equal组合自行实现区间过滤使用前请确认当前版本的操作符可用范围。完整请求示例以下示例查询模型bk_switch交换机与主机host之间建立的bk_switch_connect_host关联并附加条件源实例 ID 属于[2, 4, 6]或关联类型 ID 等于3{ bk_app_code:code, bk_app_secret:secret, bk_username: xxx, bk_token:xxxx, bk_obj_id:bk_switch, conditions:{ condition: AND, rules: [ { field: bk_obj_asst_id, operator: equal, value: bk_switch_connect_host }, { condition: OR, rules: [ { field: bk_inst_id, operator: in, value: [2,4,6] }, { field: bk_asst_id, operator: equal, value: 3 } ] } ] }, fields:[ bk_inst_id, bk_asst_inst_id, bk_asst_obj_id, bk_asst_id, bk_obj_asst_id ], page:{ start:0, limit:500 } }结构解读顶层condition: AND表示以下规则同时成立第一条规则限定关联类型为bk_switch_connect_host第二条是嵌套的OR组合第 2 层表示“源实例 ID 为 2/4/6”或“关联类型 ID 为 3”fields按需指定返回字段减少传输开销page从第 0 条开始每页 500 条。返回结果解析返回结果示例{ result: true, code: 0, message: , permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: { info: [ { bk_inst_id: 2, bk_asst_inst_id: 8, bk_asst_obj_id: host, bk_asst_id: connect, bk_obj_asst_id: bk_switch_connect_host } ] } }response 顶层字段字段类型说明resultbool请求是否成功true 成功false 失败codeint错误码0 表示成功0 表示失败messagestring失败时返回的错误信息permissionobject权限信息request_idstring请求链路 IDrequest chain iddataobject请求返回的数据data.info 每条关联记录的字段字段类型说明bk_inst_idint源模型实例 IDbk_asst_inst_idint目标模型实例 IDbk_asst_obj_idstring关联目标对端模型 IDbk_asst_idstring关联类型 IDbk_obj_asst_idstring自动生成的模型关联 ID注意返回记录还隐含携带bk_obj_id源模型 ID、id记录自增 ID、bk_supplier_account等字段对应 InstAsst 的完整字段集但只有当它们被fields显式要求时才会出现在输出中bk_obj_id恒等于请求路径中的模型 ID。此外服务端将查询结果以data.info数组形式封装见 service/association.go与通用响应结构保持一致。源码实现剖析1. 路由与入口接口注册于 service_business_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /search/instance_associations/object/{bk_obj_id}, Handler: s.SearchInstanceAssociations})处理函数 SearchInstanceAssociations 的执行流程从路径参数取出bk_obj_id将请求体解码为CommonSearchFilter并回填ObjectID调用input.Validate()做参数校验模型 ID 非空、分页 limit 上限、组合条件深度与规则数设置读偏好为SecondaryPreferredMode优先从 MongoDB 从节点读取降低主节点压力允许轻微数据延迟通过HasFindModelInstAuth校验“模型实例查询”权限调用业务逻辑层SearchInstanceAssociations执行查询。2. 条件转换与数据读取业务逻辑层 SearchInstanceAssociations 完成关键转换通过input.GetConditions()将querybuilder.QueryFilter组合条件转换为 MongoDB 过滤条件Conditions.ToMgo()见 common.go组装InstAsstQueryCondition含bk_obj_id、fields、condition、page并关闭 count 计数DisableCounter: true以提升性能最终调用CoreService().Association().ReadInstAssociation下发至 coreservice 读取实例关联集合inst_asst数据表。3. 数据结构落点每条实例关联记录对应结构体 InstAsst核心字段的 bson/json 标签与接口返回字段完全对应bk_inst_id源实例、bk_obj_id源模型、bk_asst_inst_id目标实例、bk_asst_obj_id目标模型、bk_obj_asst_id模型关联 ID、bk_asst_id关联类型、bk_supplier_account开发商账号、bk_biz_id业务 ID。实战注意事项与最佳实践主线模型查询必须带bk_biz_id当bk_obj_id指向主线模型如业务、集群、模块、主机等拓扑主线上的模型时务必在请求中携带bk_biz_id否则查询范围不准确。fields按需返回不指定fields会返回全部字段实例关联量大时严重影响性能与网络开销生产环境建议始终显式声明所需字段。控制分页与深度limit默认 500 且受上限约束组合条件最多 3 层、单个 OR 最多 20 条规则、数组 value 最多 500 个元素超限请求会被校验逻辑直接拒绝组装条件时应提前评估复杂度。区间查询用组合操作符between/not_between在 querybuilder 中不受支持区间过滤请用greater_or_equal与less_or_equal组合表达。权限前置调用方需要具备对应模型的“实例查询”权限鉴权失败将返回无权限响应permission字段会携带权限申请信息。关联查询的补充接口若需要同时获取源/目标实例详情与关联记录可参考同族接口find/instassociation/object/{bk_obj_id}/inst/detailSearchInstAssociationAndInstDetail与find/instassociation/relatedSearchAssociationRelatedInst它们分别用于返回带实例明细的关联信息与指定实例的全部关联含作为源与目标两侧的记录。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 通用模型实例关系查询 API 实战指南search_instance_associations 全解析蓝鲸 CMDB 通用模型实例关系查询 API 实战指南search_instance_associations 全解析 本文围绕蓝鲸智云配置平台BlueKi后端企业应用运维蓝鲸智云 CMDB 实例关联关系查询接口find_instance_association实战指南蓝鲸智云 CMDB 实例关联关系查询接口find_instance_association实战指南 导读 find_instance_association后端企业应用运维蓝鲸 CMDB 通用对象实例增删改查与拓扑查询 API 实战指南蓝鲸 CMDB 通用对象实例增删改查与拓扑查询 API 实战指南 本文基于蓝鲸智云配置平台BlueKing CMDB归档接口文档 object_common后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考