后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载count_instance_associations是蓝鲸配置平台bk-cmdb对外开放 API 中用于统计模型实例关联关系数量的接口自 v3.10.1 起提供适用于需要在不拉取明细的情况下快速获取关联规模、进行容量评估或触发阈值判断的场景。阅读本文后你将完整掌握该接口的请求参数、conditions条件组装规则、响应结构以及从 API 网关到 Mongo 底层计数的完整调用链路与校验逻辑。接口概览项目内容接口名称operationIdcount_instance_associationsHTTP 方法与路径POST /api/v3/count/instance_associations/object/{bk_obj_id}功能说明查询模型实例关系数量版本要求v3.10.1 及以上该接口在 API 网关资源配置文件 中登记网关后端直连拓扑服务的/api/v3/count/instance_associations/object/{bk_obj_id}并默认带有bk-rate-limit默认每周期 100 token限流插件isPublic: false表示该资源不对外公开需申请 API 权限后方可调用。从调用链定位看该路径属于拓扑topo系列接口与查询实例关联明细的search_instance_associations互为姊妹接口一个返回info明细列表一个仅返回count数量。请求参数详解接口请求体为 JSON包含三个字段字段名类型必填说明bk_biz_idint否业务 ID查询主线模型时必填bk_obj_idstring是模型 ID对象模型标识conditionsobject否组合查询条件支持 AND / OR可嵌套最多嵌套 3 层每层最多 20 个 OR 条件不传表示匹配全部即conditions为 null注意bk_obj_id同时也会出现在 URL 路径参数{bk_obj_id}中两者含义一致。主链路模型如业务、集群、模块等组织架构主线模型的实例关联统计必须携带bk_biz_id否则无法限定业务范围。conditions 结构conditions由condition与rules两个字段构成字段名类型必填说明conditionstring是规则操作符取值为AND或ORrulesarray是所选业务规则的范围条件集合conditions.rules 字段说明rules数组中的每个元素既可以是原子规则原子过滤规则也可以再次嵌套conditionrules形成组合规则字段名类型必填说明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 格式数组类型 value 的元素个数上限为 500各字段的实际含义与仓库中的字段常量一一对应定义于 definitions.go字段名语义源码常量bk_obj_id源模型 IDBKObjIDFielddefinitions.gobk_inst_id源实例 IDBKInstIDFielddefinitions.gobk_asst_obj_id目标模型 IDBKAsstObjIDFielddefinitions.gobk_asst_inst_id目标实例 IDBKAsstInstIDFielddefinitions.gobk_obj_asst_id模型关联关系 IDAssociationObjAsstIDFielddefinitions.gobk_asst_id关联类型关联种类IDAssociationKindIDFielddefinitions.goid实例关联记录自身的唯一 ID对应关联记录表主键这些字段在实例关联记录表上均建有索引见 src/common/index/association.go因此按上述字段过滤可以命中 Mongo 索引。操作符与 value 格式conditions底层由src/common/querybuilder模块解析模块说明见 src/common/querybuilder/README.md。操作符常量定义在 src/common/querybuilder/types.go 的SupportOperators集合中包括类别操作符value 格式通用比较equal、not_equal基本数据类型数值 / bool / 字符串集合匹配in、not_in元素类型一致的数组数字比较less、less_or_equal、greater、greater_or_equal数值时间比较datetime_less、datetime_less_or_equal、datetime_greater、datetime_greater_or_equalRFC3339 格式字符串字符串begins_with、not_begins_with、contains、not_contains、ends_with、not_ends_with非空字符串数组判空is_empty、is_not_empty不接受参数空值判断is_null、is_not_null不接受参数字段存在性exist、not_exist不接受参数说明接口文档操作符一栏示例中列出的between、not_between在当前仓库的 querybuilder 实现中并未列入SupportOperators集合README 明确注明不支持 between 和 not_between 运算符这类运算符可基于基本比较运算符组合实现。实际可用操作符以 types.go 中SupportOperators为准区间过滤可改用greater_or_equal与less_or_equal组合表达。限制边界源码级校验conditions的合法性由CommonCountFilter.Validate把关src/common/metadata/common.go规则常量定义于 src/common/querybuilder/types.go限制项上限常量嵌套层数3 层MaxDeep 3数组类型 value 元素个数500DefaultMaxSliceElementsCount 500单层 OR 组合规则数20DefaultMaxConditionOrRulesCount 20数组元素类型要求一致RuleOption.NeedSameSliceElementType若conditions为空null或不传校验直接通过语义为匹配全部关联记录见 common.go。请求示例以下示例统计交换机模型bk_switch的实例关联数量要求关联关系为bk_switch_connect_host且满足源实例 ID 属于 [2,4,6]或关联类型 ID 等于 3{ 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 } ] } ] } }外层condition为AND连接关联关系 ID 等于指定值与内层OR组合内层OR连接源实例 ID 属于集合与关联类型等于 3。整体语义等价于bk_obj_asst_id bk_switch_connect_host AND (bk_inst_id IN [2,4,6] OR bk_asst_id 3)查询主线模型如biz、set、module时需在上述 JSON 中补充bk_biz_id: 业务ID字段。响应示例与参数说明{ result: true, code: 0, message: success, permission: null, data: { count: 1 } }响应参数字段名类型说明resultbool请求是否成功true成功false失败codeint错误码0表示成功0表示失败错误码messagestring请求失败时返回的错误信息permissionobject权限信息dataobject请求返回的数据data.count为 int 类型即满足条件的实例关联记录数量。响应外层结构与CommonCountResp定义对应src/common/metadata/common.godata部分实际由metadata.CommonCountResult承载。源码级调用链路剖析从一次 HTTP 请求到最终计数完整调用链如下① API 网关层POST /api/v3/count/instance_associations/object/{bk_obj_id}在 apiserver 中按拓扑系列路径转发该路径被列入topoPrefixes白名单src/apiserver/service/url.go。② 权限解析层apiserver 将请求转发到拓扑服务前权限解析器会匹配正则^/api/v3/count/instance_associations/object/[^\s/]/?$src/ac/parser/topolatest.go命中后标记为SkipAction跳过实例级鉴权topolatest.go。③ 拓扑服务路由注册拓扑服务通过utility.AddHandler注册该 POST 路由到CountInstanceAssociationshandlerservice_business_initfunc.go。④ 拓扑服务 handler 处理从路径取bk_obj_id将请求体反序列化为metadata.CommonCountFilter执行参数校验并将读偏好设为SecondaryPreferredMode从库优先读取降低主库压力src/scene_server/topo_server/service/association.go。⑤ 逻辑层组装条件CountInstanceAssociations逻辑将conditions通过GetConditions()转换为 Mongo 过滤条件并强制注入bk_obj_id字段src/scene_server/topo_server/logics/inst/association.gocond, err : input.GetConditions() cond[common.BKObjIDField] objID conditions : metadata.Condition{Condition: cond}⑥ coreservice 底层计数拓扑服务调用 coreservice 的CountInstanceAssociationssrc/source_controller/coreservice/core/association/instance.go最终落到countInstanceAssociationasstTableName : common.GetObjectInstAsstTableName(objID, kit.SupplierAccount) return mongodb.Client().Table(asstTableName).Find(cond).Count(kit.Ctx)即对实例关联记录表表名由模型 ID 与租户标识动态生成执行 MongoFind(...).Count(...)完成统计instance.go。由于关联记录表对bk_obj_id、bk_inst_id、bk_asst_obj_id、bk_asst_inst_id等字段建有复合索引src/common/index/association.go按这些字段过滤时计数查询效率有保障。⑦ 条件转换细节CommonCountFilter.GetConditions()将 QueryBuilder 的规则树通过ToMgo()转换为 Mongo 查询条件src/common/metadata/common.go原子规则与组合规则的定义可参见 src/common/querybuilder/types.go。常见问题与注意事项查询主线模型必须传bk_biz_id不传时无法限定业务范围结果可能与预期不符。conditions不传等于匹配全部若希望统计某模型下所有关联记录直接省略conditions即可无需构造空对象。数组 value 上限 500in/not_in等操作符的数组元素个数超过 500 会校验失败需拆分多次调用后自行汇总。嵌套与 OR 规则数限制嵌套超过 3 层、单层 OR 超过 20 条会被CommonCountFilter.Validate拒绝报参数错误对应错误码CCErrCommParamsInvalid。between/not_between不可用当前 querybuilder 实现不支持这两个操作符区间场景请组合greater_or_equal与less_or_equal。只返回数量、不返回明细需要关联明细列表时请使用姊妹接口search_instance_associationsPOST /api/v3/search/instance_associations/object/{bk_obj_id}。延伸阅读实例关联查询接口 search_instance_associationsQueryBuilder 查询规则组装详细说明CommonCountFilter 定义与校验实现拓扑服务关联计数实现coreservice 关联计数实现赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云配置平台bk-cmdb批量创建模型实例关联关系接口实战指南蓝鲸智云配置平台bk cmdb批量创建模型实例关联关系接口实战指南 导读 本文以蓝鲸智云配置平台BlueKing CMDBbk cmdb开放 API后端企业应用运维蓝鲸配置平台 bk-cmdb 接口实战list_process_related_info 点分五位查询进程实例关联信息蓝鲸配置平台 bk cmdb 接口实战list_process_related_info 点分五位查询进程实例关联信息 导读 本文以蓝鲸配置平台BlueKi后端企业应用运维蓝鲸配置平台 bk-cmdb点分五位查询进程实例关联信息接口list_process_related_info实战指南蓝鲸配置平台 bk cmdb点分五位查询进程实例关联信息接口list_process_related_info实战指南 导读 /api/v3/findma后端企业应用运维上一篇Illustrator自动化脚本终极指南8个免费工具彻底改变你的设计工作流下一篇OmenSuperHub惠普游戏本硬件控制的技术实现与性能优化解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考