蓝鲸 CMDB `batch_create_inst` 接口实战:批量创建通用模型实例的调用与原理

原创2026-10-14 10:18:061,425 阅读
文章标签:后端企业应用微服务

蓝鲸 CMDB batch_create_inst 接口实战:批量创建通用模型实例的调用与原理

导读

batch_create_inst(批量创建通用模型实例)是蓝鲸智云配置平台(bk-cmdb)对外提供的核心写接口之一,用于通过一次 API 调用向某个通用模型批量写入最多 200 条实例数据,适用于设备台账批量录入、CMDB 初始化数据导入、自动化平台同步实例等高频场景。本文以官方 API 文档(英文版、中文版)为主体,结合仓库源码讲解接口的请求/响应协议、调用示例、返回的索引映射语义,以及从 ESB 网关到 topo_server、再到 coreservice 的完整落库链路,帮助开发者正确使用该接口并理解其校验与错误处理机制。

一、接口概览

项目 说明
接口名称 batch_create_inst(批量创建通用模型实例)
建议方法 POST(suggest_method: POST)
接口类型 operate(写操作)
网关路径 /v2/cc/batch_create_inst/
后端路径 /api/v3/createmany/instance/object/{bk_obj_id}
功能版本 v3.10.2+
所需权限 模型实例新建权限(New instance permission)

以上网关与后端路径的映射关系可以直接在仓库的 ESB 组件定义 docs/apidoc/cc/cc.yaml 中查到:该文件将蓝鲸 ESB 的 /v2/cc/batch_create_inst/ 路由映射到 bk-cmdb 内部的 /api/v3/createmany/instance/object/{bk_obj_id}。在 esb-cc 文档目录 docs/apidoc/esb-cc/zh_hans 下可以找到对应的旧版 ESB 使用说明。

二、请求参数详解

接口除了携带蓝鲸 ESB 的通用鉴权参数(如请求示例中的 bk_app_code、bk_app_secret、bk_username、bk_token)外,核心业务参数只有两个:

参数 类型 必选 描述
bk_obj_id string 是 用于创建的模型 ID,只允许创建通用模型的实例
details array 是 需要创建的实例内容,最多不能超过 200 个,内容为该模型实例的属性信息

其中 details 数组内的每个元素(即一条实例记录)的常用属性字段如下:

字段 类型 必选 描述
bk_inst_name string 是 实例名
bk_asset_id string 是 固资编号
bk_sn string 否 设备 SN
bk_operator string 否 维护人

需要说明的是,details 中的属性字段并非固定为以上四个,实际可填写模型自定义的全部属性字段;文档给出的这四个字段是通用模型最常见的公共属性。如果模型配置了唯一性校验的属性(例如 bk_asset_id 固资编号为唯一字段),则重复提交会在批量创建中被逐条拦截,具体见下文"返回结果解析"。

三、请求示例

以模型 bk_switch(交换机模型)为例,一次性创建 s1、s2、s3 三条实例:

{
    "bk_app_code": "esb_test",
    "bk_app_secret": "xxx",
    "bk_username": "xxx",
    "bk_token": "xxx",
    "bk_obj_id": "bk_switch",
    "details": [
        {
            "bk_inst_name": "s1",
            "bk_asset_id": "test_001",
            "bk_sn": "00000001",
            "bk_operator": "admin"
        },
        {
            "bk_inst_name": "s2",
            "bk_asset_id": "test_002",
            "bk_sn": "00000002",
            "bk_operator": "admin"
        },
        {
            "bk_inst_name": "s3",
            "bk_asset_id": "test_003",
            "bk_sn": "00000003",
            "bk_operator": "admin"
        }
    ]
}

说明:bk_app_code / bk_app_secret 为蓝鲸应用身份凭证,bk_username / bk_token 为用户身份凭证,实际调用时由网关鉴权后透传给 CMDB 后端。若直接在 CMDB 内部调用后端路径 /api/v3/createmany/instance/object/{bk_obj_id},同样需要携带 CMDB 认可的认证头与 bk_username。

四、返回结果解析

返回结果示例

{
    "result": true,
    "code": 0,
    "message": "",
    "permission": null,
    "request_id": "e43da4ef221746868dc4c837d36f3807",
    "data": {
        "success_created": {
            "1": 1001,
            "2": 1002
        },
        "error_msg": {
            "0": "数据唯一性校验失败, [bk_asset_id: test_001] 重复"
        }
    }
}

response 公共字段

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

data 字段语义(重要)

字段 类型 描述
success_created map key 为实例在参数 details 中的 index(从 0 开始),value 为创建成功的实例 ID
error_msg map key 为实例在参数 details 中的 index,value 为失败信息

以示例响应为例:

  • details[1](s2)创建成功,得到实例 ID 1001;details[2](s3)创建成功,得到实例 ID 1002;
  • details[0](s1)失败,原因 数据唯一性校验失败, [bk_asset_id: test_001] 重复——即 bk_asset_id=test_001 已存在于库中,违反了唯一性约束。

这种"成功与失败按索引分表返回"的设计,使得一次批量调用中可以部分成功、部分失败:只要请求本身格式合法(code=0),业务方就应该遍历 success_created 与 error_msg 两个 map 分别处理成功项与失败项,而不是把整个请求视为全部成功或全部失败。

该响应结构在仓库源码中对应 CreateManyCommInstResultDetail 定义,见 src/common/metadata/inst.go:

type CreateManyCommInstResultDetail struct {
	SuccessCreated map[int64]int64  `json:"success_created"`
	Error          map[int64]string `json:"error_msg"`
}

五、完整调用链路与源码级实现

1. 网关层:ESB → topo_server

batch_create_inst 最终落地在**拓扑服务(topo_server)**的 CreateManyInstance 处理器上。路由注册见 src/scene_server/topo_server/service/service_business_initfunc.go:

utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/createmany/instance/object/{bk_obj_id}",
	Handler: s.CreateManyInstance})

处理器实现见 src/scene_server/topo_server/service/inst.go,其关键拦截逻辑如下(从源码结构可以推断):

  1. 从请求体中解码 CreateManyCommInst(包含 bk_obj_id 与 details 数组);
  2. 禁止用通用创建接口操作内置模型:若 objID 命中 common.IsInnerModel(objID),直接返回 CCErrCommForbiddenOperateInnerModelInstanceWithCommonAPI 错误(错误码 1199084,定义见 src/common/errInfo.go)。例如业务、集群、模块、主机等内置模型不在此接口允许范围内;
  3. 禁止操作主线(mainline)模型实例:通过 IsMainlineObject 判断,若目标模型属于主线模型则返回对应错误——主线实例必须沿拓扑关系创建;
  4. 通过 InstOperation().CreateManyInstance 走业务逻辑层。

2. 逻辑层:数量限制与参数校验

业务逻辑实现在 src/scene_server/topo_server/logics/inst/inst.go 的 CreateManyInstance 方法中:

if len(data) == 0 {
	// 返回 CCErrCommInstDataNil("details")
}
if len(data) > 200 {
	// 返回 CCErrCommXXExceedLimit("details", 200)
}

即:details 不能为空,且最多 200 条,超限返回错误码 CCErrCommXXExceedLimit(1199035,见 src/common/errInfo.go)。这两项校验与 API 文档中"最多不能超过 200 个"的约定完全一致。

随后逻辑层构造 CreateManyModelInstance{Datas: data} 调用 CoreService().Instance().CreateManyInstance 发起对 coreservice 的 RPC 请求。

3. 数据层:coreservice 逐条校验与批量落库

客户端方法定义见 src/apimachinery/coreservice/instance/api.go,实际请求路径为:

subPath := "/batch/create/model/%s/instance"

该路径在 coreservice 的 service_initfunc.go 中注册(/createmany/model/{bk_obj_id}/instance 与 /batch/create/model/{bk_obj_id}/instance 两个路由并存),核心实现位于 src/source_controller/coreservice/core/instances/instance.go 的 CreateManyModelInstance:

  • 先为整批数据一次性构建实例校验器(getValidatorsFromInstances);
  • 逐条执行 validCreateInstanceData 校验(含必填字段、字段类型、唯一性等);
  • 校验失败的条目记录到 Exceptions(携带原始 index),不会中断整批请求;
  • 校验通过的条目通过 save 逐条写入,最终汇总为 CreateManyDataResult,其中 Created 列表每一项都带有 OriginIndex(对应 details 中的下标),供上层还原成 success_created / error_msg 的索引映射。

批量写入阶段的 batchSave 实现见 src/source_controller/coreservice/core/instances/instance_crud.go,它会:

  • 通过 getSequences 预先生成一批实例 ID;
  • 为每条数据自动补齐 bk_obj_id、实例 ID 字段、owner_id(bk_supplier_account)、create_time、last_time、bk_created_by 等系统字段;
  • 使用 MongoDB 批量 Insert 落库;若命中唯一索引冲突,识别为重复键错误并返回 CCErrCommDuplicateItem——这正是响应示例中"数据唯一性校验失败,[bk_asset_id: test_001] 重复"信息的底层来源。

4. 权限校验

该接口要求模型实例新建权限。bk-cmdb 的权限体系基于蓝鲸权限中心(IAM)实现,实例级新建/查看/编辑的权限扩展定义在 src/ac/extensions/instance.go,权限中心资源初始化见 src/ac/iam/initial_resources.go。无权限时接口返回 permission 字段与相关错误码,调用方可通过蓝鲸权限中心申请对应资源实例的创建权限后重试。

六、常见错误与排错建议

现象 可能原因 处理建议
code > 0,message 提示 details 为空 details 传了空数组 至少传入 1 条实例数据(对应错误码 CCErrCommInstDataNil)
message 提示数量超限 details 超过 200 条 拆分为多次请求,单次不超过 200 条(对应错误码 CCErrCommXXExceedLimit)
报错"禁止操作内置模型/主线模型实例" bk_obj_id 指向内置模型(如 biz、set、module、host)或主线模型 改为对应的专有接口(如业务/集群/模块/主机相关接口),本接口仅限通用模型
data.error_msg 中某 index 返回唯一性校验失败 该条记录的 bk_asset_id 等唯一字段与库中已有数据重复 按 index 定位失败的记录,修正唯一字段后重试或改用更新接口
无权限被拦截 缺少"模型实例新建权限" 到蓝鲸权限中心申请对应模型实例的新建权限

七、关联接口速查

如果批量创建通用模型实例无法满足需求,可结合仓库文档对比以下关联接口:

  • 单实例创建 create_inst(/v2/cc/create_inst/):一次创建一条实例,路由映射见 docs/apidoc/cc/cc.yaml,对应接口文档 create_inst.md;
  • Excel 批量导入:通过 /create/instance/object/{bk_obj_id}/by_import 走 Excel 导入流程,处理器 CreateInstsByImport 见 src/scene_server/topo_server/service/inst.go,适合带表格数据(内嵌表/引用实例)的复杂批量场景;
  • 批量创建被引用模型的实例 batch_create_quoted_inst(/v2/cc/batch_create_quoted_inst/):专门用于创建被引用模型实例,见 batch_create_quoted_inst.md 与 cc.yaml 中对应的 dest_path 映射;
  • 批量更新实例 batch_update_inst:对已存在实例批量修改属性,见 batch_update_inst.md。

八、小结

batch_create_inst 是 bk-cmdb 通用模型实例批量写入的标准入口,其核心要点可归纳为四点:仅限通用模型(内置模型与主线模型被显式拒绝)、单批上限 200 条、逐条校验且互不影响(部分成功部分失败)、返回结果按 details 下标索引映射(success_created 与 error_msg)。理解这四点,即可在自动化平台、数据同步任务中正确编排该接口,并利用索引映射精准定位失败记录、实现可重试的幂等补偿逻辑。

登录后查看全文
bk-cmdb