• 后端
• 企业应用
• 运维

导读

管控区域（Cloud Area，旧称"云区域"）是 BlueKing CMDB 中用于隔离和管理不同网络区域主机资源的核心模型，而update/cloudarea接口（update_cloud_area）负责对已有管控区域的名称等属性进行更新维护。本文基于当前仓库的接口文档与源码实现，完整讲解该接口的请求参数、调用示例、返回结构与底层实现原理，帮助开发者正确、安全地在业务系统中调用该接口完成管控区域的动态维护。

一、接口功能与调用前提

1.1 功能描述

update_cloud_area接口用于更新管控区域，其调用前提为调用方具备管控区域编辑权限（对应蓝鲸权限中心 IAM 中的edit_cloud_area操作）。该接口可以修改管控区域的名称等基础属性，是管控区域生命周期管理（创建 → 更新 → 查询 → 删除）中的重要一环。

在 src/scene_server/host_server/service/cloudarea.go 中，服务端实现函数为UpdatePlat，其核心职责包括：解析 URL 路径中的管控区域 ID、校验是否为内置管控区域、解码请求体、记录审计日志并以事务方式更新实例数据。

1.2 权限模型

从 src/ac/iam/adaptor.go 的权限动作映射可以看出，管控区域资源（CloudAreaInstance）的Update动作对应权限动作EditCloudArea；src/ac/iam/initial_actions.go 中定义了EditCloudArea: "管控区域编辑"，即文档中所说的"管控区域编辑权限"。

二、请求参数详解

2.1 公共参数（common_args）

接口文档中的{{ common_args_desc }}为文档模板占位符，实际调用时需携带 ESB 网关鉴权公共参数。从请求参数示例可以确认，至少需要以下公共参数：

2.2 接口参数

参数说明：

• bk_cloud_id：必填，用于定位待更新的管控区域。它来源于管控区域创建（create_cloud_area）或查询（search_cloud_area）接口的返回值。
• bk_cloud_name：选填，更新后的管控区域名称。若请求体中不携带该字段，则名称保持不变；服务端按字段是否存在决定是否更新（详见后文源码解析）。

值得说明的是，虽然文档表格仅列出以上两个接口参数，但从 src/scene_server/host_server/service/cloudarea.go 的服务端解码结构来看，实际实现还支持bk_cloud_vendor（云厂商）与bk_region（地域）字段的更新。对应地，src/common/metadata/cloud.go 中CloudArea结构体完整字段还包括bk_status、bk_supplier_account、bk_vpc_id、bk_vpc_name、bk_account_id、bk_creator、bk_last_editor、create_time、last_time等。

三、请求参数示例

以下为完整的 HTTP 请求 JSON 示例（直接取自接口文档）：

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_cloud_id": 5, "bk_cloud_name": "管控区域1" }

该示例表示：将 ID 为5的管控区域名称更新为管控区域1。请求时携带的公共鉴权参数与业务参数bk_cloud_id、bk_cloud_name一同置于请求体中。

对应的 HTTP 方法为PUT，完整路径为/api/v3/update/cloudarea/{bk_cloud_id}（bk_cloud_id同时作为 URL 路径参数与请求体字段存在）。这一路由在 src/scene_server/host_server/service/service_initfunc.go 中注册，具体定义为：

utility.AddHandler(rest.Action{Verb: http.MethodPut, Path: "/update/cloudarea/{bk_cloud_id}", Handler: s.UpdatePlat})

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

4.1 返回结果示例

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

4.2 response 参数说明

其中request_id贯穿整条调用链，便于在日志中检索定位问题；permission字段在权限中心开启且权限不足时会携带跳转授权所需的详细信息。

五、源码级实现原理

5.1 客户端调用链

在 src/apimachinery/hostserver/apis.go 中定义了 SDK 客户端方法UpdateCloudArea：

// UpdateCloudArea TODO func (hs *hostServer) UpdateCloudArea(ctx context.Context, h http.Header, cloudID int64, data map[string]interface{}) (resp *metadata.Response, err error) { resp = new(metadata.Response) subPath := "/update/cloudarea/%d" err = hs.client.Put(). WithContext(ctx). Body(data). SubResourcef(subPath, cloudID). WithHeaders(h). Do(). Into(resp) return }

可以看到：客户端通过PUT方法请求/update/cloudarea/%d子路径，cloudID作为路径参数格式化进 URL，请求体为需要更新的字段集合，响应反序列化为metadata.Response。

5.2 服务端处理流程

服务端入口为 src/scene_server/host_server/service/cloudarea.go 中的UpdatePlat函数，其处理流程可概括为以下五个步骤：

第一步：解析并校验管控区域 ID。从 URL 路径参数中取出bk_cloud_id并转换为int64；解析失败时返回参数非法错误（错误码1199006，对应CCErrCommParamsInvalid）。

第二步：禁止修改内置管控区域。代码显式检查：

if util.ContainsInt(common.BuiltInCloudAreaIDs, platID) { ctx.RespAutoError(ctx.Kit.CCError.CCError(common.CCErrTopoUpdateBuiltInCloudForbidden)) return }

根据 src/common/definitions.go，内置管控区域 ID 集合为[]int64{BKDefaultDirSubArea, UnassignedCloudAreaID}，即0（默认目录子区域）和90000001（未分配管控区域）。尝试更新这两个内置区域会返回错误码1199076（CCErrTopoUpdateBuiltInCloudForbidden），这是接口的关键保护机制。

第三步：解码请求体。请求体仅接受三个业务字段：

input := struct { CloudName string `json:"bk_cloud_name"` CloudVendor string `json:"bk_cloud_vendor"` Region string `json:"bk_region"` }{}

随后按"字段非空才更新"的原则组装toUpdate集合，同时自动写入bk_last_editor（最后编辑人）为当前操作用户：

toUpdate := mapstr.MapStr{ common.BKLastEditor: user, } if len(input.CloudVendor) != 0 { toUpdate[common.BKCloudVendor] = input.CloudVendor } if len(input.Region) != 0 { toUpdate[common.BKRegion] = input.Region } if len(input.CloudName) != 0 { toUpdate[common.BKCloudNameField] = input.CloudName }

字段名常量定义在 src/common/definitions.go：BKCloudIDField = "bk_cloud_id"、BKCloudNameField = "bk_cloud_name"。

第四步：生成审计日志。通过auditlog.NewCloudAreaAuditLog构造审计对象，使用metadata.AuditUpdate类型生成更新前的审计日志。

第五步：事务内执行更新。更新操作在AutoRunTxn事务中执行：先通过CoreService().Instance().UpdateInstance更新bk_cloud_id等于目标 ID 的管控区域实例（模型 ID 为common.BKInnerObjIDPlat），更新条件为：

updateOption := &meta.UpdateOption{ Data: toUpdate, Condition: map[string]interface{}{ common.BKCloudIDField: platID, }, }

事务成功后保存审计日志并返回ctx.RespEntity(nil)（即返回data: "success"）；事务内任一步失败则整体回滚并返回对应错误。

5.3 测试用例验证

仓库中的集成测试 src/test/host_server/cloudarea_test.go 覆盖了更新接口的主要分支场景：

这些用例与请求参数表中"bk_cloud_name 为可选项"的约定一致：正常更新场景仅携带bk_cloud_name即可成功；而重名、非法厂商值、目标不存在等异常场景均会被服务端校验拦截。

六、常见错误码与排查建议

排查建议：

1. 确认目标 ID 存在：先用search_cloud_area查询接口确认待更新的管控区域 ID 是否真实存在，且不属于内置区域。
2. 确认权限：更新失败且返回带permission信息的响应时，说明当前用户缺少"管控区域编辑"权限，需在蓝鲸权限中心申请edit_cloud_area操作权限。
3. 关注事务一致性：该接口更新与审计日志写入在同一事务内，若数据出现"已更新但无审计"的异常，应从 CoreService 事务执行结果与日志中排查。
4. 通过 request_id 追踪：响应中的request_id可用于在服务端日志中串联完整请求链路，定位具体失败环节。

七、总结

update_cloud_area是 BlueKing CMDB 管控区域管理的基础接口之一。通过本文可以掌握：

• 接口的完整请求参数（公共参数 +bk_cloud_id/bk_cloud_name）与 PUT 调用方式；
• 返回结构各字段的业务含义（result/code/message/permission/request_id/data）；
• 服务端UpdatePlat的实现细节：内置管控区域保护、按字段非空增量更新、审计日志与事务保证；
• 通过 src/test/host_server/cloudarea_test.go 中的测试用例了解接口的边界行为与校验规则。

在集成调用时，建议结合search_cloud_area查询接口先行确认目标管控区域状态，并确保调用账号具备对应编辑权限，即可安全完成管控区域的动态维护。

• 后端
• 企业应用
• 运维