企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

本文面向需要调用蓝鲸智云配置平台（BlueKing CMDB）开放接口的开发者与运维工程师，系统讲解「更新动态分组」接口（update_dynamic_group）的完整调用方式：从请求参数结构、锁定条件（condition）与可变条件（variable_condition）的语义差异，到操作符合法性约束、完整请求/返回示例，再到 host_server 与 coreservice 两层源码实现与事务、审计细节。读完本文，你将能够准确构造更新动态分组的请求报文，理解参数校验规则与常见失败原因，并可在实际项目中安全地通过该接口维护 CMDB 动态分组。

一、接口概览：功能、版本与权限

「更新动态分组」是 CMDB 开放平台（OpenAPI/ESB）提供的一组动态分组管理能力之一，用于修改指定业务下已创建的动态分组。

从网关定义文件 docs/apidoc/cc/cc.yaml 可以看到，该接口使用generic.v2.cc.cc_component组件，suggest_method为POST（ESB 侧统一使用 POST 包裹），实际转发到 CMDB 内部时使用PUT方法访问/dynamicgroup/{bk_biz_id}/{id}：

- path: /v2/cc/update_dynamic_group/ name: update_dynamic_group label: 更新动态分组 suggest_method: POST api_type: operate comp_codename: generic.v2.cc.cc_component dest_path: /api/v3/dynamicgroup/{bk_biz_id}/{id} dest_http_method: PUT

与之配套的接口还包括创建（create_dynamic_group）、查询指定（get_dynamic_group）、搜索（search_dynamic_group）、删除（delete_dynamic_group）与执行（execute_dynamic_group），更新接口是其中修改分组定义的核心入口。

二、请求参数详解

2.1 公共请求参数（common_args_desc）

所有 CMDB 开放接口都需携带一组公共参数，用于 ESB 鉴权与用户身份识别，典型的公共参数包括：

2.2 接口专属参数

几点重要约定（均可在源码中得到验证）：

• bk_biz_id与id为定位动态分组的必要条件，二者在服务端组成过滤条件{bk_biz_id: bizID, id: targetID}后再更新数据库记录；
• bk_obj_id、info、name三者均为「按需更新」的可选字段，但存在联动约束（见 2.4 节）；
• bk_obj_id决定该动态分组未来执行时筛选的对象类型：host类型动态分组执行后返回主机，set类型动态分组执行后返回集群。

2.3 info：动态分组的规则结构

info是动态分组的核心规则载体，包含两类条件：

• 锁定条件（condition）：写入分组定义后固定不变的筛选条件，任何一次执行动态分组时都会被应用；
• 可变条件（variable_condition）：允许在执行动态分组时通过ExecuteOption.VariableCondition动态覆盖或追加的条件，为同一分组在不同场景复用提供了灵活性。

condition与variable_condition内部结构完全一致，均为「条件对象数组」，每个条件对象结构如下：

其中每个字段级查询条件（info.condition.condition）由三要素组成：

2.4 更新参数的联动约束（来自 host_server 源码）

在 src/scene_server/host_server/service/dynamic_grouping.go 的updateGroupParamCheck方法中，实现了严格的参数联动校验：

1. 更新info必须同时携带bk_obj_id：仅传info而不传bk_obj_id时直接报错bk_obj_id is required in update info condition action；
2. 更新bk_obj_id必须同时携带info：仅传bk_obj_id而不传info时同样报错info.condition is required in update bk_obj_id action；
3. 至少提供一项可更新内容：若info、bk_obj_id、name均未提供，会报错empty update content；
4. 最终只有bk_obj_id、info、name三个字段会被写入updates集合，其他传入字段被忽略。

因此，文档中「更新规则时需同时提供bk_obj_id和info」的说明，本质上是上述第 1、2 条联动约束的直接体现。

三、操作符与条件对象的合法范围（源码级约束）

动态分组的条件校验集中在 src/common/metadata/dynamic_grouping.go，理解这些约束能显著减少请求被拒的概率。

3.1 条件对象类型白名单

DynamicGroupConditionTypes = map[string]map[string]string{ // host 动态分组：支持对 set、module、host 三类对象设置条件 common.BKInnerObjIDHost: { common.BKInnerObjIDSet: common.BKInnerObjIDSet, common.BKInnerObjIDModule: common.BKInnerObjIDModule, common.BKInnerObjIDHost: common.BKInnerObjIDHost, }, // set 动态分组：仅支持对 set 对象设置条件 common.BKInnerObjIDSet: { common.BKInnerObjIDSet: common.BKInnerObjIDSet, }, }

即：host动态分组的info.condition/info.variable_condition中，bk_obj_id只能是set、module、host三者之一；set动态分组则只允许set。超出白名单会报not support condition type[%s] for %s dynamic group。

3.2 操作符全集

代码中定义的操作符常量包括：

注意：API 文档表格列出的是$eq / $ne / $in / $nin / $regex五个核心操作符；从源码看，系统还支持$lte、$gte以及contains、contains_sensitive，使用时以上述白名单为准。

3.3 操作符与字段类型/字段名的约束

DynamicGroupCondition.Validate方法按字段类型对操作符做二次约束：

• 布尔（bool）字段：仅支持$eq；
• 日期（date）字段：仅支持$gte、$lte，且值必须为字符串；
• $regex（模糊匹配）：仅支持字符串类型字段，且值必须可编译为合法正则（VerifyRegexValidity会调用regexp.Compile校验，非法正则直接拒绝）；
• $in/$nin：值必须是数组（[]interface{}），数组内每个元素类型需与字段类型匹配；
• $lte/$gte：仅支持数值类型字段；
• 服务模板字段（bk_service_template_id）：仅支持$in操作符；
• 字段本身必须在目标对象已定义的属性中，否则报not support condition field。

3.4 值类型与字段类型映射

代码将 CMDB 属性类型归并为四类，并据此校验value的类型：

此外，同一条件对象内锁定条件与可变条件之间、以及多个条件对象之间的字段不允许重复设置，重复时报cannot set the same field。

四、完整请求参数示例

以下示例完整继承了原文档的请求报文（含公共参数、业务 ID、分组 ID、名称、锁定条件与可变条件），展示了host类型动态分组同时更新规则与名称的典型用法：

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_biz_id": 1, "id": "XXXXXXXX", "bk_obj_id": "host", "name": "my-dynamic-group", "info": { "condition":[ { "bk_obj_id":"set", "condition":[ { "field":"default", "operator":"$ne", "value":1 } ] }, { "bk_obj_id":"module", "condition":[ { "field":"default", "operator":"$ne", "value":1 } ] }, { "bk_obj_id":"host", "condition":[ { "field":"bk_host_innerip", "operator":"$eq", "value":"127.0.0.1" } ] } ], "variable_condition":[ { "bk_obj_id":"set", "condition":[ { "field":"bk_parent_id", "operator":"$ne", "value":1 } ] }, { "bk_obj_id":"module", "condition":[ { "field":"bk_parent_id", "operator":"$ne", "value":1 } ] }, { "bk_obj_id":"host", "condition":[ { "field":"bk_host_outerip", "operator":"$eq", "value":"127.0.0.1" } ] } ] } }

示例要点解读：

• 锁定条件（condition）通过set、module、host三层对象共同圈定目标主机：非默认集群（default $ne 1）、非默认模块、且内网 IP 为127.0.0.1；
• 可变条件（variable_condition）给出执行时可替换的默认值：bk_parent_id非 1、外网 IP 为127.0.0.1。执行接口（execute_dynamic_group）可通过variable_condition覆盖这些值，实现同一分组在不同场景下复用；
• 由于info与bk_obj_id同时提供，符合「更新规则需同时提供二者」的联动约束；
• field: "default"是 CMDB 内置字段，用于标记集群/模块是否为默认对象，校验逻辑中对该字段不做属性存在性检查（if c.Field == common.BKDefaultField { return nil }）。

五、返回结果示例与参数说明

5.1 返回结果示例

更新成功后返回如下报文（data为空对象）：

{ "result": true, "code": 0, "message": "", "permission": null, "request_id": "e43da4ef221746868dc4c837d36f3807", "data": {} }

5.2 返回参数说明

六、更新接口的源码级实现链路

6.1 一次更新的完整调用链

以「更新规则 + 名称」为例，一次更新的调用链为：

ESB 网关 (/v2/cc/update_dynamic_group/) → host_server PUT /api/v3/dynamicgroup/{bk_biz_id}/{id} → hostServer.UpdateDynamicGroup (src/scene_server/host_server/service/dynamic_grouping.go) → 事务 AutoRunTxn：先写审计日志，再调用 coreservice → coreservice PUT /update/dynamicgroup/{bk_biz_id}/{id} → coreService.UpdateDynamicGroup (src/source_controller/coreservice/service/dynamic_grouping.go) → 更新 MongoDB 表 cc_DynamicGroup

host_server 侧的路由注册见 src/scene_server/host_server/service/service_initfunc.go：

utility.AddHandler(rest.Action{ Verb: http.MethodPut, Path: "/dynamicgroup/{bk_biz_id}/{id}", Handler: s.UpdateDynamicGroup, })

客户端封装（ESB 网关 → CMDB 内部的 HTTP 调用）见 src/apimachinery/coreservice/host/api.go，其最终 PUT 到/update/dynamicgroup/{bk_biz_id}/{id}。

6.2 host_server：参数检查 + 事务 + 审计

在 src/scene_server/host_server/service/dynamic_grouping.go 的UpdateDynamicGroup中：

1. 从路径参数解析bk_biz_id与id（bk_biz_id非法时返回CCErrCommParamsIsInvalid）；
2. updateGroupParamCheck完成 2.4 节所述的联动校验，并把合法字段放入updates；
3. 通过AutoRunTxn开启事务，事务内先使用NewDynamicGroupAuditLog(...).GenerateAuditLog(...)生成并保存审计日志（操作类型为AuditUpdate，见 src/common/auditlog/dynamic_grouping.go），再调用CoreService().Host().UpdateDynamicGroup落库；任一步失败则事务整体回滚。

6.3 coreservice：真实落库

coreservice 的UpdateDynamicGroup（见 src/source_controller/coreservice/service/dynamic_grouping.go）实现非常轻量：

data["modify_user"] = httpheader.GetUser(ctx.Kit.Header) data[common.LastTimeField] = time.Now().UTC() filter := common.KvMap{common.BKAppIDField: bizIDUint64, common.BKFieldID: targetID} err = mongodb.Client().Table(common.BKTableNameDynamicGroup).Update(ctx.Kit.Ctx, filter, data)

即：按bk_biz_id + id定位记录，将请求中携带的字段写入数据表，同时自动覆写modify_user（取自请求头中的用户）与last_time（UTC 当前时间）。DynamicGroup完整数据结构（bk_biz_id、id、name、bk_obj_id、info、create_user、modify_user、create_time、last_time）定义在 src/common/metadata/dynamic_grouping.go。

6.4 更新后的使用建议

更新动态分组不会立刻影响已查询出的数据，而是作用于下一次执行：

• 通过「执行动态分组」接口（POST /api/v3/dynamicgroup/data/{bk_biz_id}/{id}）按最新规则重新拉取匹配的主机或集群；
• 通过「查询指定动态分组」接口（GET /api/v3/dynamicgroup/{bk_biz_id}/{id}）核对更新后的规则是否按预期生效；
• 通过「搜索动态分组」接口（POST /api/v3/dynamicgroup/search/{bk_biz_id}）批量确认分组列表与名称变更。

七、常见错误与排查建议

结合校验源码，总结以下高频失败场景：

八、小结

「更新动态分组」接口是 CMDB 动态分组生命周期管理的关键一环，它允许通过一次PUT调用同时修改分组的名称、目标对象类型与筛选规则。理解其背后「锁定条件 + 可变条件」的双层结构、bk_obj_id与info的联动约束，以及操作符与字段类型的匹配规则，是稳定调用该接口的前提。结合本文给出的 host_server 参数校验、coreservice 落库与审计事务实现，开发者可以在蓝鲸体系内以代码方式安全、可追溯地维护动态分组，并将其作为主机/集群自动化分类治理的基础设施能力持续使用。

• 后端
• 企业应用
• 运维