后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文基于 bk-cmdb蓝鲸智云配置平台 BlueKing CMDB的 API 文档 find_set_batch.md 展开完整介绍find_set_batch接口的用途、入参、调用与响应示例并结合 topo_server 的源码实现inst_set.go、service_initfunc.go剖析参数校验规则、查询条件拼装与底层调用链帮助你在对接 CMDB 拓扑数据时准确、高效地批量获取集群set实例信息。接口定位与调用入口find_set_batch的语义是根据业务 ID 和集群实例 ID 列表以及想要获取的属性列表批量获取指定业务下集群的属性详情文档标注自 v3.8.6 起支持。它适用于如下典型场景上游系统监控、运维编排、CMDB 同步任务等已经通过拓扑接口拿到了某业务下的部分集群 IDbk_set_id需要一次性拉取这些集群的名称、环境、创建时间等属性而不是逐个调用单点查询接口需要控制返回字段fields只取所需列减少网络传输与序列化开销。从仓库中的网关资源配置 bk_apigw_resources_bk-cmdb.yaml 可以看到该开放接口的网关定义后端方法与路径POST /api/v3/findmany/set/bk_biz_id/{bk_biz_id}operationIdfind_set_batch权限属性isPublic: false、allowApplyPermission: true即该接口不是公开接口调用方需要申请相应权限后才能在 API 网关上调用超时时间timeout: 0沿用网关默认。同时该接口还通过蓝鲸 ESB 组件方式暴露。ESB 组件定义见 cc.yaml- path: /v2/cc/find_set_batch/ name: find_set_batch label: 批量查询某业务的集群详情 label_en: find set in batch suggest_method: POST api_type: query comp_codename: generic.v2.cc.cc_component dest_path: /api/v3/findmany/set/bk_biz_id/{bk_biz_id} dest_http_method: POST也就是说无论从 API 网关还是从 ESB 组件调用最终都落到同一个 CC 内部路径POST /api/v3/findmany/set/bk_biz_id/{bk_biz_id}。在 CC 内部该路由注册于 topo_server 的服务初始化逻辑 service_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /findmany/set/bk_biz_id/{bk_biz_id}, Handler: s.SearchSetBatch})即业务 ID 走 URL 路径参数请求体承载查询选项。输入参数参数名称参数类型必选描述bk_biz_idint是业务ID位于 URL 路径{bk_biz_id}中而非请求体bk_idsarray是集群实例ID列表, 即bk_set_id列表最多可填500个fieldsarray是集群属性列表控制返回结果的集群信息里有哪些字段bk_ids 的校验规则请求体由metadata.SearchInstBatchOption结构反序列化定义在 common.go// SearchInstBatchOption TODO type SearchInstBatchOption struct { IDs []int64 json:bk_ids Fields []string json:fields }其Validate方法common.go实现了两条硬性约束与文档中的“最多 500 个”描述一一对应func (s *SearchInstBatchOption) Validate() (rawError errors.RawErrorInfo) { if len(s.IDs) 0 || len(s.IDs) common.BKMaxInstanceLimit { return errors.RawErrorInfo{ ErrCode: common.CCErrArrayLengthWrong, Args: []interface{}{bk_ids, common.BKMaxInstanceLimit}, } } if len(s.Fields) 0 { return errors.RawErrorInfo{ ErrCode: common.CCErrCommParamsInvalid, Args: []interface{}{fields}, } } return errors.RawErrorInfo{} }其中上限常量BKMaxInstanceLimit在 definitions.go 中定义为500。因此bk_ids为空数组、或长度超过 500都会返回CCErrArrayLengthWrong错误错误信息中会明确指出bk_ids的长度上限是 500fields为空则返回CCErrCommParamsInvalid参数无效。该接口不支持“不传 fields 返回全量字段”的用法必须显式指定要返回的字段。bk_biz_id 的来源bk_biz_id不在请求体中而是从 URL 路径参数解析。处理函数入口inst_set.go// SearchSetBatch search the sets in one biz func (s *Service) SearchSetBatch(ctx *rest.Contexts) { bizIDStr : ctx.Request.PathParameter(common.BKAppIDField) bizID, err : strconv.ParseInt(bizIDStr, 10, 64) if err ! nil { ctx.RespAutoError(err) return } option : metadata.SearchInstBatchOption{} if err : ctx.DecodeInto(option); err ! nil { ctx.RespAutoError(err) return } rawErr : option.Validate() if rawErr.ErrCode ! 0 { ctx.RespAutoError(rawErr.ToCCError(ctx.Kit.CCError)) return } ... }注意这里业务 ID 字段在内部常量中为bk_biz_idcommon.BKAppIDField路径上的bk_biz_id必须能解析为 int64否则直接报错。调用示例{ bk_biz_id: 3, bk_ids: [ 11, 12 ], fields: [ bk_set_id, bk_set_name, create_time ] }对应完整请求为POST /api/v3/findmany/set/bk_biz_id/3请求体如上述 JSON其中bk_biz_id已体现在路径上请求体内该字段仅为文档习惯性的展示。响应示例{ result: true, code: 0, message: success, permission: null, data: [ { bk_set_id: 12, bk_set_name: ss1, create_time: 2020-05-15T22:15:51.6708:00, default: 0 }, { bk_set_id: 11, bk_set_name: set1, create_time: 2020-05-12T21:04:36.64408:00, default: 0 } ] }响应参数说明参数名称参数类型描述resultbool请求成功与否。true:请求成功false请求失败codeint错误编码。 0表示success0表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataarray请求返回的数据data参数名称参数类型描述bk_set_namestring集群名称defaultint0-普通集群1-内置模块集合默认为0bk_biz_idint业务idbk_capacityint设计容量bk_parent_idint父节点的IDbk_set_idint集群idbk_service_statusstring服务状态:1/2(1:开放,2:关闭)bk_set_descstring集群描述bk_set_envstring环境类型1/2/3(1:测试,2:体验,3:正式)create_timestring创建时间last_timestring更新时间bk_supplier_accountstring开发商账号descriptionstring数据的描述信息set_template_versionarray集群模板的当前版本set_template_idint集群模板IDbk_created_atstring创建时间bk_updated_atstring更新时间注意此处的返回值仅对系统内置的属性字段做了说明其余返回值取决于用户自己定义的属性字段。也就是说data中每个元素具体有哪些键取决于请求时传入的fields上表只覆盖了内置模型set的系统字段。源码级调用链从 topo_server 到 coreservice查询条件拼装SearchSetBatch在校验通过后会先对bk_ids去重util.IntArrayUnique然后拼装查询条件并调用 Core Service 的实例读取接口inst_set.gosetIDs : util.IntArrayUnique(option.IDs) cond : mapstr.MapStr{ common.BKAppIDField: bizID, common.BKSetIDField: mapstr.MapStr{ common.BKDBIN: setIDs, }, } qc : metadata.QueryCondition{ Fields: option.Fields, Page: metadata.BasePage{ Limit: common.BKNoLimit, }, Condition: cond, } instanceResult, err : s.Engine.CoreAPI.CoreService().Instance().ReadInstance(ctx.Kit.Ctx, ctx.Kit.Header, common.BKInnerObjIDSet, qc) if err ! nil { blog.Errorf(search module batch failed, err: %v, rid: %s, err, ctx.Kit.Rid) ctx.RespAutoError(err) return } ctx.RespEntity(instanceResult.Info)这段代码揭示了几个实现要点跨业务 ID 过滤是天然保障条件中同时包含bk_biz_id {路径中的业务ID}与bk_set_id $in {去重后的ID列表}common.BKDBIN即数据库$in操作符。即使调用方传入的bk_ids属于其他业务也不会被查出来业务隔离由服务端条件强制保证内部无分页限制Limit设为common.BKNoLimit在 definitions.go 中定义为999999999因此接口不分页返回一次最多返回 500 条集群详情固定查询set内置模型common.BKInnerObjIDSet即内置模型set查询条件中的fields原样透传实现“返回哪些字段由调用方决定”。底层实例读取客户端ReadInstance的客户端实现在 instance/api.go// ReadInstance search instance func (inst *instance) ReadInstance(ctx context.Context, h http.Header, objID string, input *metadata.QueryCondition) ( *metadata.InstDataInfo, error) { resp : new(metadata.QueryConditionResult) subPath : /read/model/%s/instances ... }即 topo_server 通过 CoreAPI 客户端向 Core Service 发送POST /read/model/set/instances携带 QueryCondition 结构type QueryCondition struct { Fields []string json:fields Page BasePage json:page Condition mapstr.MapStr json:condition // 非必填只能用来查时间且与Condition是与关系 TimeCondition *TimeCondition json:time_condition,omitempty ... }由此可还原完整调用链API网关/ESBPOST /api/v3/findmany/set/bk_biz_id/{bk_biz_id} → topo_server 路由 SearchSetBatchservice_initfunc.go 注册 → SearchInstBatchOption 校验bk_ids ≤ 500 且非空、fields 非空 → CoreAPI.CoreService().Instance().ReadInstance(set, qc) → Core Service POST /read/model/set/instances → 返回实例数据data 仅包含 fields 指定字段另外CC 内部其他服务如 admin_server、web_server 等若需要同样的批量查集群能力也可以通过 apimachinery 提供的客户端复用该接口见 toposerver/inst/set.go// SearchSetBatch TODO func (t *instanceClient) SearchSetBatch(ctx context.Context, appID string, h http.Header, s *metadata.SearchInstBatchOption) (resp *metadata.MapArrayResponse, err error) { resp new(metadata.MapArrayResponse) subPath : /findmany/set/bk_biz_id/%s ... }权限控制网关侧该接口非公开isPublic: falseCC 内部还有更细粒度的权限解析。权限解析器 ac/parser/topology.go 中定义了路径正则findSetBatchRegexp regexp.MustCompile(^/api/v3/findmany/set/bk_biz_id/[0-9]/?$)命中该正则且方法为POST时解析器从 URL 中提取bk_biz_id并将资源属性标记为业务Business资源上的FindMany动作topology.go用于后续的权限校验与审计。也就是说调用方至少需要具备对应业务的集群查询类权限。使用建议与常见错误结合文档与源码对接该接口时建议注意以下几点单次最多 500 个集群超过会触发CCErrArrayLengthWrong。数据量大时应在调用方侧将bk_ids切分为每批不超过 500 个的分片顺序/并发调用fields必填且按需取值返回字段完全由fields决定bk_set_id建议始终带上便于把结果与请求的bk_ids对齐响应数组顺序不保证与请求一致参见响应示例中 12 排在 11 前结果按业务过滤传入不属于该bk_biz_id的集群 ID 不会报错只是查不到对应记录调用方需自行比对data中实际返回的bk_set_id集合识别“未命中”的 ID错误响应遵循蓝鲸通用协议resultfalse时通过code与message定位原因常见如路径参数bk_biz_id非整数、bk_ids长度超限、fields为空等时间字段格式create_time、last_time等时间属性为带时区的 ISO 8601 字符串如2020-05-15T22:15:51.6708:00解析时建议按 RFC 3339 处理。相关文档与源码索引API 文档正文find_set_batch.md网关资源定义bk_apigw_resources_bk-cmdb.yamlESB 组件定义cc.yaml路由注册service_initfunc.go请求处理与条件拼装inst_set.go请求选项与校验common.go上限常量definitions.goCore Service 实例读取客户端instance/api.go权限解析topology.go前端页面调用类似批量查询的示例集群详情批量获取set.js赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台bk-cmdb批量删除业务集接口详解蓝鲸配置平台bk cmdb批量删除业务集接口详解 导读 本文围绕蓝鲸配置平台bk cmdb提供的批量删除业务集开放接口展开完整介绍接口的版本与权限后端企业应用运维蓝鲸配置平台集群批量查询接口 find_set_batch 全解析参数、调用与源码实现蓝鲸配置平台集群批量查询接口 find_set_batch 全解析参数、调用与源码实现 find_set_batch 是蓝鲸配置平台BlueKing CMD后端企业应用运维蓝鲸配置平台 bk-cmdb 动态分组详情查询接口 get_dynamic_group 详解蓝鲸配置平台 bk cmdb 动态分组详情查询接口 get_dynamic_group 详解 动态分组Dynamic Group是蓝鲸配置平台bk cmd后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考