后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本篇指南面向需要调用蓝鲸智云配置平台bk-cmdbBlueKing CMDB OpenAPI 的开发者完整讲解「更新模型定义」接口PUT /api/v3/update/object/{id}的请求参数、调用示例、响应结构并结合仓库源码剖析其权限模型、校验流程与obj_sort_number排序规则帮助读者在二次开发、自动化运维与平台集成中正确、安全地使用该接口。接口概览「更新模型定义」是 bk-cmdb 中修改自定义对象模型Object / Model的标准接口对应权限为「模型编辑权限」。所谓模型Model即 CMDB 中的资源对象定义如主机、集群、模块以及用户自定义的业务对象每个模型归属于一个模型分组Classification。该接口通过模型 IDid定位目标模型可更新模型的分类归属、名称、ICON、前端坐标以及分组内排序序号等元信息。接口的开放网关定义位于 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml其中operationId: update_object即为该接口后端透传路径为PUT /api/v3/update/object/{id}。在源码层面该接口的调用链完整贯穿三层接入层apigw / topo_server路由PUT /update/object/{id}注册在 src/scene_server/topo_server/service/service_business_initfunc.go处理器为 Service.UpdateObject负责解析路径参数与请求体、启动事务业务逻辑层topo_server logicsobject.UpdateObject 负责参数合法性校验、分类存在性校验、生成审计日志并下发数据更新请求数据层coreservice先经 service.UpdateModel 反序列化metadata.UpdateOption再进入 modelManager.UpdateModel 与 modelManager.update 完成对 MongoDBcc_ObjDes表对象模型定义表的实际写入。请求方式与鉴权请求方法PUT请求路径/api/v3/update/object/{id}路径参数{id}为对象模型的 IDint 类型即下面输入参数表中的id字段两者指向同一模型。鉴权要求调用方需要具备模型编辑权限。在 IAM 权限解析层该路径由正则updateObjectLatestRegexp ^/api/v3/update/object/[0-9]/?$匹配见 src/ac/parser/topolatest.go并映射为meta.Model资源上的meta.Update动作同时把路径中的模型 ID 作为资源实例 ID见 src/ac/parser/topolatest.go。因此未授予对应模型编辑权限的账号调用时会返回权限校验失败。输入参数说明接口请求体为 JSON 对象完整参数如下参数名称参数类型必选描述idint否对象模型的ID作为更新操作的条件也通过 URL 路径传入modifierstring否本条数据的最后修改人员bk_classification_idstring是对象模型的分类ID只能用英文字母序列命名用于将模型移动/归属到某个模型分组bk_obj_namestring否对象模型的名字bk_obj_iconstring否对象模型的ICON信息用于前端显示取值参考模型图标集合例如icon-cc-business、icon-cc-defaultpositionjson object string否用于前端展示的坐标以 JSON 字符串形式传入obj_sort_numberint否对象模型在所属模型分组下的排序序号具体取值规则见下文「排序序号机制」参数与源码字段的对应关系可直接在 metadata.Object 结构体 中印证bk_classification_idModelFieldObjCls、bk_obj_nameModelFieldObjectName、bk_obj_iconModelFieldObjIcon、positionModelFieldPosition、obj_sort_numberModelFieldObjSortNumber均是该结构体的映射字段与请求参数一一对应。关于必选字段需要注意文档标注bk_classification_id为必选但从源码看update 支持“仅传递obj_sort_number、不传递bk_classification_id”的场景——此时系统默认在当前分组内调整排序updateSortNum 中有明确注释与实现。建议在实际调用时至少携带id与需要变更的字段保持请求最小化。调用示例以下请求将 ID 为 1 的模型更新到分类cc_test下并设置模型名称、ICON、前端坐标与排序序号{ id: 1, modifier: admin, bk_classification_id: cc_test, bk_obj_name: cc2_test_inst, bk_obj_icon: icon-cc-business, position:{\ff\:{\x\:-863,\y\:1}}, obj_sort_number: 1 }实际请求命令示意将{id}替换为目标模型 ID并携带网关鉴权所需的 headercurl -X PUT https://cmdb-host/api/v3/update/object/1 \ -H Content-Type: application/json \ -d { id: 1, modifier: admin, bk_classification_id: cc_test, bk_obj_name: cc2_test_inst, bk_obj_icon: icon-cc-business, position:{\ff\:{\x\:-863,\y\:1}}, obj_sort_number: 1 }说明示例中的position是序列化后的 JSON 字符串实际值需自行转义modifier仅为业务上记录修改人系统在落库时会用登录用户覆盖写入见下文「更新写入流程」。响应结构与状态码响应示例{ result: true, code: 0, message: success, permission: null, data: null }响应参数说明参数名称参数类型描述resultbool请求成功与否。true:请求成功false请求失败codeint错误编码。 0表示success0表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息本接口成功时为空dataobject无数据返回接口成功时data为空失败时通过非 0 的code与message描述错误原因。常见失败场景包括目标模型 ID 不存在、bk_classification_id对应的模型分组不存在返回CCErrorModelClassificationNotFound、bk_obj_name与其他模型重名返回重复项错误、obj_sort_number为负数返回参数非法等这些校验逻辑均可在 object.isValid、object.isClassificationValid 与 updateSortNum 中找到对应实现。更新写入流程详解从请求进入到数据落库后端依次执行以下关键步骤路径参数解析Service.UpdateObject从 URL 中解析id并转为 int64同时将请求体 JSON 反序列化为map[string]interface{}随后在事务中调用逻辑层UpdateObjectsrc/scene_server/topo_server/service/object.go合法性校验object.isValid校验模型名称字段、分类字段等更新场景下bk_obj_id不可变更随后isClassificationValid会向 coreservice 查询bk_classification_id对应的模型分组若不存在则直接报错src/scene_server/topo_server/logics/model/object.go不可变字段剔除更新前显式移除bk_obj_id与id字段防止通过请求体篡改模型标识src/scene_server/topo_server/logics/model/object.go审计日志生成更新前生成审计日志AuditUpdate若本次更新包含bk_ispaused模型停用/启用字段审计动作会对应切换为AuditPause/AuditResumesrc/scene_server/topo_server/logics/model/object.go调用 coreservice 落库以id为条件、请求体数据为内容调用UpdateModelsrc/scene_server/topo_server/logics/model/object.go数据最终进入 modelManager.update自动填充modifier覆盖为当前登录用户与last_time若更新了模型名称则进行重名校验若携带分类或排序字段则先重排obj_sort_number再更新主数据审计日志落库与 IAM 同步更新成功后保存审计日志若本次更新包含bk_obj_name且开启了鉴权能力还会将新名称同步到 IAM 视图src/scene_server/topo_server/service/object.go。其中 coreservice 对外的服务路由PUT /update/model注册于 src/source_controller/coreservice/service/service_initfunc.go客户端封装位于 src/apimachinery/coreservice/model/api.go可供二次开发时直接复用。排序序号机制obj_sort_numberobj_sort_number是本接口中行为最特殊的一个字段其核心规则如下原文已给出此处结合源码给出精确解释更新该值时当设置的值超过分组模型中该值的最大值则更新的值为最大值加一如设置的值为 999而当前分组模型中该值的最大值为 6则更新值设置为 7。底层实现位于 GetSortNum具体逻辑为新模型创建或未传obj_sort_number时取当前分组内最大值 1组内移动若目标序号小于原序号前移区间[目标, 原序号)内的模型序号 1若大于原序号后移区间(原序号, 目标]内的模型序号 -1再写入目标序号跨分组移动原分组中序号大于原序号的模型全部 -1补位目标分组中序号大于等于目标值的模型全部 1腾位随后写入目标序号越界兜底目标值超过当前分组最大值时自动收敛为“最大值 1”保证序号连续不重复。批量平移通过$inc操作完成updateOtherObjSort。另外删除模型时也会触发同类补位逻辑updateSortNumWhenDelete保证分组内排序始终连续src/source_controller/coreservice/core/model/model_crud.go。需要注意的是更新排序序号时会以请求体中的分类为基准判定是组内移动还是跨分组移动——若请求同时携带bk_classification_id则按“移动到该分组”处理并执行上述平移若只携带obj_sort_number则默认在当前分组内调整src/source_controller/coreservice/core/model/model_crud.go。obj_sort_number字段在较新版本中随升级脚本y3.12.202311061800被加入cc_ObjDes表add_sort_number_column.go升级时会按分类分组为存量模型从 1 开始补齐序号历史版本库请确认升级后再调用该字段。前端页面中的实际使用该接口并非只供 API 调用方使用CMDB 前端“模型管理”页面同样复用它实现模型编辑功能可作为接口语义的补充印证模型详情页保存模型名称、ICON、分组时直接调用updateObject且注释明确“改变分组就不传 sort默认放到最后”src/ui/src/views/model-manage/children/model-details/index.vue模型列表页拖拽调整分组顺序时携带bk_classification_id与新的obj_sort_number取当前索引调用updateObjectsrc/ui/src/views/model-manage/index.vue前端 API 封装位于 src/ui/src/store/modules/api/object-model.js即$http.put(update/object/${id}, params)。因此通过该接口更新模型时bk_obj_name、bk_obj_icon、bk_classification_id、obj_sort_number的组合使用方式与页面行为完全一致改名、换图标、移动分组、调整排序可一次性或分批完成。使用建议与注意事项权限先行该接口受“模型编辑权限”管控调用前确认账号已在 IAM 中具备目标模型按模型 ID 授权的编辑权限否则将返回权限错误id 定位唯一id是更新条件的唯一依据务必通过POST /api/v3/find/object查询模型接口确认目标模型 ID 后再发起更新避免误改分组名与名称规则bk_classification_id仅允许英文字母序列bk_obj_name更新时会做全局重名校验重名请求会被拒绝position 为字符串前端展示坐标以 JSON 字符串整体传入注意在请求体中正确转义双引号避免解析失败排序值注意越界语义obj_sort_number传值超过分组最大值时不会报错而是被自动收敛为“最大值 1”这是设计行为而非异常停用模型的补充能力接口还支持通过bk_ispaused字段对模型进行停用/启用并在审计日志中体现为暂停/恢复动作可用于模型生命周期管理。通过本文的接口参数、源码链路与排序机制解析开发者可以在蓝鲸智云配置平台中可靠地完成模型定义维护并为上层自动化脚本、配置同步工具与第三方系统集成提供稳定的模型元数据支撑。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云配置平台bk-cmdb更新服务模板接口 update_service_template 实战指南蓝鲸智云配置平台bk cmdb更新服务模板接口 update_service_template 实战指南 导读 本文聚焦蓝鲸智云配置平台bk cmdb提后端企业应用运维蓝鲸智云配置平台bk-cmdb模型分类删除接口 delete_classification 实战指南蓝鲸智云配置平台bk cmdb模型分类删除接口 delete_classification 实战指南 delete_classification 是蓝鲸智云后端企业应用运维蓝鲸配置平台bk-cmdb批量更新 Kubernetes Workload 接口实战指南蓝鲸配置平台bk cmdb批量更新 Kubernetes Workload 接口实战指南 导读 本文围绕 bk cmdb蓝鲸智云配置平台API 网关提供后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考