★ FEATURED ARTICLE 后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载蓝鲸智云配置平台BlueKing CMDB中模型分类Model Classification用于对模型对象进行分组管理例如系统内置的主机管理业务拓扑组织架构网络等分组。本文以 APIGateway 开放接口create/model/classification为核心完整讲解创建模型分类的请求参数、请求与响应示例、响应字段含义并结合源码深入分析参数校验规则、内置分类保护机制与数据落库流程帮助你正确、安全地通过 API 扩展自己的模型分组。接口概述创建模型分类接口用于在 CMDB 中新增一条模型分类记录对应权限为模型分组新建权限Model Group New Permission。该接口是模型管理链路的基础操作——新建的模型对象必须归属于某个分类而系统内置分类不可修改因此为自定义模型建立独立分类是模型扩展的第一步。接口调用方式如下请求方法POST请求路径/api/v3/create/model/classification经 APIGateway 开放接口转发至 coreservice 服务在 coreservice 服务路由注册文件 中可以看到模型分类相关的完整 REST 路由均在此统一注册方法路径处理函数语义POST/create/model/classificationCreateOneModelClassification创建单条分类POST/createmany/model/classificationCreateManyModelClassification批量创建分类POST/set/model/classificationSetOneModelClassification存在则更新、不存在则创建单条POST/setmany/model/classificationSetManyModelClassification存在则更新、不存在则创建批量PUT/update/model/classificationUpdateModelClassification按条件更新分类DELETE/delete/model/classificationDeleteModelClassification按条件删除分类POST/read/model/classificationSearchModelClassification查询分类本文聚焦其中的创建场景即/create/model/classification。请求参数详解创建模型分类的请求体为 JSON 对象核心参数如下参数名类型必填说明bk_classification_idstring是分类 ID供系统内部使用的英文标识bk_classification_namestring是分类名称展示用通常为中文bk_classification_iconstring否模型分类图标参数约束与源码校验虽然接口文档只标注了三个字段但从 coreservice 创建实现 的源码可以提炼出三条关键校验规则bk_classification_id 必填若为空直接返回参数缺失错误CCErrCommParamsNeedSet提示信息指向bk_classification_id字段。禁止以bk或BK开头源码中显式校验strings.HasPrefix(strings.ToLower(ClassificationID), bk)一旦命中即返回bk_classification_id can not start with bk or BK。这是因为系统内置分类的 ID 均以bk为前缀见下文此规则用于防止自定义分类与后续创建的内置分类产生冲突。注释明确指出上层 topo server 也有此 ID 校验这里作为兜底防线防止绕过拦截直接调用 core service。唯一性约束落库时若触发 Mongo 唯一索引冲突会返回重复项错误CCErrCommDuplicateItem说明bk_classification_id在同一供应商supplier account下不可重复。系统内置分类参考在 metadata.Classification 定义文件 中定义了系统内置分类的 ID 与名称常量可作为自定义命名的避让清单内置 ID分类名称bk_host_manage主机管理bk_biz_topo业务拓扑bk_organization组织架构bk_network网络bk_uncategorized未分类bk_table_classification内置表格分类从源码结构看自定义分类的 ID 应避开上述值并遵守不以 bk 开头的约定例如使用cs_test、custom_asset等命名。请求示例以下是一个标准的创建请求 JSON内容取自接口文档并原样保留{ bk_classification_id: cs_test, bk_classification_name: test_name, bk_classification_icon: icon-cc-business }其中bk_classification_icon为可选字段用于指定该分组在界面中展示的图标标识例如icon-cc-business即代表业务类图标。响应示例与响应参数说明响应示例创建成功时返回如下 JSON原文示例仅修正缩进{ result: true, code: 0, data: { id: 11, bk_classification_id: cs_test, bk_classification_name: test_name, bk_classification_type: , bk_classification_icon: icon-cc-business, bk_supplier_account: }, message: success, permission: null }响应参数参数名类型说明resultbool请求是否成功。true成功false失败codeint错误码。0 表示成功0 表示失败messagestring请求失败时返回的错误信息permissionobject权限信息dataobject请求返回数据data 子字段参数名类型说明idint新增数据记录的 IDbk_classification_idstring分类 ID供系统内部使用的英文标识bk_classification_namestring分类名称bk_classification_iconstring模型分类图标bk_classification_typestring分类类型内置分类为 inner code自定义分类为空字符串bk_supplier_accountstring开发商账号需要特别说明的是响应中data的完整字段它正是 metadata.Classification 结构体 的 JSON 序列化结果包含id、bk_classification_id、bk_classification_name、bk_classification_type、bk_classification_icon、bk_supplier_account六个字段。其中bk_classification_type由系统维护内置分类写入inner code自定义分类为空字符串bk_supplier_account由服务端自动填充为当前请求的开发商账号二者均不需要调用方传入。源码级实现原理请求处理链路创建分类的完整调用链为APIGateway 开放接口 → coreservice HTTP 服务service/model.go 中的CreateOneModelClassification→ 核心业务层 core/model/classification.go 的CreateOneModelClassification。HTTP 服务层负责将请求体解码到metadata.CreateOneModelClassification结构体核心业务层则依次完成参数非空校验 →bk前缀保留字校验 → 填充OwnerID即bk_supplier_account取自当前请求上下文kit.SupplierAccount→ 调用save落库。数据落库流程底层落库逻辑位于 classification_crud.go通过mongodb.Client().NextSequence从 MongoDB 自增序列中取下一个 ID作为该分类的id将id与OwnerID写入分类结构体插入到cc_ObjClassification数据表对应常量BKTableNameObjClassification见 tablenames.go。因此响应中的data.id即自增序列生成的主键可用于后续更新、查询或删除操作。测试验证仓库在 model_classification_test.go 中提供了完整的 CRUD 集成测试TestClassificationCRUD覆盖 create / read / update / delete 全流程其中createOneClassification用例直接以POST http://127.0.0.1:3308/api/v3/create/model/classification验证创建接口并断言返回的Created.ID非 0queryClassification用例进一步验证按bk_classification_id查询后OwnerID、ClassificationID均非空。这些测试可作为理解接口行为与自建联调脚本的参考。实战建议与注意事项命名规范自定义分类的bk_classification_id务必使用清晰、稳定的英文标识如cs_test、asset_group严禁以bk/BK开头避免与系统内置分类冲突创建后可继续查询如需在业务系统中按 ID 检索该分类可调用/read/model/classification接口条件中使用bk_classification_id精确匹配测试用例中即采用此方式区分 create 与 set 语义create遇到重复 ID 会报错而set语义为存在即更新、不存在即创建幂等性更强适合初始化脚本场景分类删除约束删除分类前系统会校验该分类下是否已挂载模型存在模型时返回错误CCErrTopoObjectClassificationHasObject见 classification.go因此创建分类时应规划好模型归属避免空分类堆积权限要求调用该接口需具备模型分组新建权限接入方应通过 APIGateway 完成鉴权后调用。通过本文你可以完整掌握蓝鲸 CMDB 模型分类的创建接口用法、字段含义与底层实现机制从而安全地规划自定义模型分组并接入上层业务。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb API 实战create_biz_custom_field 创建业务自定义模型属性蓝鲸配置平台 bk cmdb API 实战create_biz_custom_field 创建业务自定义模型属性 本文基于蓝鲸配置平台bk cmdb开源仓后端企业应用运维蓝鲸配置平台bk-cmdb批量创建项目接口 batch_create_project 实战指南蓝鲸配置平台bk cmdb批量创建项目接口 batch_create_project 实战指南 本篇以 docs/apidoc/apigw/open/en/后端企业应用运维蓝鲸智云配置平台bk-cmdb批量创建模型实例关联关系接口实战指南蓝鲸智云配置平台bk cmdb批量创建模型实例关联关系接口实战指南 导读 本文以蓝鲸智云配置平台BlueKing CMDBbk cmdb开放 API后端企业应用运维上一篇MAA明日方舟一键日常助手安装部署完整教程三平台一次装通下一篇best-skills 快速上手教程3 步安装 SKILL.md让 AI Agent 自动调用技能告别手动复制 Prompt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
 上下文转换器注意力：动静态上下文融合增强特征表征，优化多尺度目标检)
