bk-cmdb 实例关联关系查询接口深度解析:一键获取实例的源/目标全部关联
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):
- 条件完整性:
bk_inst_id == 0或bk_obj_id为空时,返回CCErrCommParamsNeedSet错误,提示必须同时提供'bk_inst_id' & 'bk_obj_id'; - 字段必填:
fields为空数组时直接返回错误,避免无字段查询; - 分页上限:
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 投影 + 分页)
八、实战注意事项
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.go
- coreservice 查询入口: 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