后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读本文基于蓝鲸智云配置平台bk-cmdb开放 API 文档中「创建模型Create Object」接口的说明完整讲解POST /api/v3/create/object接口的请求参数、请求/响应示例并结合 src/scene_server/topo_server/logics/model/object.go 与 src/scene_server/topo_server/service/object.go 的源码剖析模型创建背后的校验规则、建表逻辑、默认属性组与审计链路。读完本文你将掌握如何通过开放 API 在 bk-cmdb 中安全、正确地创建一个自定义模型对象模型并理解每个参数在底层数据模型与数据库中的实际落点。一、接口概述与权限要求「创建模型」是 bk-cmdb 模型管理体系中最高频的基础操作之一业务模型如主机、模块由系统内置而业务自定义数据如机柜、网络设备、存储资源等则需要通过该接口以「模型 模型分组」的方式建模随后才能向该模型写入实例数据。接口路径POST /api/v3/create/object接口语义创建一个模型对象模型权限要求创建模型Create Model权限未授权时将返回无权限错误网关注册该路由在 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中登记operationId为create_object后端转发方式为 HTTP POST路径原样透传至 bk-cmdb 的/api/v3/create/object。二、请求参数详解创建模型接口的请求体为一个 JSON 对象各字段定义如下表名称类型必填说明creatorstring否本条数据的创建者bk_classification_idstring是模型所属分组的 ID模型分组只能由英文字母命名bk_obj_idstring是模型 ID只能由英文字母命名全局唯一bk_obj_namestring是模型名称用于展示可以使用任意人类可读语言bk_obj_iconstring否模型的图标信息用于前端展示obj_sort_numberint否模型在其所属模型分组下的排序序号参数与元数据结构的对应关系上述参数并非散落的业务字段而是与 src/common/metadata/object.go 中定义的模型常量与Object结构体一一对应ModelFieldObjCls bk_classification_id模型分组 ID对应结构体字段ObjCls数据库字段同样为bk_classification_idModelFieldObjectID bk_obj_id模型 ID对应ObjectIDModelFieldObjectName bk_obj_name模型名称对应ObjectNameModelFieldObjIcon bk_obj_icon模型图标对应ObjIconModelFieldObjSortNumber obj_sort_number排序序号对应ObjSortNumber。在 src/scene_server/topo_server/logics/model/object.go 的isValid参数校验逻辑中请求体经由mapstruct.Decode2Struct反序列化为metadata.Object结构体随后依次执行以下校验模型 ID 校验bk_obj_id必须通过valid.ValidModelIDField的模型 ID 格式校验模型名称校验bk_obj_name必须通过valid.ValidModelNameField校验分组必填校验创建时bk_classification_id必须存在否则返回参数缺失错误内置模型占用校验bk_obj_id不得与系统内置模型 ID如biz、set、module、host、proc等冲突源码中通过metadata.IsCommon(obj.ObjectID)判断命中内置 ID 时提示 the built-in object id, please use a new one供应商账户回填OwnerID即bk_supplier_account由服务端以请求上下文中的kit.SupplierAccount自动填充用户无需也无法在请求中指定。创建前的分组存在性检查分组 ID 必须是已存在的模型分组。在 createObjectParamCheck 中会先调用isClassificationExist按bk_classification_id查询bkTableNameObjClassification模型分组表的计数若分组不存在直接返回错误码CCErrTopoObjectClassificationSelectFailed1101024见 src/common/errInfo.go。同时该函数还强制校验bk_obj_icon不能为空图标未设置时返回CCErrCommParamsNeedSetobj_sort_number不能小于 0数值非法时返回CCErrCommParamsInvalid。请求示例以创建一个位于test分组下的test模型为例与文档示例一致{ creator: admin, bk_classification_id: test, bk_obj_name: test, bk_obj_icon: icon-cc-business, bk_obj_id: test, obj_sort_number: 1 }提示上述示例为便于演示仅作最小化配置。生产实践中建议bk_obj_id使用有业务语义的英文标识如rack、switchbk_obj_name使用中文或英文展示名bk_obj_icon使用 bk-cmdb 前端已注册的图标类名如icon-cc-business。三、响应示例与响应参数接口返回统一结果结构正常创建成功时{ code: 0, permission: null, result: true, message: success, data: { description: , bk_ishidden: false, bk_classification_id: test, creator: admin, bk_obj_name: test, bk_ispaused: false, last_time: null, bk_obj_id: test, create_time: null, bk_supplier_account: 0, position: , bk_obj_icon: icon-cc-business, modifier: , id: 2000002118, ispre: false, obj_sort_number: 1 } }其中响应参数含义如下名称类型说明resultbool请求是否成功true 成功false 失败codeint错误码0 表示成功0 表示失败错误码messagestring请求失败时返回的错误信息permissionobject权限信息dataobject请求返回的数据即创建成功的模型对象响应 data 中的关键字段解读对照 Object 结构体 可以解释data中每个字段的来源与含义id系统生成的自增模型 ID示例中为2000002118是模型在数据库中的主键后续创建属性、查询实例、配置权限时均会用到bk_supplier_account供应商账户服务端自动写入示例中为0默认供应商账户可推断默认场景下单供应商部署即为该值ispre是否内置模型IsPre新创建的模型为falsebk_ishidden是否在页面上隐藏新模型默认falsebk_ispaused是否停用新模型默认falsecreate_time/last_time创建时间与最后修改时间由数据库层写入响应时可能为 nullmodifier最后修改者刚创建时为空字符串。CreateModelResult响应体定义于 src/common/metadata/toposerver.godata字段类型即为metadata.Object说明接口返回的是完整的模型元数据对象。四、请求背后的完整调用链与实现原理开放 API 的/api/v3/create/object请求在 bk-cmdb 内部会经过一条清晰的「网关 → apiserver → topo_server → core_service」链路理解这条链路有助于排查问题与二次开发。第 1 跳apiserver 按 URL 路由并转发apiserver 是 bk-cmdb 的统一接入层。在 src/apiserver/service/url.go 中create动词的 URL 会被归类到 topo 组件并由 TopoFilterChan 通过服务发现将请求转发至topo_server的/topo/v3前缀路径。第 2 跳topo_server 事务化创建src/scene_server/topo_server/service/object.go 中的CreateObject处理器承担创建主流程先建表后建模型调用createObjectTable提前调用 core_service 的CreateModelTables在 MongoDB 中创建模型对应的集合collection。源码注释解释了原因——避免模型创建后查询数据时出现 MongoDB 快照不可用错误SnapshotUnavailable ... pending collection catalog changes即建表与建模型必须严格分离事务内执行创建通过AutoRunTxn开启分布式事务在事务内调用ObjectOperation().CreateObject真正创建模型权限落库若开启了鉴权auth.EnableAuthorize()则在 IAM 中登记新模型实例使后续的模型管理操作具备权限判定依据事务整体成功后通过ctx.RespEntity(rsp)返回模型对象。第 3 跳core_service 的 CreateModel 与模型初始化object.go 的 CreateObject 实现 展示了一个模型创建时服务端自动完成的全部初始化动作参数校验createObjectParamCheck完成前文所述的 ID/名称/分组/图标/排序号校验写入模型元数据调用 core_service 的Model().CreateModel请求结构体见 src/common/metadata/core_service.goSpec字段即模型对象将模型记录写入模型表创建默认属性分组为模型创建名为Default的默认分组GroupName: Default、IsDefault: true、GroupIndex: -1新模型的所有属性在未手动分组前都归入该组创建默认属性createDefaultAttrs批量创建系统预置属性包括创建时间bk_created_at、创建人bk_created_by、更新时间、更新人、实例 IDbk_inst_id、实例名称bk_inst_name等内置字段预置属性定义可见 object.go 起的recordedAttrs创建唯一索引将默认属性组成唯一键调用CreateModelAttrUnique建立唯一索引。源码注释特别说明该索引与index.MainLineInstanceUniqueIndex、index.InstanceUniqueIndex强依赖因为 MongoDB 4.2.64.4 之前事务中不能建表建表与建立索引是互斥操作所以必须在本环节预建生成审计日志通过auditlog.NewObjectAuditLog生成AuditCreate类型的对象创建审计日志并落库实现模型创建全程可追溯。第 4 跳返回结果core_service 写入成功后CreateObject将新模型的ID回填到obj.ID最终以metadata.Object形式层层返回形成第三节中的响应 JSON。五、错误码与常见失败场景创建模型最常见的失败场景及其对应错误码如下错误码常量定义见 src/common/errInfo.go错误码含义触发场景1101013CCErrTopoObjectCreateFailed创建模型失败core_service 写入模型元数据失败1101024CCErrTopoObjectClassificationSelectFailed查询/校验模型分组失败bk_classification_id对应的分组不存在CCErrCommParamsNeedSet参数缺失bk_classification_id未传、bk_obj_icon为空CCErrCommParamsInvalid参数非法obj_sort_number小于 0、bk_obj_id与内置模型 ID 冲突此外调用侧还需注意bk_classification_id与bk_obj_id仅允许英文字母命名模型创建是重操作涉及建表、建索引与事务请求超时阈值建议放宽模型 ID 一旦创建不可随意修改规划时应先确定命名规范。六、验证方式从测试用例看接口契约仓库中的集成测试用例完整覆盖了该接口的正向与异常分支可作为接口契约的补充验证。例如 src/test/topo_server/object_test.go 中多次调用objectClient.CreateObject创建模型并断言返回src/test/topo_server/inst_test.go 在实例测试前置步骤中先创建模型再写实例。若需要二次开发或本地调试可参考 docs/apidoc/apigw/README.md 了解开放 API 的整体接入方式。七、小结本文完整梳理了 bk-cmdb「创建模型」开放 API 的请求参数、请求/响应示例与底层实现参数层面明确了bk_classification_id、bk_obj_id、bk_obj_name三个必填项以及creator、bk_obj_icon、obj_sort_number三个可选项的约束实现层面揭示了「先建表再建模型」「事务化创建」「默认属性分组与唯一索引预建」「审计日志落库」等核心机制并给出了可复现的测试用例路径。掌握这些内容后你即可通过开放 API 稳定地批量建模为后续实例数据写入与模型关联打下基础。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐bk-cmdb 创建模块create_moduleOpenAPI 接口实战指南参数详解、调用示例与源码级实现剖析bk cmdb 创建模块create_moduleOpenAPI 接口实战指南参数详解、调用示例与源码级实现剖析 蓝鲸智云配置平台bk cmdb中后端企业应用运维bk-cmdb 创建模型属性接口 create_object_attribute参数详解与源码实现剖析bk cmdb 创建模型属性接口 create_object_attribute参数详解与源码实现剖析 本篇技术文章基于 bk cmdb蓝鲸智云配置平台的后端企业应用运维蓝鲸配置平台 bk-cmdb 创建模型接口 create_object 详解从 ESB 调用到 topo_server 源码实现蓝鲸配置平台 bk cmdb 创建模型接口 create_object 详解从 ESB 调用到 topo_server 源码实现 本文围绕 bk cmdb 的后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考