后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载蓝鲸智云配置平台bk-cmdb的更新业务自定义模型属性接口update_biz_custom_field用于修改业务bk_biz_id 非 0下的自定义字段定义是业务自定义字段编辑权限能力对应的开放 API。本文以官方 API 文档为主线结合仓库内网关资源定义、topo_server 服务实现、属性校验逻辑与前端调用代码系统讲解该接口的路径、参数、调用示例、响应格式及其底层实现原理帮助开发者准确完成业务自定义字段的增量更新与排查问题。接口概览路径、方法与权限该接口在蓝鲸 API 网关中的资源定义如下见 bk_apigw_resources_bk-cmdb.yaml项目内容网关操作 IDoperationIdupdate_biz_custom_field网关路径/api/v3/update/objectattr/biz/{bk_biz_id}/id/{id}HTTP 方法PUT后端转发路径/api/v3/update/objectattr/biz/{bk_biz_id}/id/{id}权限业务自定义字段编辑权限isPublic: false需申请权限allowApplyPermission: true限流插件bk-rate-limit默认100 tokens / 1 秒后端服务topo_server中注册了完全一致的路由PUT /update/objectattr/biz/{bk_biz_id}/id/{id}绑定到s.UpdateObjectAttribute处理函数见 service_business_initfunc.go。注意该接口仅适用于业务自定义字段即bk_biz_id为实际业务 ID 的字段与通用模型属性的更新接口PUT /update/objectattr/{id}不同。两者的区别在于业务自定义字段的bk_biz_id为真实业务 ID而其它模型字段的bk_biz_id为 0。输入参数详解路径参数参数名称类型必选描述bk_biz_idint是业务 id业务自定义字段归属的业务idint是目标数据字段属性的记录 ID请求体参数参数名称参数类型必选描述idint是目标数据的记录IDbk_biz_idint是业务iddescriptionstring否数据的描述信息isonlybool否表明唯一性isreadonlybool否表明是否只读isrequiredbool否表明是否必填bk_property_groupstring否字段分栏的名字optionobject否用户自定义内容存储的内容及格式由调用方决定, 以数字内容为例{min:1,max:2}bk_property_namestring否模型属性名用于展示unitstring否单位bk_property_typestring否定义的属性字段用于存储数据的数据类型singlechar(短字符),longchar(长字符),int(整形),enum(枚举类型),date(日期),time(时间),objuser(用户),enummulti(枚举多选),enumquote(枚举引用),timezone(时区),bool(布尔),organization(组织))placeholderstring否占位符bk_asst_obj_idstring否如果有关联其它的模型那么就必需设置此字段否则就不需要设置default随bk_property_type字段类型否默认值字段类型取值说明bk_property_type支持的类型常量在 definitions.go 中统一定义各类型含义如下取值含义singlechar短字符longchar长字符int整形enum枚举类型date日期time时间objuser用户enummulti枚举多选enumquote枚举引用timezone时区bool布尔organization组织关键参数补充说明option用户自定义内容格式由调用方决定。例如数字类型字段可传{min:1,max:2}用于约束取值范围枚举类型字段的option则用于定义枚举选项列表。后端会依据字段类型对option做合法性校验详见下文源码原理。default默认值其类型随bk_property_type变化传参时需与实际字段类型匹配。bk_asst_obj_id仅当字段需要关联其它模型时才必须设置否则无需设置。bk_property_group字段分栏名。值得注意在后端UpdateObjectAttribute处理中bk_property_group会被removeImmutableFields显式移除见 object_attribute.go即分栏归属无法通过该接口变更分栏调整应走属性分组相关接口。调用示例{ id: 1, bk_biz_id: 2, description: test, placeholder: test, unit: 1, isonly: false, isreadonly: false, isrequired: false, bk_property_group: default, option: {min: 1, max: 4}, bk_property_name: aaa, bk_property_type: int, bk_asst_obj_id: 0 }对应的完整 HTTP 请求形式为PUT /api/v3/update/objectattr/biz/2/id/1请求体中id1与路径中的id需要保持一致bk_biz_id2与路径中的{bk_biz_id}同理。实际调用时建议只传需要修改的字段接口按字段增量更新但id与bk_biz_id两个标识性参数必须携带。前端Vue通过$http.put(update/objectattr/biz/${bizId}/id/${id}, params, config)发起该请求封装于 object-model-property.js可供二次开发参考。响应说明响应示例{ result: true, code: 0, message: success, permission: null, data: null }响应参数说明参数名称参数类型描述resultbool请求成功与否。true:请求成功false请求失败codeint错误编码。 0表示success0表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataobject请求返回的数据更新成功后data为null业务自定义字段的完整属性结构data内容形态可参考创建接口 create_biz_custom_field.md 中的说明其属性对象包含bk_biz_id、bk_obj_id、bk_property_id、bk_property_name、bk_property_group、bk_property_index、unit、placeholder、editable、ispre、isrequired、isreadonly、isonly、bk_issystem、bk_isapi、bk_property_type、option、description、creator、create_time、last_time等字段。源码级原理一次更新请求的完整调用链1. 请求进入 topo_server 服务层PUT /api/v3/update/objectattr/biz/{bk_biz_id}/id/{id}命中 service_business_initfunc.go 注册的s.UpdateObjectAttribute。处理函数位于 object_attribute.go其核心流程将请求体解析为mapstr.MapStr通过getAttrIDAndBizID解析路径参数id与bk_biz_id若bk_biz_id为 0 直接报错业务自定义字段不允许业务 ID 为 0见 object_attribute.go若bk_property_type为innertable表格字段走updateObjectTableAttribute单独流程对普通字段调用removeImmutableFields移除bk_metadata、bk_biz_id、bk_property_index、bk_property_group即这些字段不可经此接口修改在AutoRunTxn事务中调用AttributeOperation().UpdateObjectAttribute成功后返回data: null。2. 逻辑层更新与三层校验事务内的核心实现是 attribute.go 的UpdateObjectAttribute依次执行数据合法性校验isValidattribute.go更新场景下若传了ismultiple会校验字段类型是否支持多选bk_property_id若传入需通过FieldTypeStrictCharRegexp正则校验且长度不超过AttributeIDMaxLength 128字符bk_property_name若传入长度不超过AttributeNameMaxLength 128字符按 rune 计数placeholder若传入长度不超过AttributePlaceHolderMaxLength 2000字符对enumquote枚举引用类型校验option中的目标模型与实例 ID 是否有效ValidObjIDAndInstID。可更新性校验canAttrsUpdateattribute.go若字段来自字段组合模板bk_template_id ! 0且本次不是模板同步操作isSyncfalse则仅允许更新isrequired、editable、placeholder三个字段且对应模板锁为false时才能更新否则返回CCErrCommModifyFieldForbidden错误。相关锁判定逻辑见 attribute.go。审计日志与落库更新前通过auditlog.NewObjectAttributeAuditLog生成审计日志操作类型AuditUpdate随后以{id: attID}为条件并追加业务维度条件调用 CoreService 的UpdateModelAttrsByCondition执行更新最后保存审计日志。3. 权限解析业务 ID 不可为 0在权限中心解析层topolatest.go该路径匹配正则^/api/v3/update/objectattr/biz/[0-9]/id/[0-9]/?$HTTP 方法为 PUT见 topolatest.go。解析逻辑同样强制要求路径中的业务 ID 不能为 0否则直接判定请求无效随后将资源动作解析为meta.ModelAttribute meta.Update并以attrID作为资源实例 ID交由权限中心按业务自定义字段编辑权限鉴权。实践建议与注意事项明确适用对象本接口只面向业务自定义字段bk_biz_id为实际业务 ID。创建接口create_biz_custom_field.md的注意点中明确指出业务自定义字段与其它模型字段的区别就是bk_biz_id是否为真实业务 id创建时bk_obj_id仅能为集群set、模块module和主机host。更新时同样应基于该前提操作。按需传参接口为增量更新语义除id、bk_biz_id外仅传入需要变更的字段即可避免误传导致意外覆盖。不可修改项bk_property_index、bk_property_group会被后端强制剔除传参不会生效字段类型变更需谨慎属性类型相关的深度校验发生在落库侧源码注释亦说明 option 的更新校验在 coreservice 侧完成因为需要从数据库读取字段类型。字段模板锁定若字段由字段组合模板下发bk_template_id非 0普通 API 更新将受模板锁限制仅isrequired、editable、placeholder且锁未启用时允许修改期望改动的其它属性需先在模板侧调整。权限申请该资源非公开资源isPublic: false调用方需在蓝鲸 API 网关申请业务自定义字段编辑权限且网关默认配置了每秒 100 token 的限流。失败排查响应中resultfalse时关注code错误编码0 表示成功0 表示失败与message错误信息常见的失败原因包括业务 ID 为 0、属性名/占位符超长、模板锁定字段被修改、option与字段类型不匹配等均可结合上述校验逻辑快速定位。相关资源索引API 文档原文update_biz_custom_field.md创建业务自定义字段create_biz_custom_field.md网关资源定义含限流与鉴权配置bk_apigw_resources_bk-cmdb.yaml路由注册service_business_initfunc.go服务层处理逻辑object_attribute.go逻辑层更新与校验attribute.go属性数据结构定义attribute.go字段类型常量与长度限制definitions.go前端封装object-model-property.js赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 BK-CMDB 业务集业务查询接口 list_business_in_business_set 实战指南蓝鲸配置平台 BK CMDB 业务集业务查询接口 list_business_in_business_set 实战指南 本指南围绕蓝鲸智云配置平台BlueKi后端企业应用运维蓝鲸智云配置平台bk-cmdb更新服务模板接口 update_service_template 实战指南蓝鲸智云配置平台bk cmdb更新服务模板接口 update_service_template 实战指南 导读 本文聚焦蓝鲸智云配置平台bk cmdb提后端企业应用运维蓝鲸配置平台bk-cmdb批量更新 Kubernetes Workload 接口实战指南蓝鲸配置平台bk cmdb批量更新 Kubernetes Workload 接口实战指南 导读 本文围绕 bk cmdb蓝鲸智云配置平台API 网关提供后端企业应用运维上一篇cann/mat-chem-sim-pred Lennard-Jones力场融合算子下一篇终极指南Android Sunflower项目中的依赖版本管理工具比较创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/13 6:06:16 · 阅读 1.2k 蓝鲸配置平台 bk-cmdb 更新业务自定义字段接口（update_biz_custom_field）完整指南
后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载蓝鲸智云配置平台bk-cmdb的更新业务自定义模型属性接口update_biz_custom_field用于修改业务bk_biz_id 非 0下的自定义字段定义是业务自定义字段编辑权限能力对应的开放 API。本文以官方 API 文档为主线结合仓库内网关资源定义、topo_server 服务实现、属性校验逻辑与前端调用代码系统讲解该接口的路径、参数、调用示例、响应格式及其底层实现原理帮助开发者准确完成业务自定义字段的增量更新与排查问题。接口概览路径、方法与权限该接口在蓝鲸 API 网关中的资源定义如下见 bk_apigw_resources_bk-cmdb.yaml项目内容网关操作 IDoperationIdupdate_biz_custom_field网关路径/api/v3/update/objectattr/biz/{bk_biz_id}/id/{id}HTTP 方法PUT后端转发路径/api/v3/update/objectattr/biz/{bk_biz_id}/id/{id}权限业务自定义字段编辑权限isPublic: false需申请权限allowApplyPermission: true限流插件bk-rate-limit默认100 tokens / 1 秒后端服务topo_server中注册了完全一致的路由PUT /update/objectattr/biz/{bk_biz_id}/id/{id}绑定到s.UpdateObjectAttribute处理函数见 service_business_initfunc.go。注意该接口仅适用于业务自定义字段即bk_biz_id为实际业务 ID 的字段与通用模型属性的更新接口PUT /update/objectattr/{id}不同。两者的区别在于业务自定义字段的bk_biz_id为真实业务 ID而其它模型字段的bk_biz_id为 0。输入参数详解路径参数参数名称类型必选描述bk_biz_idint是业务 id业务自定义字段归属的业务idint是目标数据字段属性的记录 ID请求体参数参数名称参数类型必选描述idint是目标数据的记录IDbk_biz_idint是业务iddescriptionstring否数据的描述信息isonlybool否表明唯一性isreadonlybool否表明是否只读isrequiredbool否表明是否必填bk_property_groupstring否字段分栏的名字optionobject否用户自定义内容存储的内容及格式由调用方决定, 以数字内容为例{min:1,max:2}bk_property_namestring否模型属性名用于展示unitstring否单位bk_property_typestring否定义的属性字段用于存储数据的数据类型singlechar(短字符),longchar(长字符),int(整形),enum(枚举类型),date(日期),time(时间),objuser(用户),enummulti(枚举多选),enumquote(枚举引用),timezone(时区),bool(布尔),organization(组织))placeholderstring否占位符bk_asst_obj_idstring否如果有关联其它的模型那么就必需设置此字段否则就不需要设置default随bk_property_type字段类型否默认值字段类型取值说明bk_property_type支持的类型常量在 definitions.go 中统一定义各类型含义如下取值含义singlechar短字符longchar长字符int整形enum枚举类型date日期time时间objuser用户enummulti枚举多选enumquote枚举引用timezone时区bool布尔organization组织关键参数补充说明option用户自定义内容格式由调用方决定。例如数字类型字段可传{min:1,max:2}用于约束取值范围枚举类型字段的option则用于定义枚举选项列表。后端会依据字段类型对option做合法性校验详见下文源码原理。default默认值其类型随bk_property_type变化传参时需与实际字段类型匹配。bk_asst_obj_id仅当字段需要关联其它模型时才必须设置否则无需设置。bk_property_group字段分栏名。值得注意在后端UpdateObjectAttribute处理中bk_property_group会被removeImmutableFields显式移除见 object_attribute.go即分栏归属无法通过该接口变更分栏调整应走属性分组相关接口。调用示例{ id: 1, bk_biz_id: 2, description: test, placeholder: test, unit: 1, isonly: false, isreadonly: false, isrequired: false, bk_property_group: default, option: {min: 1, max: 4}, bk_property_name: aaa, bk_property_type: int, bk_asst_obj_id: 0 }对应的完整 HTTP 请求形式为PUT /api/v3/update/objectattr/biz/2/id/1请求体中id1与路径中的id需要保持一致bk_biz_id2与路径中的{bk_biz_id}同理。实际调用时建议只传需要修改的字段接口按字段增量更新但id与bk_biz_id两个标识性参数必须携带。前端Vue通过$http.put(update/objectattr/biz/${bizId}/id/${id}, params, config)发起该请求封装于 object-model-property.js可供二次开发参考。响应说明响应示例{ result: true, code: 0, message: success, permission: null, data: null }响应参数说明参数名称参数类型描述resultbool请求成功与否。true:请求成功false请求失败codeint错误编码。 0表示success0表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataobject请求返回的数据更新成功后data为null业务自定义字段的完整属性结构data内容形态可参考创建接口 create_biz_custom_field.md 中的说明其属性对象包含bk_biz_id、bk_obj_id、bk_property_id、bk_property_name、bk_property_group、bk_property_index、unit、placeholder、editable、ispre、isrequired、isreadonly、isonly、bk_issystem、bk_isapi、bk_property_type、option、description、creator、create_time、last_time等字段。源码级原理一次更新请求的完整调用链1. 请求进入 topo_server 服务层PUT /api/v3/update/objectattr/biz/{bk_biz_id}/id/{id}命中 service_business_initfunc.go 注册的s.UpdateObjectAttribute。处理函数位于 object_attribute.go其核心流程将请求体解析为mapstr.MapStr通过getAttrIDAndBizID解析路径参数id与bk_biz_id若bk_biz_id为 0 直接报错业务自定义字段不允许业务 ID 为 0见 object_attribute.go若bk_property_type为innertable表格字段走updateObjectTableAttribute单独流程对普通字段调用removeImmutableFields移除bk_metadata、bk_biz_id、bk_property_index、bk_property_group即这些字段不可经此接口修改在AutoRunTxn事务中调用AttributeOperation().UpdateObjectAttribute成功后返回data: null。2. 逻辑层更新与三层校验事务内的核心实现是 attribute.go 的UpdateObjectAttribute依次执行数据合法性校验isValidattribute.go更新场景下若传了ismultiple会校验字段类型是否支持多选bk_property_id若传入需通过FieldTypeStrictCharRegexp正则校验且长度不超过AttributeIDMaxLength 128字符bk_property_name若传入长度不超过AttributeNameMaxLength 128字符按 rune 计数placeholder若传入长度不超过AttributePlaceHolderMaxLength 2000字符对enumquote枚举引用类型校验option中的目标模型与实例 ID 是否有效ValidObjIDAndInstID。可更新性校验canAttrsUpdateattribute.go若字段来自字段组合模板bk_template_id ! 0且本次不是模板同步操作isSyncfalse则仅允许更新isrequired、editable、placeholder三个字段且对应模板锁为false时才能更新否则返回CCErrCommModifyFieldForbidden错误。相关锁判定逻辑见 attribute.go。审计日志与落库更新前通过auditlog.NewObjectAttributeAuditLog生成审计日志操作类型AuditUpdate随后以{id: attID}为条件并追加业务维度条件调用 CoreService 的UpdateModelAttrsByCondition执行更新最后保存审计日志。3. 权限解析业务 ID 不可为 0在权限中心解析层topolatest.go该路径匹配正则^/api/v3/update/objectattr/biz/[0-9]/id/[0-9]/?$HTTP 方法为 PUT见 topolatest.go。解析逻辑同样强制要求路径中的业务 ID 不能为 0否则直接判定请求无效随后将资源动作解析为meta.ModelAttribute meta.Update并以attrID作为资源实例 ID交由权限中心按业务自定义字段编辑权限鉴权。实践建议与注意事项明确适用对象本接口只面向业务自定义字段bk_biz_id为实际业务 ID。创建接口create_biz_custom_field.md的注意点中明确指出业务自定义字段与其它模型字段的区别就是bk_biz_id是否为真实业务 id创建时bk_obj_id仅能为集群set、模块module和主机host。更新时同样应基于该前提操作。按需传参接口为增量更新语义除id、bk_biz_id外仅传入需要变更的字段即可避免误传导致意外覆盖。不可修改项bk_property_index、bk_property_group会被后端强制剔除传参不会生效字段类型变更需谨慎属性类型相关的深度校验发生在落库侧源码注释亦说明 option 的更新校验在 coreservice 侧完成因为需要从数据库读取字段类型。字段模板锁定若字段由字段组合模板下发bk_template_id非 0普通 API 更新将受模板锁限制仅isrequired、editable、placeholder且锁未启用时允许修改期望改动的其它属性需先在模板侧调整。权限申请该资源非公开资源isPublic: false调用方需在蓝鲸 API 网关申请业务自定义字段编辑权限且网关默认配置了每秒 100 token 的限流。失败排查响应中resultfalse时关注code错误编码0 表示成功0 表示失败与message错误信息常见的失败原因包括业务 ID 为 0、属性名/占位符超长、模板锁定字段被修改、option与字段类型不匹配等均可结合上述校验逻辑快速定位。相关资源索引API 文档原文update_biz_custom_field.md创建业务自定义字段create_biz_custom_field.md网关资源定义含限流与鉴权配置bk_apigw_resources_bk-cmdb.yaml路由注册service_business_initfunc.go服务层处理逻辑object_attribute.go逻辑层更新与校验attribute.go属性数据结构定义attribute.go字段类型常量与长度限制definitions.go前端封装object-model-property.js赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 BK-CMDB 业务集业务查询接口 list_business_in_business_set 实战指南蓝鲸配置平台 BK CMDB 业务集业务查询接口 list_business_in_business_set 实战指南 本指南围绕蓝鲸智云配置平台BlueKi后端企业应用运维蓝鲸智云配置平台bk-cmdb更新服务模板接口 update_service_template 实战指南蓝鲸智云配置平台bk cmdb更新服务模板接口 update_service_template 实战指南 导读 本文聚焦蓝鲸智云配置平台bk cmdb提后端企业应用运维蓝鲸配置平台bk-cmdb批量更新 Kubernetes Workload 接口实战指南蓝鲸配置平台bk cmdb批量更新 Kubernetes Workload 接口实战指南 导读 本文围绕 bk cmdb蓝鲸智云配置平台API 网关提供后端企业应用运维上一篇cann/mat-chem-sim-pred Lennard-Jones力场融合算子下一篇终极指南Android Sunflower项目中的依赖版本管理工具比较创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考