后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读本篇文章围绕蓝鲸智云配置平台bk-cmdb的查询某实例所有关联关系接口/api/v3/find/instassociation/related展开从接口参数、请求/返回报文示例到源码实现原理逐步拆解。读完本文你将掌握如何通过bk_inst_id与bk_obj_id一次查询某实例作为关联关系源模型与目标模型的全量关联数据并理解其底层基于 MongoDB OR 条件、权限鉴权与分页限制的完整调用链路可直接用于二次开发与日常 API 调试。一、功能概述与典型应用场景在 bk-cmdb 中模型如交换机bk_switch、路由器bk_router之间存在关联关系Association而实例之间则通过实例关联Instance Association建立具体的关联记录。该接口解决的问题是给定一个模型实例返回它参与的全部关联记录——既包括它作为源模型实例bk_inst_id发起的关联也包括它作为目标模型实例bk_asst_inst_id被关联的情况。典型应用场景包括拓扑图展示给定某台交换机实例反查它连接了哪些路由器、上联了哪些汇聚设备变更影响分析删除或变更实例前先查询其关联关系评估连锁影响数据对账批量核对模型实例的关联是否完整、是否符合预期。调用该接口需要具备模型实例查询权限HasFindModelInstAuth无权限时会返回鉴权失败响应。二、接口基本信息项目说明请求方式POST路由路径/api/v3/find/instassociation/related权限要求模型实例查询权限功能查询某实例所有的关联关系包含其作为关联关系原模型和关联关系目标模型的情况该路由在 src/scene_server/topo_server/service/service_business_initfunc.go 中注册对应的处理函数为SearchAssociationRelatedInst位于 src/scene_server/topo_server/service/association.go归属于 topo_server 的实例关联instassociation相关接口族与find/instassociation、create/instassociation、delete/instassociation等接口并列。三、请求参数详解3.1 通用鉴权参数接口调用首先需要携带蓝鲸应用与用户鉴权信息common_args字段类型描述bk_app_codestring应用 IDESB 应用编码bk_app_secretstring应用密钥bk_usernamestring操作用户名bk_tokenstring用户登录态 Token可与bk_username二选一3.2 接口业务参数字段类型必选描述bk_inst_idint是实例 IDbk_obj_idstring是模型 ID如bk_router、bk_switchfieldsarray是需要返回的字段startint否记录开始位置limitint否分页大小最大值 500注意接口业务参数位于请求体condition对象内见下方示例fields与page为平级参数。page 分页对象字段类型必选描述startint是记录开始位置偏移量limitint是每页限制条数最大 200源码印证请求结构体定义于 src/common/metadata/association.gotype SearchAssociationRelatedInstRequest struct { Fields []string json:fields Page BasePage json:page Condition SearchAssociationRelatedInstRequestCond json:condition } type SearchAssociationRelatedInstRequestCond struct { ObjectID string field:bk_obj_id json:bk_obj_id,omitempty bson:bk_obj_id,omitempty InstID int64 field:bk_inst_id json:bk_inst_id,omitempty bson:bk_inst_id,omitempty }其中Condition对应bk_obj_id与bk_inst_idPage对应start/limit分页Fields对应需要返回的字段列表。四、请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, condition: { bk_inst_id: 16, bk_obj_id: bk_router }, fields: [ id, bk_inst_id, bk_obj_id, bk_asst_inst_id, bk_asst_obj_id, bk_obj_asst_id, bk_asst_id ], page: { start:0, limit:2 } }上述示例的含义查询模型bk_router路由器下实例 ID 为16的全部关联记录无论该实例是关联的发起方源模型实例还是接收方目标模型实例只返回指定的 7 个字段分页从第 0 条开始、每页 2 条。五、返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: [ { id: 4, bk_inst_id: 1, bk_obj_id: bk_switch, bk_asst_inst_id: 16, bk_asst_obj_id: bk_router, bk_obj_asst_id: bk_switch_default_bk_router, bk_asst_id: default }, { id: 6, bk_inst_id: 2, bk_obj_id: bk_switch, bk_asst_inst_id: 16, bk_asst_obj_id: bk_router, bk_obj_asst_id: bk_switch_default_bk_router, bk_asst_id: default } ] }从返回可以看出虽然查询条件是实例 16bk_router但命中的记录中实例 16 全部出现在bk_asst_inst_id目标实例 ID位置而源侧分别是bk_switch下的实例 1 和实例 2——这正是目标模型实例被关联的场景印证了接口的双向查询能力。六、返回结果参数说明6.1 response 通用封装字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息无权限时为 null 或具体鉴权结果request_idstring请求链 ID用于全链路日志追踪dataobject请求返回的数据6.2 data 数据项说明字段类型描述idint64关联 ID实例关联记录的自增序列号bk_inst_idint64源模型实例 IDbk_obj_idstring关联关系源模型 IDbk_asst_inst_idint64关联关系目标模型实例 IDbk_asst_obj_idstring目标模型 IDbk_obj_asst_idstring自动生成的模型关联关系 ID如bk_switch_default_bk_routerbk_asst_idstring关系名称关联类型 ID如default上述字段与源码中实例关联数据结构InstAsst完全对应其定义位于 src/common/metadata/association.gotype InstAsst struct { ID int64 field:id json:id,omitempty InstID int64 field:bk_inst_id json:bk_inst_id,omitempty bson:bk_inst_id ObjectID string field:bk_obj_id json:bk_obj_id,omitempty bson:bk_obj_id AsstInstID int64 field:bk_asst_inst_id json:bk_asst_inst_id,omitempty bson:bk_asst_inst_id AsstObjectID string field:bk_asst_obj_id json:bk_asst_obj_id,omitempty bson:bk_asst_obj_id OwnerID string field:bk_supplier_account json:bk_supplier_account,omitempty bson:bk_supplier_account ObjectAsstID string field:bk_obj_asst_id json:bk_obj_asst_id,omitempty bson:bk_obj_asst_id AssociationKindID string field:bk_asst_id json:bk_asst_id,omitempty bson:bk_asst_id BizID int64 field:bk_biz_id json:bk_biz_id,omitempty bson:bk_biz_id }可见存储层还包含bk_supplier_account开发商账号与bk_biz_id业务 ID两个字段若需要可在fields中补充返回。七、源码级原理剖析7.1 双向查询的核心OR 条件构造该接口既能查源又能查目标的关键在于查询条件中使用了 MongoDB 的$or即代码中的common.BKDBOR。在 src/scene_server/topo_server/service/association.go 中SearchAssociationRelatedInst构造了如下条件queryCond : metadata.InstAsstQueryCondition{ ObjID: request.Condition.ObjectID, Cond: metadata.QueryCondition{ Fields: request.Fields, Page: request.Page, Condition: mapstr.MapStr{ common.BKDBOR: []mapstr.MapStr{ { common.BKObjIDField: request.Condition.ObjectID, common.BKInstIDField: request.Condition.InstID, }, { common.BKAsstObjIDField: request.Condition.ObjectID, common.BKAsstInstIDField: request.Condition.InstID, }, }, }, }, }翻译成 Mongo 查询语义即为$or: [ { bk_obj_id: 模型ID, bk_inst_id: 实例ID }, // 作为源模型实例 { bk_asst_obj_id: 模型ID, bk_asst_inst_id: 实例ID } // 作为目标模型实例 ]InstAsstQueryCondition结构体定义于 src/common/metadata/association.go包含Cond查询条件 分页 字段投影与ObjID模型 ID两部分。7.2 参数强校验缺一不可接口处理函数在正式查询前执行了多层校验src/scene_server/topo_server/service/association.go条件完整性bk_inst_id 0或bk_obj_id为空时返回CCErrCommParamsNeedSet错误提示必须同时提供bk_inst_id bk_obj_id字段必填fields为空数组时直接返回错误避免无字段查询分页上限page.limit超过common.BKMaxInstanceLimit时返回CCErrCommPageLimitIsExceeded分页限制超出。7.3 分页与排序约定代码中强制将排序字段设置为idrequest.Page.Sort common.BKFieldID即返回结果按关联记录 ID 升序排列保证分页查询的数据顺序稳定不会出现翻页时记录重复或遗漏。关于 limit 上限接口文档记载的最大值 500与源码中的常量定义一致common.BKMaxInstanceLimit 500见 src/common/definitions.go。文档中 page.limit 标注的最大 200为接口文档的历史描述当前仓库源码中以 500 为硬性校验上限实际调用时建议以服务端校验结果为准。7.4 权限鉴权查询前调用s.AuthManager.HasFindModelInstAuth(ctx.Kit, []string{request.Condition.ObjectID})校验用户对目标模型实例的查询权限src/scene_server/topo_server/service/association.go。鉴权失败时返回 403 无权限响应这对应文档中权限模型实例查询权限的说明。7.5 底层调用链SearchAssociationRelatedInst并不直接访问数据库而是通过 apimachinery 客户端调用 coreservice 的Association().ReadInstAssociationsrc/scene_server/topo_server/service/association.go该 RPC 方法定义于 src/apimachinery/coreservice/association/association.go 与 src/apimachinery/coreservice/association/api.go最终由 coreservice 模块完成 MongoDB 实例关联表的查询与投影结果以[]*InstAsst形式封装进data返回。完整调用链路可概括为HTTP POST /find/instassociation/related → topo_server Service.SearchAssociationRelatedInst → 参数校验 / 权限鉴权 / 分页排序预处理 → CoreService.Association().ReadInstAssociation (apimachinery 客户端) → coreservice 实例关联查询逻辑 → MongoDB 查询$or 双向条件 fields 投影 分页八、实战注意事项fields是必填项漏传或传空数组会被直接拒绝建议至少包含id、bk_inst_id、bk_asst_inst_id、bk_obj_id、bk_asst_obj_id以便定位关联双方分页要传全page对象中start与limit均必填limit受服务端 500 上限约束超出会返回CCErrCommPageLimitIsExceeded结果方向需自行区分接口返回的data数组混合了该实例作为源与该实例作为目标两类记录可通过比较bk_inst_id/bk_asst_inst_id与查询的bk_inst_id是否相等来判断记录方向权限前置调用方应用需要对查询的模型具备实例查询权限否则即使参数正确也会被鉴权拦截排查问题用request_id返回报文中的request_id是请求链 ID结合日志可按rid维度全链路排查查询失败原因。九、关联资源延伸阅读接口实现 src/scene_server/topo_server/service/association.go路由注册 src/scene_server/topo_server/service/service_business_initfunc.go请求/响应数据结构 src/common/metadata/association.go、InstAsst 定义分页上限常量 src/common/definitions.gocoreservice 查询入口 src/apimachinery/coreservice/association/api.go同族接口参考创建/批量创建/删除实例关联可对比阅读 docs/apidoc/cc/zh_hans/add_instance_association.md、docs/apidoc/cc/zh_hans/batch_create_instance_association.md、docs/apidoc/cc/zh_hans/batch_delete_inst.md赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 实例关联关系全量查询search_related_inst_asso 接口深度解析蓝鲸配置平台 bk cmdb 实例关联关系全量查询search_related_inst_asso 接口深度解析 文章导读 本文围绕蓝鲸配置平台BlueKi后端企业应用运维bk-cmdb 根据关联关系实例查询模型实例search_inst 接口完整实战指南bk cmdb 根据关联关系实例查询模型实例search_inst 接口完整实战指南 本文围绕蓝鲸智云配置平台bk cmdb根据关联关系实例查询模型实例后端企业应用运维蓝鲸配置平台 bk-cmdb 模型实例关联关系数量查询接口全解析蓝鲸配置平台 bk cmdb 模型实例关联关系数量查询接口全解析 count_instance_associations 是蓝鲸配置平台bk cmdb对外开后端企业应用运维上一篇DBeaver 驱动包教程30 余种数据库 JDBC 驱动离线配置指南下一篇Simple Live 完整教程如何把四大直播平台装进一个跨平台应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考