bk-cmdb 实例关联关系查询接口深度解析:一键获取实例的源/目标全部关联

原创2026-10-14 20:30:491,699 阅读
文章标签:后端企业应用微服务

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_code string 应用 ID(ESB 应用编码)
bk_app_secret string 应用密钥
bk_username string 操作用户名
bk_token string 用户登录态 Token(可与 bk_username 二选一)

3.2 接口业务参数

字段 类型 必选 描述
bk_inst_id int 是 实例 ID
bk_obj_id string 是 模型 ID(如 bk_router、bk_switch)
fields array 是 需要返回的字段
start int 否 记录开始位置
limit int 否 分页大小,最大值 500

注意:接口业务参数位于请求体 condition 对象内(见下方示例),fields 与 page 为平级参数。

page 分页对象

字段 类型 必选 描述
start int 是 记录开始位置(偏移量)
limit int 是 每页限制条数,最大 200

源码印证:请求结构体定义于 src/common/metadata/association.go:

type 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_id,Page 对应 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"
        }
    ]
}

从返回可以看出,虽然查询条件是"实例 16(bk_router)",但命中的记录中实例 16 全部出现在 bk_asst_inst_id(目标实例 ID)位置,而源侧分别是 bk_switch 下的实例 1 和实例 2——这正是"目标模型实例被关联"的场景,印证了接口的双向查询能力。


六、返回结果参数说明

6.1 response 通用封装

字段 类型 描述
result bool 请求成功与否。true:请求成功;false:请求失败
code int 错误编码。0 表示 success,>0 表示失败错误
message string 请求失败返回的错误信息
permission object 权限信息(无权限时为 null 或具体鉴权结果)
request_id string 请求链 ID,用于全链路日志追踪
data object 请求返回的数据

6.2 data 数据项说明

字段 类型 描述
id int64 关联 ID(实例关联记录的自增序列号)
bk_inst_id int64 源模型实例 ID
bk_obj_id string 关联关系源模型 ID
bk_asst_inst_id int64 关联关系目标模型实例 ID
bk_asst_obj_id string 目标模型 ID
bk_obj_asst_id string 自动生成的模型关联关系 ID(如 bk_switch_default_bk_router)
bk_asst_id string 关系名称(关联类型 ID,如 default)

上述字段与源码中实例关联数据结构 InstAsst 完全对应,其定义位于 src/common/metadata/association.go:

type 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):

  1. 条件完整性:bk_inst_id == 0 或 bk_obj_id 为空时,返回 CCErrCommParamsNeedSet 错误,提示必须同时提供 'bk_inst_id' & 'bk_obj_id';
  2. 字段必填:fields 为空数组时直接返回错误,避免无字段查询;
  3. 分页上限:page.limit 超过 common.BKMaxInstanceLimit 时返回 CCErrCommPageLimitIsExceeded(分页限制超出)。

7.3 分页与排序约定

代码中强制将排序字段设置为 id(request.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, <a href="https://link.gitcode.com/i/3a2c1bf94cff02302144b91acc1a4e52" target="_blank">]string{request.Condition.ObjectID}) 校验用户对目标模型实例的查询权限([src/scene_server/topo_server/service/association.go)。鉴权失败时返回 403 无权限响应,这对应文档中"权限:模型实例查询权限"的说明。

7.5 底层调用链

SearchAssociationRelatedInst 并不直接访问数据库,而是通过 apimachinery 客户端调用 coreservice 的 Association().ReadInstAssociation(src/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 投影 + 分页)

八、实战注意事项

  1. fields 是必填项:漏传或传空数组会被直接拒绝,建议至少包含 id、bk_inst_id、bk_asst_inst_id、bk_obj_id、bk_asst_obj_id 以便定位关联双方;
  2. 分页要传全:page 对象中 start 与 limit 均必填,limit 受服务端 500 上限约束,超出会返回 CCErrCommPageLimitIsExceeded;
  3. 结果方向需自行区分:接口返回的 data 数组混合了"该实例作为源"与"该实例作为目标"两类记录,可通过比较 bk_inst_id/bk_asst_inst_id 与查询的 bk_inst_id 是否相等来判断记录方向;
  4. 权限前置:调用方(应用)需要对查询的模型具备实例查询权限,否则即使参数正确也会被鉴权拦截;
  5. 排查问题用 request_id:返回报文中的 request_id 是请求链 ID,结合日志可按 rid 维度全链路排查查询失败原因。

九、关联资源延伸阅读

登录后查看全文
bk-cmdb