• 后端
• 企业应用
• 运维

本指南围绕蓝鲸智云配置平台（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，请求方式POST，api_type为query；
• API 网关（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。

请求参数详解

顶层参数

说明：虽然fields允许指定任意属性，但该接口的核心定位是返回关联实例的基本信息，实际后端组装结果时以实例 ID 字段与实例名/展示名字段为准（详见下文「模型字段映射」一节），fields的扩展属性筛选能力有限，日常调用建议不传或保持默认。

condition 对象

page 对象

参数合法性校验（源码视角）

从源码看，三个必填参数缺一不可，且服务端做了显式校验。在 src/scene_server/topo_server/service/inst.go 的SearchInstAssociationWithOtherObject处理函数中：

• bk_obj_id为空 → 报CCErrCommParamsNeedSet（需设置bk_obj_id）；
• bk_inst_id为 0 → 报CCErrCommParamsNeedSet（需设置bk_inst_id）；
• association_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，详见下方字段映射表）。

响应参数说明

data 对象

data.info 字段说明

不同模型下的 bk_inst_id / bk_inst_name 字段映射

接口返回值中统一使用bk_inst_id与bk_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_id；
• GetInstNameFieldName(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_id，bk_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.go：

type 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. 核心处理逻辑

SearchInstAssociationWithOtherObject（src/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_id+bk_inst_id作为关联关系的源端，返回association_obj_id模型下所有作为目标端的关联实例；
• is_target_object = true：bk_obj_id+bk_inst_id作为关联关系的目标端，返回association_obj_id模型下所有作为源端的关联实例。

随后调用SearchInstAssociationSingleObjectInstInfo（src/scene_server/topo_server/logics/inst/association.go）完成两步查询：

1. 通过 CoreService 的Association().ReadInstAssociation读取满足条件的关联关系（rsp.Info）；
2. 根据方向（isTargetObject）从每条关系中提取对端实例 ID：目标模式下取AsstInstID，源模式下取InstID，汇总为objIDInstIDArr；
3. 依据association_obj_id通过GetInstIDFieldByObjID/GetInstNameFieldName确定该模型的 ID 字段与名称字段，仅查询{idField, nameField}两个字段（Page设为Start: 0, Limit: BKNoLimit，即一次性取全量再交回上层分页）；
4. 将结果逐条转换为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. 底层依赖：ReadInstAssociation

ReadInstAssociation是 CoreService 提供的实例关联关系查询能力，客户端封装见 src/apimachinery/coreservice/association/api.go，接口定义见 src/apimachinery/coreservice/association/association.go。它接收metadata.InstAsstQueryCondition（包含cond与bk_obj_id）并返回关联关系列表，是本接口“先查关系、再查实例”两步法的第一步。

典型使用场景与注意事项

典型场景：

1. 拓扑反查：已知交换机/负载均衡等设备实例，反查其关联的业务、集群、模块或主机，用于可视化拓扑与影响面分析；
2. 主机关联查询：已知主机实例，查询其关联的进程/服务实例（association_obj_id传proc），或反向由进程查主机；
3. 通用模型关联展示：在自定义模型（通用模型）之间建立关联后，通过该接口获取对端实例的 ID 与名称用于列表展示，避免拉取完整实例详情。

注意事项：

1. condition三个字段全部必填，缺少任一字段会直接返回参数错误；
2. is_target_object方向必须与实际关联关系的建联方向一致，否则可能返回空结果——建议先通过关联关系详情接口确认源/目标模型方向；
3. limit上限 200，超出会触发CCErrCommPageLimitIsExceeded错误；大数据量场景应配合start分页拉取；
4. 返回的bk_inst_id/bk_inst_name是通用输出字段名，实际语义随association_obj_id模型变化（见字段映射表），例如主机模型的bk_inst_name实为内网 IP；
5. 该接口聚焦“基本信息”（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.md
• API 网关资源定义：docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml
• ESB 组件注册：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.go
• CoreService 关联关系查询封装：src/apimachinery/coreservice/association/api.go

• 后端
• 企业应用
• 运维