后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读在蓝鲸智云配置平台BlueKing CMDB中模型引用Model Quote机制允许源模型通过表格类型属性引用一张派生子表例如主机模型通过disk属性引用磁盘表。当需要一次性修改多条被引用实例时可调用batch_update_quoted_inst接口v3.10.30 引入。本文以 docs/apidoc/apigw/open/zh/batch_update_quoted_inst.md 为主干结合仓库源码梳理该接口的请求参数、调用示例、响应结构以及底层的路由注册、参数校验、权限与审计实现帮助读者正确、安全地批量更新被引用模型实例。接口概述功能定位batch_update_quoted_inst用于批量更新被引用的模型的实例即批量修改源模型通过表格属性引用出的子模型中的多条实例记录。它需要以下前置条件版本要求v3.10.30 及以上版本权限要求调用者需要具备源模型实例的编辑权限。从源码结构看被引用模型的实例管理与普通模型实例走的是独立链路拓扑服务topo_server负责接入层鉴权与审计核心服务coreservice负责真正的数据读写二者通过ModelQuote()客户端桥接相关代码位于 src/scene_server/topo_server/service/quoted_instance.go 与 src/source_controller/coreservice/service/model_quote/quoted_inst.go。模型引用的数据模型被引用模型与源模型的关联关系记录在ModelQuoteRelation结构中见 src/common/metadata/model_quote.goDestModel派生出的子模型即被引用模型例如bk_host_diskSrcModel源模型例如主机模型hostPropertyID源模型上引用该子模型的属性 ID例如diskType引用类型如表格table。生成被引用模型对象 ID 的规则为bk_ 源模型 # 属性ID对应源码函数GenerateModelQuoteObjID(srcModel, propertyID)。这解释了为什么接口入参必须同时提供bk_obj_id与bk_property_id二者共同定位到唯一的被引用模型及其表。输入参数详解接口请求体为 JSON 对象各参数说明如下与原文档保持完全一致并补充源码校验细节参数名称参数类型必选描述bk_obj_idstring是源模型 IDbk_property_idstring是源模型引用该模型的属性 IDidsint64 array是需要更新的实例 ID 数组最多不能超过 500 个dataobject是需要更新的实例信息data 字段说明data为待更新的字段集合其字段由被引用模型的属性定义决定并非固定结构。原文档中的name、operator、description仅为示例字段参数名称参数类型必选描述namestringdata 中至少一个字段必填名称此处仅为示例实际字段由模型属性决定operatorstringdata 中至少一个字段必填维护人此处仅为示例实际字段由模型属性决定descriptionstringdata 中至少一个字段必填描述此处仅为示例实际字段由模型属性决定提示data中的多个字段是批量应用于ids指定的全部实例即这些实例会统一被设置为相同值。若需要对不同实例设置不同字段值应拆分为多次调用。源码层的参数校验逻辑服务端对入参的校验可在 src/common/metadata/model_quote.go 的BatchUpdateQuotedInstOption.Validate()中看到它与接口文档互为印证bk_obj_id为空 → 报参数缺失bk_property_id为空 → 报参数缺失ids为空数组 → 报参数缺失ids数量超过common.BKMaxWriteOpLimit200→ 报参数缺失错误此处注意文档上限 500 与常量定义存在差异源码中BKMaxWriteOpLimit 200见 src/common/definitions.go实际以服务端校验为准data为空对象 → 报参数缺失。此外拓扑服务层还会做二次校验src/scene_server/topo_server/service/quoted_instance.go通过ModelQuoteOperation().GetQuotedObjID根据bk_obj_idbk_property_id查询ModelQuoteRelation定位被引用模型对象 ID实现见 src/scene_server/topo_server/logics/model_quote/model_quote.go用filtertools.GenAtomFilter(common.BKFieldID, filter.In, opt.IDs)构造ID 属于 ids 集合的过滤条件先查出待更新实例的原始快照用于后续鉴权与审计。调用示例以下为原文档提供的完整调用示例{ bk_obj_id: host, bk_property_id: disk, ids: [ 1, 2 ], data: { name: test, operator: user, description: test instance } }该示例的含义将主机host模型通过disk属性引用的磁盘实例中 ID 为 1、2 的两条记录统一更新为nametest、operatoruser、descriptiontest instance。响应结构与示例响应示例{ result: true, code: 0, message: success, permission: null, data: null }响应参数说明参数名称参数类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataobject请求返回的数据更新成功时data返回null这一点与批量创建接口batch_create_quoted_inst不同——创建接口的data.ids会返回新实例 ID 数组可参见 docs/apidoc/apigw/open/zh/batch_create_quoted_inst.md而批量删除接口同样返回data: null见 docs/apidoc/apigw/open/zh/batch_delete_quoted_inst.md。底层调用链与实现原理路由注册该接口的 HTTP 路由在拓扑服务的initModelQuote中注册src/scene_server/topo_server/service/service_model_quote_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodPut, Path: /updatemany/quoted/instance, Handler: s.BatchUpdateQuotedInstance})即完整 API 路径为PUT /api/v3/updatemany/quoted/instance权限点在 src/ac/parser/model_quote.go 中登记为BatchUpdateQuotedInstance/ 更新引用模型实例。服务端处理流程拓扑服务层的BatchUpdateQuotedInstancesrc/scene_server/topo_server/service/quoted_instance.go执行步骤如下解析并校验请求体cts.DecodeInto(opt)反序列化为BatchUpdateQuotedInstOption并执行Validate()定位被引用模型调用GetQuotedObjID从关系表取出DestModel查询实例快照按ids构造filter.In条件查询现有实例limit 为BKMaxPageSize用于后续鉴权与审计日志生成鉴权通过authorizeQuotedInstance调用AuthManager.AuthorizeByInstanceID(..., meta.Update, objID, instIDs...)对被引用实例做更新授权源码注释表明当前复用了源模型实例的更新动作进行鉴权生成审计日志使用auditlog.NewQuotedInstAuditLog生成AuditUpdate类型的操作审计实现见 src/common/auditlog/quoted_inst.go记录变更前后的字段内容事务内更新在AutoRunTxn事务中调用CoreService().ModelQuote().BatchUpdateQuotedInstance真正写库并在同一事务内保存审计日志保证数据与审计的一致性响应成功则返回data: null。核心数据层实现核心服务层coreservice的BatchUpdateQuotedInstancesrc/source_controller/coreservice/service/model_quote/quoted_inst.go完成最终写库解析CommonUpdateOption包含过滤条件与data执行Validate()取路径参数bk_obj_id通过common.GetInstTableName(objID, supplierAccount)计算被引用模型的 MongoDB 表名调用validateUpdateQuotedInst逐字段校验细节见 src/source_controller/coreservice/service/model_quote/quoted_inst_validate.go过滤掉bk_inst_id、bk_field_id等主键/关联字段不允许通过该接口修改仅保留被引用模型属性表中真实存在且IsEditable为 true 的字段其余字段被静默删除对字符串值做TrimSpace去空格并调用属性的Validate做类型/枚举/必填等校验将过滤条件SetModOwner加上供应商账号多租户数据隔离并把last_time更新为当前时间执行mongodb.Client().Table(table).Update(ctx, filter, data)批量更新若命中唯一键冲突返回重复项错误否则返回RespEntity(nil)。客户端调用封装若通过 Go SDK 调用可使用 src/apimachinery/apiserver/model_quote/instance.go 中提供的封装err : quoteClient.BatchUpdateQuotedInstance(ctx, header, metadata.BatchUpdateQuotedInstOption{ ObjID: host, PropertyID: disk, IDs: []uint64{1, 2}, Data: mapstr.MapStr{name: test}, })客户端内部以PUT /updatemany/quoted/instance请求并统一解析BaseResp出错时返回errors.CCHttpError或业务错误码。测试用例佐证仓库集成测试 src/test/topo_server/model_quote_test.go 覆盖了更新场景正常更新构造BatchUpdateQuotedInstOption含ObjID、PropertyID、IDs、Data调用BatchUpdateQuotedInstance断言不报错异常场景PropertyID设置为不存在的prop_no_exist断言调用报错——对应源码中GetQuotedObjID查询关系表无结果时返回参数非法错误。这为接口行为提供了可复现的验证路径。使用注意事项权限前置接口要求源模型实例的编辑权限权限校验失败时响应中permission字段会携带所需权限信息数量上限ids数组不能超过文档所述 500 个且实际服务端校验以BKMaxWriteOpLimit源码中为 200为准批量过大时应分批调用字段白名单data中非被引用模型属性、或不可编辑IsEditablefalse的字段会被忽略bk_inst_id等关联字段不可通过本接口修改整体覆盖语义data中的所有字段会统一写入ids指定的所有实例请确认业务上允许这些实例拥有相同的更新值审计可追溯更新会写入操作审计QuotedInst 类型AuditUpdate动作变更记录可在平台审计中心查询原子性更新与审计日志在同一事务内提交任一环节失败都会整体回滚不会出现数据已改、审计缺失的不一致状态。关联文档如需了解被引用模型实例的完整操作闭环可配合阅读同一目录下的关联接口文档批量创建docs/apidoc/apigw/open/zh/batch_create_quoted_inst.md查询列表docs/apidoc/apigw/open/zh/list_quoted_inst.md批量删除docs/apidoc/apigw/open/zh/batch_delete_quoted_inst.md结合这三篇文档与上文源码分析即可完整掌握被引用模型实例从创建、查询、批量更新到删除的整个 API 使用链路。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 批量更新引用模型实例batch_update_quoted_inst接口实战详解蓝鲸 CMDB 批量更新引用模型实例batch_update_quoted_inst接口实战详解 本文以仓库文档 docs/apidoc/apigw/ope后端企业应用运维蓝鲸配置平台 bk-cmdb 开放接口实战批量更新进程实例update_process_instance蓝鲸配置平台 bk cmdb 开放接口实战批量更新进程实例update_process_instance 本篇文章以 update_process_ins后端企业应用运维蓝鲸配置平台bk-cmdb批量更新 Kubernetes Workload 接口实战指南蓝鲸配置平台bk cmdb批量更新 Kubernetes Workload 接口实战指南 导读 本文围绕 bk cmdb蓝鲸智云配置平台API 网关提供后端企业应用运维上一篇终极指南3步让你的老款Mac焕发新生免费安装最新macOS系统下一篇深度解析如何用mootdx构建高效通达信金融数据处理系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考