后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读服务分类Service Category是蓝鲸配置平台bk-cmdb业务拓扑中用于组织服务模板与模块的逻辑分组其结构直接影响业务拓扑树中服务层级的展示与维护。本文围绕开放 API 网关APIGW提供的更新服务分类接口update_service_category完整讲解其请求参数、调用示例、响应结构并结合仓库源码深入解析从网关到数据层的完整调用链、名称校验规则、内置分类保护机制与错误码含义帮助你在业务中安全、正确地维护服务分类名称。接口概述更新服务分类是 bk-cmdb 通过 APIGW 对外开放的 API 之一对应开放 API 资源定义文件 bk_apigw_resources_bk-cmdb.yaml 中的/api/v3/update/proc/service_category资源项目值请求方式PUT请求路径/api/v3/update/proc/service_categoryoperationIdupdate_service_category功能描述更新服务分类目前仅名称字段可更新权限要求服务分类编辑权限IAM 动作edit_biz_service_category网关可见性isPublic: false需申请权限后才可调用allowApplyPermission: true从网关资源定义可以看到该接口经过 APIGW 的限流插件bk-rate-limit默认每秒 100 个令牌后以PUT方式转发至后端/api/v3/update/proc/service_category。由于userVerifiedRequired: false该接口通过蓝鲸 API 网关的统一鉴权应用凭据 用户身份完成认证而非要求用户在请求头中额外携带登录态。输入参数说明更新服务分类接口共接收三个必选参数完整参数表如下参数名称参数类型必选描述idint是服务分类 IDnamestring是服务分类名称bk_biz_idint是业务 ID参数含义详解id待更新服务分类的唯一标识。该 ID 是服务分类在bk_cmdb集合表名见下文中的主键可通过查询服务分类list_service_category接口或业务拓扑页面获取。name更新后的服务分类名称。当前版本仅支持更新名称字段服务分类的层级关系bk_parent_id、归属业务bk_biz_id等字段不可通过本接口修改。bk_biz_id服务分类所属业务 ID用于限定操作范围保证更新操作只作用于指定业务下的分类。调用示例请求体以 JSON 形式提交以下为文档给出的调用示例{ bk_biz_id: 1, id: 3, name: 222 }以curl方式调用该接口配合蓝鲸 API 网关的应用鉴权信息可写作curl -X PUT https://{APIGW_HOST}/api/v3/update/proc/service_category \ -H Content-Type: application/json \ -H X-Bk-App-Code: {APP_CODE} \ -H X-Bk-App-Secret: {APP_SECRET} \ -H X-Bk-User-Name: {USERNAME} \ -d { bk_biz_id: 1, id: 3, name: 222 }其中{APIGW_HOST}为蓝鲸 APIGW 网关地址X-Bk-App-Code/X-Bk-App-Secret为应用凭据X-Bk-User-Name为发起操作的用户名用于 IAM 权限校验。响应示例与参数说明响应示例{ result: true, code: 0, message: success, permission: null, data: { bk_biz_id: 3, id: 22, name: api, bk_root_id: 21, bk_parent_id: 21, bk_supplier_account: 0, is_built_in: false } }说明响应示例中data展示的是更新后服务分类的完整信息示例中的字段取值如id: 22、bk_biz_id: 3为演示数据与上方请求示例中的输入值无严格对应关系。响应参数说明参数名称参数类型描述resultbool请求成功与否。true表示请求成功false表示请求失败codeint错误编码。0表示 success0表示失败错误messagestring请求失败时返回的错误信息permissionobject权限信息通常为nulldataobject更新后的服务分类信息data字段说明data对象完整对应源码中 ServiceCategory 结构体 的字段定义参数名称参数类型描述bk_biz_idint业务 IDidint服务分类 IDnamestring服务分类名称bk_root_idint根服务分类 IDbk_parent_idint父服务分类 IDbk_supplier_accountstring运营商账号is_built_inbool是否是内置服务分类其中bk_parent_id为0表示该分类是一级顶层分类否则为二级分类bk_root_id记录该分类所属的根分类 ID。由 CreateServiceCategory 源码 可见一级分类创建后其bk_root_id等于自身id二级分类则继承父分类的bk_root_idis_built_in为true时表示系统内置分类如默认的Default分类见 definitions.go此类分类受保护不允许修改。底层调用链从网关到 MongoDB更新服务分类并非单模块实现而是贯穿 APIGW → proc_server → coreservice → MongoDB 的多层调用。完整链路如下APIGW (/api/v3/update/proc/service_category, PUT) │ 转发 ▼ proc_server 路由: PUT /update/proc/service_category │ [service.go](https://link.gitcode.com/i/e06321bb91a4cbb1c04a822acc15411c) 注册路由 ▼ ProcServer.UpdateServiceCategory 处理器 │ [servicecategory.go](https://link.gitcode.com/i/9d7ea26bf860220a09ed73b242d0c826) ▼ apimachinery 客户端: PUT /update/proc/service_category │ [category.go](https://link.gitcode.com/i/d936811216f9d1a6c220b9a4f8585f71) ▼ coreservice 路由: PUT /update/process/service_category/{service_category_id} │ [service_process_initfunc.go](https://link.gitcode.com/i/18bed2bbd8a20d93c18a442f9c903e8b) ▼ coreService.UpdateServiceCategory 处理器 │ [service_category.go](https://link.gitcode.com/i/39bf798615146dd7eb366a2489f9ef42) ▼ processOperation.UpdateServiceCategory业务逻辑 MongoDB 写入 [service_category.go](https://link.gitcode.com/i/33a2b33e162813ea8ad68c7f83c0090c)各层职责proc_server 层UpdateServiceCategory处理器先通过ctx.DecodeInto(input)解析请求体为 ServiceCategory 结构体随后使用Engine.CoreAPI.CoreService().Txn().AutoRunTxn开启事务在事务内调用 coreservice 的更新接口。数据持久化到 MongoDB 的操作与事务提交保持一致性源码见 servicecategory.go。apimachinery 客户端层封装对 coreservice 的 HTTP 调用构造PUT /update/proc/service_category请求源码见 category.go为上层各服务模块提供统一的 SDK 入口。coreservice 接口层从 URL 路径参数中解析service_category_idctx.Request.PathParameter(common.BKServiceCategoryIDField)并通过ctx.DecodeInto解析请求体然后调用数据层源码见 service_category.go。coreservice 数据层执行最终的校验与写库操作详见下一节。核心业务逻辑名称校验、内置分类保护与唯一性检查更新操作的真正核心位于数据层 processOperation.UpdateServiceCategory其执行流程可以概括为四步1. 加载原分类并更新名称先通过GetServiceCategory(kit, categoryID)按id从bk_cmdb集合表常量BKTableNameServiceCategory加载目标分类加载成功后仅将请求中的Name覆盖到本地对象category, err : p.GetServiceCategory(kit, categoryID) ... category.Name input.Name这一步印证了文档中目前仅名称字段可更新的描述请求体中即使携带其他字段最终也只会被用于名称更新。2. 名称合法性校验更新后的对象调用ServiceCategory.Validate()进行校验源码见 process.go校验规则包括校验项规则依据非空名称不能为空字符串process.go最大长度按 UTF-8 字符数utf8.RuneCountInString计算不得超过 128 个字符常量ServiceCategoryMaxLength见 definitions.go字符格式必须匹配正则^([\w\p{Han}]|[:\-\(\)])$即允许字母、数字、下划线、中文及: - ( )字符常量FieldTypeServiceCategoryRegexp见 definitions.go校验失败时接口返回参数非法错误CCErrCommParamsInvalid并在message中指明具体字段与原因。3. 内置分类保护若目标分类的IsBuiltIn为true更新操作会被直接拒绝返回错误码CCErrCommOperateBuiltInItemForbidden错误码值 1199054见 errInfo.goif category.IsBuiltIn { return nil, kit.CCError.CCError(common.CCErrCommOperateBuiltInItemForbidden) }这意味着系统内置服务分类如默认的Default分类只读无法通过本接口改名。4. 名称唯一性检查更新前会在业务范围内校验新名称是否与其他分类冲突构造的查询条件为name等于新名称排除当前分类自身id ! categoryIDbk_biz_id属于[0, 业务ID]即全局默认分类与当前业务分类均参与查重同时匹配bk_parent_id同层级内互斥。若已存在同名分类返回错误码CCErrCoreServiceServiceCategoryNameDuplicated错误码值 1113017见 errInfo.go。5. 执行更新并返回最新数据以上校验全部通过后按id为过滤条件执行 MongoDB 的Update并将更新后的完整分类对象作为data返回给调用方。权限控制IAM 服务分类编辑权限文档明确指出该接口需要服务分类编辑权限。在 bk-cmdb 的权限中心IAM适配中资源类型biz_process_service_category服务分类与动作edit_biz_service_category服务分类编辑的定义见 types.go动作展示名为服务分类编辑见 initial_actions.go在 adaptor.go 中meta.Update操作被映射到EditBusinessServiceCategory动作即更新服务分类对应服务分类编辑权限。调用方即X-Bk-User-Name指定的用户若未获授权网关或 CMDB 会返回权限不足相关错误响应中的permission字段可用于向权限中心申请权限。错误排查指引结合错误码定义更新服务分类时常见失败场景如下场景错误码含义与处理建议id不存在CCErrCommNotFound目标分类不存在请先通过查询接口确认id名称为空 / 超长 / 含非法字符CCErrCommParamsInvalid按上文校验规则修正name非空、≤128 字符、符合正则目标为内置分类CCErrCommOperateBuiltInItemForbidden1199054内置分类不可更新请更换目标分类同层级已存在同名分类CCErrCoreServiceServiceCategoryNameDuplicated1113017更换为业务内不重复的名称无权限IAM 权限不足使用具有服务分类编辑权限的用户调用在仓库的集成测试中更新服务分类的行为由 no_service_template_test.go 覆盖——测试通过serviceClient.UpdateServiceCategory修改服务分类名称后再校验查询结果中分类名称是否同步更新可用于验证接口在完整环境下的正确性。小结更新服务分类接口是 bk-cmdb 业务拓扑维护中的重要写操作。使用时需重点把握三点仅名称可更新、内置分类受保护、业务内同名互斥。通过本文梳理的调用链与校验逻辑你可以准确构造请求、预判失败场景并理解名称变更在 CMDB 多模块架构中的流转过程。更完整的开放 API 定义可参考 bk_apigw_resources_bk-cmdb.yaml接口文档原文见 update_service_category.md。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 主机锁定接口 add_host_lock 实战指南参数、幂等语义与底层实现蓝鲸配置平台 bk cmdb 主机锁定接口 add_host_lock 实战指南参数、幂等语义与底层实现 本文以蓝鲸智云配置平台BlueKing CMDB后端企业应用运维蓝鲸配置平台bk-cmdb批量更新 Kubernetes Workload 接口实战指南蓝鲸配置平台bk cmdb批量更新 Kubernetes Workload 接口实战指南 导读 本文围绕 bk cmdb蓝鲸智云配置平台API 网关提供后端企业应用运维蓝鲸配置平台 bk-cmdb 新建服务分类接口create_service_category实战指南参数详解、源码原理与测试验证蓝鲸配置平台 bk cmdb 新建服务分类接口create_service_category实战指南参数详解、源码原理与测试验证 本指南以蓝鲸智云配置平台后端企业应用运维上一篇LanceDB Python 从同步 API 迁移到异步 API 完整指南connect_async 与 AsyncConnection/AsyncTable 实战下一篇Sliver Pivots 完整实战指南用 C2 流量链式代理穿越受限网络TCP / Named Pipe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
