后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本指南围绕蓝鲸智云配置平台BlueKing CMDB开放 APIsearch_inst_asst_object_inst_base_info查询实例关联模型实例基本信息展开从请求参数、调用示例、响应结构到后端源码调用链逐步拆解帮助你在业务、集群、模块、主机、进程及通用模型之间快速反查关联实例的基础信息bk_inst_id/bk_inst_name并理解is_target_object方向判定与不同模型的 ID/名称字段映射规则。接口概览用途与调用入口该接口用于查询与指定实例存在关联关系的其他模型实例的基本信息。例如已知某台交换机的实例 ID想知道它关联了哪些主机或已知某业务下的集群想反查该集群被哪些上层模型实例引用。接口返回的不是完整关联关系明细而是关联实例的精简基础数据实例 ID 实例名适合列表展示、拓扑反查、批量下钻等场景。在仓库中该接口存在两条对外路径ESB蓝鲸 ESB 组件路径/v2/cc/search_inst_asst_object_inst_base_info/定义于 docs/apidoc/cc/cc.yaml请求方式POSTapi_type为queryAPI 网关APIGW路径/api/v3/findmany/inst/association/association_object/inst_base_info定义于 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml对应的operationId即为search_inst_asst_object_inst_base_info并声明了bk-rate-limit限流插件默认每秒 100 个令牌。两条路径最终都汇聚到拓扑服务topo_server的同一个后端处理函数。中文版接口文档见 docs/apidoc/apigw/open/zh/search_inst_asst_object_inst_base_info.md英文版为 docs/apidoc/apigw/open/en/search_inst_asst_object_inst_base_info.md。请求参数详解顶层参数参数名称类型必选描述fieldsarray否指定查询字段可传实例的任意属性不填则返回所有字段conditionobject是查询条件pageobject否分页条件说明虽然fields允许指定任意属性但该接口的核心定位是返回关联实例的基本信息实际后端组装结果时以实例 ID 字段与实例名/展示名字段为准详见下文「模型字段映射」一节fields的扩展属性筛选能力有限日常调用建议不传或保持默认。condition 对象参数名称类型必选描述bk_obj_idstring是已知实例所属的模型 ID即“站在谁的角度”发起查询bk_inst_idint是已知实例的实例 IDassociation_obj_idstring是目标关联对象的模型 ID返回该模型下与bk_inst_id实例有关联关系的所有实例的基本数据bk_inst_id、bk_inst_nameis_target_objectbool否bk_obj_id是否为目标模型。默认false表示bk_obj_id在关联关系中作为源模型置为true则表示其作为目标模型page 对象参数名称类型必选描述startint否记录开始位置默认值 0limitint否每页条数默认值 20最大 200参数合法性校验源码视角从源码看三个必填参数缺一不可且服务端做了显式校验。在 src/scene_server/topo_server/service/inst.go 的SearchInstAssociationWithOtherObject处理函数中bk_obj_id为空 → 报CCErrCommParamsNeedSet需设置bk_obj_idbk_inst_id为 0 → 报CCErrCommParamsNeedSet需设置bk_inst_idassociation_obj_id为空 → 报CCErrCommParamsNeedSet需设置association_obj_id。分页参数则通过metadata.QueryCondition.IsIllegal()校验若start 0或limit超过common.BKMaxPageSize且不等于BKNoLimit、或limit 0均视为非法并返回CCErrCommPageLimitIsExceeded。这与文档中「limit 默认 20、最大 200」的限制相对应具体分页校验逻辑可参考 src/common/metadata/page.go。调用示例JSON{ condition: { bk_obj_id: bk_switch, bk_inst_id: 12, association_obj_id: host, is_target_object: true }, page: { start: 0, limit: 10 } }示例语义拆解查询模型bk_switch交换机下实例 ID 为12的交换机所关联的主机host模型实例。由于is_target_object为true表示交换机在此关联关系中作为目标模型即查询“哪些主机指向了这台交换机”若置为false则表示交换机作为源模型即查询“这台交换机指向了哪些主机”。响应示例{ result: true, code: 0, message: success, permission: null, data: { count: 4, info: [ { bk_inst_id: 1, bk_inst_name: 127.0.0.3 } ] } }示例中count为 4 表示共匹配到 4 条关联记录接口会以分页方式返回info列表info中每条记录包含关联实例的 ID 与名称。bk_inst_name的具体取值取决于association_obj_id对应的模型主机在此处展示为内网 IP127.0.0.3详见下方字段映射表。响应参数说明参数名称类型描述resultbool请求是否成功。true成功false失败codeint错误码。0 表示 success0 表示失败错误messagestring请求失败时返回的错误信息permissionobject权限信息dataobject请求返回的数据data 对象参数名称类型描述countint记录条数infoobject array与指定实例关联的模型实例基本数据bk_inst_id、bk_inst_namepageobject分页信息data.info 字段说明参数名称类型描述bk_inst_idint实例 IDbk_inst_namestring实例名不同模型下的 bk_inst_id / bk_inst_name 字段映射接口返回值中统一使用bk_inst_id与bk_inst_name作为输出字段名但不同内置模型在存储层对应的真实字段并不相同。文档给出了官方映射关系模型bk_inst_idbk_inst_name业务Businessbk_biz_idbk_biz_name集群Cluster/Setbk_set_idbk_set_name模块Modulebk_module_idbk_module_name进程Processbk_process_idbk_process_name主机Hostbk_host_idbk_host_inner_ip通用模型Common Modelbk_inst_idbk_inst_name这一映射在源码中有完整实现见 src/common/metadata/object.go 中的两个函数GetInstIDFieldByObjID(objID)根据模型 ID 返回其 ID 字段名如bk_biz_id、bk_set_id、bk_module_id、bk_host_id、bk_process_id通用模型及未命中场景回退为bk_inst_idGetInstNameFieldName(objID)根据模型 ID 返回其名称/展示名字段名如bk_biz_name、bk_set_name、bk_module_name、bk_host_inner_ip、bk_process_name通用模型回退为bk_inst_name。字段常量定义于 src/common/definitions.go。因此当association_obj_id为host时info中的bk_inst_id实际来自bk_host_idbk_inst_name实际来自bk_host_inner_ip主机内网 IP这就是响应示例中显示127.0.0.3的原因。后端实现原理与调用链1. 服务注册路由在 src/scene_server/topo_server/service/service_initfunc.go 中注册utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /findmany/inst/association/association_object/inst_base_info, Handler: s.SearchInstAssociationWithOtherObject})同时src/ac/parser/topolatest.go 中定义了对应的正则^/api/v3/findmany/inst/association/association_object/inst_base_info$用于 API 网关鉴权与资源匹配。2. 请求结构体请求参数对应元数据结构RequestInstAssociationObjectID与RequestInstAssociationObjectIDCondition定义于 src/common/metadata/association.gotype RequestInstAssociationObjectID struct { Condition RequestInstAssociationObjectIDCondition json:condition Page BasePage json:page } type RequestInstAssociationObjectIDCondition struct { ObjectID string json:bk_obj_id // 实例模型ID InstID int64 json:bk_inst_id // 实例ID IsTargetObject bool json:is_target_object // bk_obj_id 是否为目标模型 AssociationObjectID string json:association_obj_id // 关联对象的模型ID }3. 核心处理逻辑SearchInstAssociationWithOtherObjectsrc/scene_server/topo_server/service/inst.go先完成入参解码与必填校验然后根据is_target_object构造关联关系查询条件if reqParams.Condition.IsTargetObject { // 作为目标模型查 bk_asst_obj_id bk_obj_id 且 bk_asst_inst_id bk_inst_id 的关系 cond.Field(common.BKAsstObjIDField).Eq(reqParams.Condition.ObjectID) cond.Field(common.BKAsstInstIDField).Eq(reqParams.Condition.InstID) cond.Field(common.BKObjIDField).Eq(reqParams.Condition.AssociationObjectID) } else { // 作为源模型查 bk_obj_id bk_obj_id 且 bk_inst_id bk_inst_id 的关系 cond.Field(common.BKObjIDField).Eq(reqParams.Condition.ObjectID) cond.Field(common.BKInstIDField).Eq(reqParams.Condition.InstID) cond.Field(common.BKAsstObjIDField).Eq(reqParams.Condition.AssociationObjectID) }关联关系记录由bk_obj_id/bk_inst_id源模型/源实例与bk_asst_obj_id/bk_asst_inst_id目标模型/目标实例成对描述字段常量见 src/common/definitions.go。理解这一点后is_target_object的语义就非常清晰is_target_object false默认bk_obj_idbk_inst_id作为关联关系的源端返回association_obj_id模型下所有作为目标端的关联实例is_target_object truebk_obj_idbk_inst_id作为关联关系的目标端返回association_obj_id模型下所有作为源端的关联实例。随后调用SearchInstAssociationSingleObjectInstInfosrc/scene_server/topo_server/logics/inst/association.go完成两步查询通过 CoreService 的Association().ReadInstAssociation读取满足条件的关联关系rsp.Info根据方向isTargetObject从每条关系中提取对端实例 ID目标模式下取AsstInstID源模式下取InstID汇总为objIDInstIDArr依据association_obj_id通过GetInstIDFieldByObjID/GetInstNameFieldName确定该模型的 ID 字段与名称字段仅查询{idField, nameField}两个字段Page设为Start: 0, Limit: BKNoLimit即一次性取全量再交回上层分页将结果逐条转换为metadata.InstBaseInfo{ID, Name}返回同时返回关联关系总数rsp.Count作为count。最终服务层将结果封装为{info: infos, count: cnt}返回见 src/scene_server/topo_server/service/inst.go。InstBaseInfo结构体同样定义于 src/common/metadata/association.go其 JSON 字段即bk_inst_id与bk_inst_name。4. 底层依赖ReadInstAssociationReadInstAssociation是 CoreService 提供的实例关联关系查询能力客户端封装见 src/apimachinery/coreservice/association/api.go接口定义见 src/apimachinery/coreservice/association/association.go。它接收metadata.InstAsstQueryCondition包含cond与bk_obj_id并返回关联关系列表是本接口“先查关系、再查实例”两步法的第一步。典型使用场景与注意事项典型场景拓扑反查已知交换机/负载均衡等设备实例反查其关联的业务、集群、模块或主机用于可视化拓扑与影响面分析主机关联查询已知主机实例查询其关联的进程/服务实例association_obj_id传proc或反向由进程查主机通用模型关联展示在自定义模型通用模型之间建立关联后通过该接口获取对端实例的 ID 与名称用于列表展示避免拉取完整实例详情。注意事项condition三个字段全部必填缺少任一字段会直接返回参数错误is_target_object方向必须与实际关联关系的建联方向一致否则可能返回空结果——建议先通过关联关系详情接口确认源/目标模型方向limit上限 200超出会触发CCErrCommPageLimitIsExceeded错误大数据量场景应配合start分页拉取返回的bk_inst_id/bk_inst_name是通用输出字段名实际语义随association_obj_id模型变化见字段映射表例如主机模型的bk_inst_name实为内网 IP该接口聚焦“基本信息”ID 名称如需完整属性应使用对应模型的实例查询接口如list_biz_hosts、find_inst等二次拉取详情。延伸阅读中文接口文档docs/apidoc/apigw/open/zh/search_inst_asst_object_inst_base_info.md英文接口文档docs/apidoc/apigw/open/en/search_inst_asst_object_inst_base_info.mdAPI 网关资源定义docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yamlESB 组件注册docs/apidoc/cc/cc.yaml服务端处理函数src/scene_server/topo_server/service/inst.go关联查询业务逻辑src/scene_server/topo_server/logics/inst/association.go请求/响应元数据结构与关联字段常量src/common/metadata/association.go、src/common/definitions.go模型 ID/名称字段映射src/common/metadata/object.go分页校验规则src/common/metadata/page.goCoreService 关联关系查询封装src/apimachinery/coreservice/association/api.go赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云配置平台BK-CMDB实例关联模型实例基本信息查询接口详解search_inst_asst_object_inst_base_info蓝鲸智云配置平台BK CMDB实例关联模型实例基本信息查询接口详解search_inst_asst_object_inst_base_info 本文围绕蓝后端企业应用运维蓝鲸智云 CMDB 实例关联关系查询接口find_instance_association实战指南蓝鲸智云 CMDB 实例关联关系查询接口find_instance_association实战指南 导读 find_instance_association后端企业应用运维蓝鲸 CMDB 关联关系实例查询指南search_inst 接口原理与实战蓝鲸 CMDB 关联关系实例查询指南search_inst 接口原理与实战 本文以蓝鲸智云配置平台bk cmdb对外网关API Gateway的 se后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
