蓝鲸 CMDB `batch_create_inst` 接口实战:批量创建通用模型实例的调用与原理
蓝鲸 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)创建成功,得到实例 ID1001;details[2](s3)创建成功,得到实例 ID1002;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,其关键拦截逻辑如下(从源码结构可以推断):
- 从请求体中解码
CreateManyCommInst(包含bk_obj_id与details数组); - 禁止用通用创建接口操作内置模型:若
objID命中common.IsInnerModel(objID),直接返回CCErrCommForbiddenOperateInnerModelInstanceWithCommonAPI错误(错误码 1199084,定义见 src/common/errInfo.go)。例如业务、集群、模块、主机等内置模型不在此接口允许范围内; - 禁止操作主线(mainline)模型实例:通过
IsMainlineObject判断,若目标模型属于主线模型则返回对应错误——主线实例必须沿拓扑关系创建; - 通过
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)。理解这四点,即可在自动化平台、数据同步任务中正确编排该接口,并利用索引映射精准定位失败记录、实现可重试的幂等补偿逻辑。