bk-cmdb 新建服务模板接口（create_service_template）详解：请求参数、返回字段与源码级实现剖析

后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本篇基于蓝鲸智云配置平台bk-cmdb的官方接口文档create_service_template完整讲解该接口ESB 侧路径/v2/cc/create_service_template/CMDB 侧路径POST /api/v3/create/proc/service_template的功能定位、全部请求/返回参数、调用示例并结合同仓库的处理器、元数据定义与权限校验源码剖析服务模板创建事务中写库 IAM 注册的完整调用链帮助读者能够独立完成接口对接、读懂返回结构并排查权限与参数类错误。1. 接口功能与访问路径该接口的功能描述为根据传入的服务模板名称和服务分类 ID创建指定名称和服务分类的服务模板。中文文档中同时标注了权限要求——需要服务模板新建权限。服务模板Service Template是 bk-cmdb 拓扑体系中的重要对象位于 业务Business → 集群Set → 模块Module 层级之上用于把一类服务如登录服务中间件的通用配置沉淀下来当业务拓扑中的模块绑定某个服务模板后可以直接继承模板上的配置字段取值与进程模板避免在多个模块中重复维护。因此新建服务模板通常是业务初始化、CMDB 数据批量导入的前置步骤。该接口在仓库中存在三层访问映射全部可在源码中查证ESB 映射定义在 cc.yamlpath为/v2/cc/create_service_template/suggest_method: POSTdest_path指向 CMDB 内部接口/api/v3/create/proc/service_templatedest_http_method: POSTAPI 网关资源定义在 bk_apigw_resources_bk-cmdb.yamloperationId: create_service_templateisPublic: false、allowApplyPermission: true即需要先申请该接口的调用权限并配置了默认 100 tokens/秒的bk-rate-limit限流权限配置定义在 servicetemplate.gocreateServiceTemplatePattern条目将POST /api/v3/create/proc/service_template映射到资源类型meta.ProcessServiceTemplate、动作meta.CreateBizIDGetter使用DefaultBizIDGetter从请求体中的bk_biz_id提取业务 ID 做业务级鉴权。从源码结构看接口路由注册位于 proc_server 的场景服务中service.go 在newProcessService里把POST /create/proc/service_template绑定到ps.CreateServiceTemplate处理器。2. 请求参数2.1 通用参数文档中的{{ common_args_desc }}表示通用参数由文档模板注入即蓝鲸 ESB 调用的标准身份与追踪字段字段类型必选说明bk_app_codestring是应用 IDbk_app_secretstring是应用密钥bk_usernamestring是蓝鲸账号bk_tokenstring否蓝鲸 SSO 颁发的用户 tokenbk_username 和 bk_token 二选一验证身份2.2 接口参数字段类型必选描述namestring是服务模板名称service_category_idint是服务分类 IDbk_biz_idint是业务 ID结合元数据结构 process_request.go 中的CreateServiceTemplateOption该接口实际解析的字段比文档表格多一个可选项字段类型必选描述bk_biz_idint64是业务 IDnamestring是服务模板名称创建后受ServiceTemplate.Validate约束走ValidTopoNameField拓扑名称校验见 process.go 中ServiceTemplate.Validateservice_category_idint64是服务分类 ID对应此前通过create_service_category创建的分类host_apply_enabledbool否是否开启主机属性自动应用JSON 字段名host_apply_enabled未传时默认为falsename字段最终会进入ServiceTemplate.Validate调用 valid.go 中的ValidTopoNameField——注释说明该校验面向可生成拓扑的名称business/set/service template 均会生成对应拓扑节点因此名称需要满足 CMDB 拓扑名称规范非空、长度与字符集限制等。2.3 请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 1, name: test4, service_category_id: 1 }3. 返回结果3.1 返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: { bk_biz_id: 1, id: 52, name: test4, service_category_id: 1, creator: admin, modifier: admin, create_time: 2019-09-18T23:09:44.25197045308:00, last_time: 2019-09-18T23:09:44.25197056808:00, bk_supplier_account: 0 } }3.2 response 字段说明字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息无权限时返回具体的无权限资源/动作清单成功时为 nullrequest_idstring请求链 id可用于日志排查dataobject请求返回的数据3.3 data 字段说明字段类型描述idint服务模板 IDbk_biz_idint业务 IDnamestring服务模板名称service_category_idint服务分类 IDcreatorstring本条数据创建者modifierstring本条数据的最后修改人员create_timestring创建时间last_timestring更新时间bk_supplier_accountstring开发商账号host_apply_enabledbool是否启用主机属性自动应用中文文档示例中含此字段取值对应请求参数host_apply_enabled默认falsedata 的字段集与 process.go 中的ServiceTemplate结构体一一对应bk_biz_id、id、name、service_category_id、creator、modifier、create_time、last_time、bk_supplier_account、host_apply_enabled其中creator/modifier取自请求身份bk_supplier_account取自请求上下文的供应商账号。4. 源码实现剖析一次创建请求经历了什么接口的核心处理器位于 servicetemplate.go 的CreateServiceTemplate方法从源码可以还原出完整的执行流程参数解码ctx.DecodeInto(option)将请求体反序列化为metadata.CreateServiceTemplateOption字段定义见第 2.2 节解码失败直接返回参数错误构造实体组装metadata.ServiceTemplate其中SupplierAccount不来自请求体而是取自ctx.Kit.SupplierAccount请求头中的供应商上下文HostApplyEnabled来自请求体缺省为false事务执行通过ps.Engine.CoreAPI.CoreService().Txn().AutoRunTxn(...)开启分布式事务在事务内完成两件事调用 CoreService 的Process().CreateServiceTemplate真正落库客户端实现见 api.goPOST 到 coreservice 的/create/process/service_template若开启了鉴权auth.EnableAuthorize()把新模板注册为 IAM 资源以iam.BizProcessServiceTemplate为资源类型、模板 ID 为实例 ID、当前用户为 Creator调用RegisterResourceCreatorAction登记资源创建者动作。这一步保证谁创建的模板谁天然拥有该模板的操作权限是 bk-cmdb IAM 授权模型的一部分失败回滚任一步骤出错落库失败或 IAM 注册失败都会使整个事务回滚并返回错误返回成功时ctx.RespEntity(tpl)将带完整 ID 和时间戳的ServiceTemplate作为data返回与第 3 节示例一致。这里有一个值得注意的设计权限注册被放在了同一个事务里而不是先建数据后补权限。从源码结构看这避免了模板已存在但 IAM 侧无创建者记录的中间状态——如果 IAM 注册失败模板记录本身也会被回滚调用方只会看到一次失败重试即可。4.1 相关客户端封装其他服务若要调用该接口例如 admin_server 的数据迁移、同步任务仓库提供了 typed client 封装 template.goservice.CreateServiceTemplate直接 POST 到/create/proc/service_template请求体为map[string]interface{}响应解析为metadata.ResponseDataMapStr。4.2 姊妹接口全量创建proc_server 同时还注册了POST /create/proc/service_template/all_infoCreateServiceTemplateAllInfo见 service.go。它与本接口的区别在于在同一个事务内一次性创建服务模板本体 模板配置字段attributes 进程模板processes适合程序化批量初始化场景。若只需要空模板骨架使用本文的create_service_template即可后续还可通过update_service_template、update/proc/service_template/attribute等接口补齐配置。5. 常见集成注意事项权限ESB/APIGW 侧需要先申请该接口的调用权限allowApplyPermission: true表示可在网关申请CMDB 侧还需要服务模板新建权限业务维度的ProcessServiceTemplate资源 Create动作见 servicetemplate.go。无权限时result为falsepermission字段会返回具体缺失的资源与动作便于按提示申请服务分类必须先存在service_category_id引用的分类需先通过create_service_category创建ESB 映射见 cc.yaml 中dest_path: /api/v3/create/proc/service_category限流网关为该资源配置了bk-rate-limit默认 100 tokens/秒见 bk_apigw_resources_bk-cmdb.yaml批量创建场景应控制并发必要时以request_id结合code/message做重试与去重名称合法性name走拓扑名称统一校验不符合规范时会返回参数类错误code 0建议批量导入前先对名称做本地预校验环境前提以上参数与路径以当前仓库docs/apidoc/cc目录下的接口文档及v3API 源码为准适用于启用 ESB/API 网关访问 CMDB 的蓝鲸环境bk_token与bk_username的身份校验方式取决于部署侧的 SSO 配置。6. 小结create_service_template是 bk-cmdb 服务模板生命周期的入口接口请求只需三个业务字段name、service_category_id、bk_biz_id即可创建模板可选host_apply_enabled控制主机属性自动应用开关返回体携带新模板的完整元数据ID、审计字段、时间戳。源码层面它体现了 bk-cmdb 的典型接口模式——场景服务proc_server负责参数解码与编排事务内联动 CoreService 落库与 IAM 创建者注册失败整体回滚网关层再叠加限流与权限申请机制。理解这一链路后读者可以放心地把它用于自动化部署与 CMDB 数据初始化脚本中。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 创建服务模板接口create_service_template详解参数、调用链路与源码实现蓝鲸 CMDB 创建服务模板接口create_service_template详解参数、调用链路与源码实现 服务模板Service Template是后端企业应用运维bk-cmdb 创建模型属性接口 create_object_attribute参数详解与源码实现剖析bk cmdb 创建模型属性接口 create_object_attribute参数详解与源码实现剖析 本篇技术文章基于 bk cmdb蓝鲸智云配置平台的后端企业应用运维bk-cmdb 新建服务分类接口 create_service_category 详解ESB 调用、参数校验与源码实现bk cmdb 新建服务分类接口 create_service_category 详解ESB 调用、参数校验与源码实现 本篇围绕蓝鲸智云配置平台bk cmd后端企业应用运维上一篇免费在线3D查看器浏览器中预览和测量任何3D模型的终极解决方案下一篇YimMenuGTA5安全防护与游戏增强的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考