★ FEATURED ARTICLE 后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读find_host_by_set_template是蓝鲸智云配置平台bk-cmdb提供的标准查询接口之一用于按**集群模板Set Template**批量获取其下所有主机Host是业务侧基于模板化拓扑批量盘点主机资产的常用入口。阅读本文后你将掌握该接口的完整请求参数、分页规则、真实请求/响应报文以及其在 bk-cmdb 源码中的调用链路与校验逻辑能够直接在业务中准确调用并按需组合bk_set_template_ids与bk_set_ids完成主机筛选。接口概述该接口对应的功能为查询集群模板下的主机其语义是在指定业务bk_biz_id内给定一个或多个集群模板 ID返回这些模板所关联集群下挂载的全部主机同时可额外指定集群 ID 列表bk_set_ids做二次收窄或仅传入fields控制返回的主机字段集合。版本要求v3.8.6 及以上权限要求业务访问权限Business Access Permission调用方式POST请求路径/api/v3/findmany/hosts/by_set_templates/biz/{bk_biz_id}bk_cmdb 原生 REST 路径bk_biz_id作为路径参数在蓝鲸 API 网关APIGW与 ESB 体系中该接口的开放映射配置可分别在 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml/api/v3/findmany/hosts/by_set_templates/biz/{bk_biz_id}资源定义与 docs/apidoc/cc/cc.yaml/v2/cc/find_host_by_set_template/ESB 组件映射目标路径指向上述 v3 原生接口中确认。请求参数说明公共参数接口使用蓝鲸标准公共参数包括bk_app_code应用编码、bk_app_secret应用密钥、bk_username用户名、bk_token登录票据等用于蓝鲸体系内的鉴权与调用方标识。接口参数字段类型必填说明bk_biz_idint是业务 IDbk_set_template_idsint array是集群模板 ID 列表最多 500 个bk_set_idsint array否集群 ID 列表最多 500 个fieldsstring array是主机属性字段列表控制返回的主机信息中包含哪些字段pageobject是分页信息参数说明与源码依据bk_set_template_ids与bk_set_ids的最多 500 个上限来自 bk-cmdb 的公共常量BKMaxInstanceLimit 500定义于 src/common/definitions.go。在服务端参数校验中若bk_set_template_ids为空或超过 500 个会返回CCErrArrayLengthWrong错误bk_set_ids为空时允许非必填但一旦传入且超过 500 个同样报错。对应校验逻辑见 src/common/metadata/hostserver.go 中FindHostsBySetTplOpt.Validate()。fields为必填且不能为空数组源码校验中len(o.Fields) 0时返回CCErrCommParamsInvalid。因为该字段直接决定了后续按主机 ID 反查主机详情时返回哪些属性见下文返回数据中的字段。page的limit最大为 500这是该接口文档明确的上限同时 bk-cmdb 全局还有BKMaxPageSize 1000的分页上限常量src/common/definitions.go在BasePage.IsIllegal()src/common/metadata/page.go中校验start 0或limit 1000且不等于BKNoLimit999999999、以及limit 0均视为非法。page 字段说明字段类型必填说明startint是记录开始位置偏移量从 0 开始limitint是每页记录数最大 500分页对象在源码中对应BasePage结构src/common/metadata/page.go除start、limit外还支持sort排序字段与enable_count等可选属性接口文档所述的分页为经典 offset 分页startlimit。请求参数示例以下为文档给出的完整请求体含公共参数{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 5, bk_set_template_ids: [ 1, 3 ], bk_set_ids: [ 13, 14 ], fields: [ bk_host_id, bk_cloud_id ], page: { start: 0, limit: 10 } }请求语义解读业务 ID 为 5查询集群模板 ID 为 1 和 3 的所有集群在这些集群中仅关注集群 ID 为 13、14 的集群bk_set_ids起过滤收窄作用返回的主机只包含bk_host_id主机 ID与bk_cloud_id管控区域 ID两个字段分页从第 0 条开始每页最多返回 10 条。响应示例响应体{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: { count: 7, info: [ { bk_cloud_id: 0, bk_host_id: 1 }, { bk_cloud_id: 0, bk_host_id: 3 }, { bk_cloud_id: 0, bk_host_id: 4 }, { bk_cloud_id: 0, bk_host_id: 5 }, { bk_cloud_id: 0, bk_host_id: 6 }, { bk_cloud_id: 0, bk_host_id: 7 }, { bk_cloud_id: 0, bk_host_id: 8 } ] } }示例中命中了 7 台主机count: 7且因请求方在fields中只申请了bk_host_id与bk_cloud_idinfo数组中每台主机也仅返回这两个字段。响应参数说明response响应外层字段类型说明resultbool请求是否成功。true成功false失败codeint错误码。0 表示成功0 表示失败错误码messagestring失败时返回的错误信息permissionobject权限信息request_idstring请求链路 IDdataobject请求返回的数据data字段类型说明countint记录总数infoarray实际返回的主机数据data.info主机字段info中每条记录即一台主机的属性集合。文档完整列出系统内置主机属性字段返回字段以请求中fields为准字段类型说明bk_host_namestring主机名bk_host_inneripstring内网 IPbk_host_idint主机 IDbk_cloud_idint管控区域import_fromstring主机导入来源3 表示 API 导入bk_asset_idstring固资编号bk_cloud_inst_idstring云主机实例 IDbk_cloud_vendorstring云厂商bk_cloud_host_statusstring云主机状态bk_commentstring备注bk_cpuintCPU 逻辑核数bk_cpu_architecturestringCPU 架构bk_cpu_modulestringCPU 型号bk_diskint磁盘容量GBbk_host_outeripstring主机外网 IPbk_host_innerip_v6string主机内网 IPv6bk_host_outerip_v6string主机外网 IPv6bk_isp_namestring运营商名称bk_macstring主机内网 MAC 地址bk_memint主机内存容量MBbk_os_bitstring操作系统位数bk_os_namestring操作系统名称bk_os_typestring操作系统类型bk_os_versionstring操作系统版本bk_outer_macstring主机外网 MAC 地址bk_province_namestring主机所在省份bk_service_termint保修年限bk_slastringSLA 等级bk_snstring设备 SNbk_statestring当前状态bk_state_namestring主机所在国家operatorstring主要维护人bk_bak_operatorstring备份维护人注意上述说明仅覆盖系统内置属性字段其余返回值取决于用户自定义的属性字段——只要在fields中声明自定义字段名返回的info中同样会携带对应值。底层实现与调用链路该接口在 bk-cmdb 中由 host_server主机场景服务承载核心处理函数为FindHostsBySetTemplates源码位于 src/scene_server/host_server/service/findhost.go。整个处理流程可分为五个阶段参数解码与校验请求体被解码为meta.FindHostsBySetTplOpt结构体src/common/metadata/hostserver.go随后执行Validate()L206-L237——依次校验bk_set_template_ids非空且不超过 500、bk_set_ids不超过 500、fields非空、page合法。业务 ID 解析与鉴权从 URL 路径参数{bk_biz_id}解析业务 ID非法或为 0 时报CCErrCommParamsInvalid随后调用s.authHostUnderBiz校验当前用户在该业务下的主机访问权限无权限则返回RespNoAuth。查询集群 ID 集合构造setCond条件固定包含bk_biz_id bizID与set_template_id IN (bk_set_template_ids)若传入bk_set_ids则追加bk_set_id IN (bk_set_ids)条件src/scene_server/host_server/service/findhost.go。通过GetSetIDByCond查询得到满足条件的集群 ID 数组若为空直接返回空的SearchHost结果。按拓扑关系去重取主机 ID将业务 ID、集群 ID 数组组装为DistinctHostIDByTopoRelationRequest调用CoreService().Host().GetDistinctHostIDByTopologysrc/scene_server/host_server/service/findhost.go得到去重后的全部主机 ID并对 ID 做升序排序。分页 按字段取主机详情依据page.start与page.limit对主机 ID 切片再以bk_host_id IN (主机ID集合)的条件调用SearchHostInfo反查主机详情最终返回count总数与info当页主机数据——参见 src/scene_server/host_server/service/findhost.go。路由注册见 src/scene_server/host_server/service/service_initfunc.go即POST /findmany/hosts/by_set_templates/biz/{bk_biz_id}与文档/APIGW 配置中的路径完全对应。使用注意事项模板与集群的从属关系查询结果取决于业务内集群与集群模板的绑定关系set_template_id未挂载到模板的集群不会出现在结果中。bk_set_ids是过滤器而非附加条件传入后会在模板下的全部集群基础上进一步收窄不传则返回模板下全部集群的主机。fields必须显式声明该接口不会默认返回全部字段未声明的内置/自定义属性不会出现在info中建议按需声明以控制响应体大小。分页注意start从 0 开始limit单页上限 500全局上限 1000实际响应中count为命中总条数可用于计算页数。版本与权限接口自 v3.8.6 起提供调用方需具备对应业务的访问权限否则将收到权限拒绝响应。开放网关调用若通过蓝鲸 API 网关/ESB 调用使用docs/apidoc/cc/cc.yaml中登记的/v2/cc/find_host_by_set_template/组件路径POSTapi_type: query网关侧已配置 100 tokens/秒 的限流策略见 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 集群模板主机查询接口 find_host_by_set_template 实战指南蓝鲸配置平台 bk cmdb 集群模板主机查询接口 find_host_by_set_template 实战指南 本文基于 bk cmdb 官方开放接口文档后端企业应用运维bk-cmdb 主机服务模板 ID 查询接口list_host_service_template_id详解bk cmdb 主机服务模板 ID 查询接口list_host_service_template_id详解 导读 list_host_service_tem后端企业应用运维bk-cmdb 集群模板编辑 API 实战指南update_set_template 接口解析bk cmdb 集群模板编辑 API 实战指南update_set_template 接口解析 集群模板Set Template是蓝鲸配置平台bk cm后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
