bk-cmdb 开放 API 详解：list_service_instance 按业务查询服务实例列表-北京尧图网络

后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载在蓝鲸智云配置平台bk-cmdb的进程管理场景中服务实例ServiceInstance是承载主机上进程实例的运行时载体。本文基于开放 API 文档 list_service_instance完整讲解list_service_instance接口的入参、分页、标签过滤与响应结构并结合 bk-cmdb 仓库源码proc_server 路由、metadata 查询模型、coreservice 存储层还原其完整调用链与底层实现帮助你在集成或排查该接口时做到参数知其然、行为知其所以然。接口定位与调用方式list_service_instance用于根据业务 id 查询服务实例列表也可以叠加模块 id、主机 id 列表、名称模糊搜索、标签过滤等条件进一步收敛结果是进程管理相关开放 API 中检索频率最高的一类接口。从 API 网关定义 bk_apigw_resources_bk-cmdb.yaml 可以看到该接口的元信息operationIdlist_service_instance描述为查询服务实例列表后端转发网关将请求以POST方法转发至后端路径/api/v3/findmany/proc/service_instance权限模型isPublic: false、allowApplyPermission: true即非公开资源需要按资源维度申请list_service_instance权限在 definition.yaml 中list_service_instance被列入了多个内部应用如 NodeManager、BCS 等的资源授权清单限流配置了bk-rate-limit插件默认速率period: 1, tokens: 100即每秒 100 个 token 的令牌桶限流批量调用方需注意控制并发。输入参数接口的请求体参数如下继承自原始文档参数名称参数类型必选描述bk_biz_idint是业务idbk_module_idint否模块IDbk_host_idsint array否主机id列表最多支持1000个主机idselectorsint否label过滤功能operator可选值:,!,exists,!,in,notinpageobject否分页参数search_keystring否名字过滤参数可填写进程名称包含的字符用于模糊搜索补充说明原始文档中selectors的参数类型标注为int属于笔误从源码看其实际类型是 selector 对象数组见 metadata.ListServiceInstanceOption 中Selectors selector.Selectors字段每个元素包含key、operator、values三个字段。page 分页参数参数名称参数类型必选描述startint是记录开始位置limitint是每页限制条数,最大500分页约束在源码中可以得到印证上限 500 对应全局常量BKMaxLimitSize 500src/common/definitions.goBasePage.Validate会对越界的分页参数返回错误src/common/metadata/page.gobk_host_ids最多支持 1000 个主机 id 对应BKMaxPageSize 1000处理器SearchServiceInstancesInModule中显式检查len(input.HostIDs) common.BKMaxPageSize超出时直接返回参数超限错误serviceinstance.go。selectors 标签过滤selectors用于基于服务实例的 labels标签做条件过滤。从源码 selector.go 可以看到支持的 operator 全集为Equals、!NotEquals、exists、!DoesNotExist、in、notin与文档描述一致校验规则in/notin的values不能为空exists/!的values必须为空/!的values长度必须恰好为 1最终通过ToMgoFilter转换为 MongoDB 查询条件作用在labels.key字段上in→$in、notin→$nin、exists/!→$exists、→ 精确相等、!→$ne多个 selector 之间以$and连接。也就是说标签过滤是在服务实例自身携带的 labels 字段上生效而不是对bk_host_id等内置字段生效调用时key必须与实例上已打标的标签键匹配。调用示例{ bk_biz_id: 1, page: { start: 0, limit: 1 }, bk_module_id: 56, bk_host_ids:[26,10], search_key: , selectors: [{ key: key1, operator: notin, values: [value1] },{ key: key1, operator: in, values: [value1, value2] }] }结合源码可以确认请求体与后端模型的映射关系。proc_server 侧的入参结构体为 metadata.GetServiceInstanceInModuleInputtype GetServiceInstanceInModuleInput struct { BizID int64 json:bk_biz_id ModuleID int64 json:bk_module_id HostIDs []int64 json:bk_host_ids Page BasePage json:page SearchKey *string json:search_key Selectors selector.Selectors json:selectors }其中search_key在后端以指针类型接收空字符串与不传在反序列化后的语义上等价于不做名称过滤因此示例中传search_key: 不会触发模糊搜索。响应结构与参数说明响应示例继承自原始文档{ result: true, code: 0, message: success, permission: null, data: { count: 1, info: [ { bk_biz_id: 1, id: 72, name: t1, bk_host_id: 26, bk_module_id: 62, creator: admin, modifier: admin, create_time: 2019-06-20T22:46:00.6908:00, last_time: 2019-06-20T22:46:00.6908:00, bk_supplier_account: 0 } ] } }响应参数说明参数名称参数类型描述resultbool请求成功与否。true:请求成功false请求失败codeint错误编码。 0表示success0表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataobject请求返回的数据data 字段说明参数名称参数类型描述countinteger总数infoarray返回结果info 字段说明参数名称参数类型描述idint服务实例IDnamestring服务实例名称bk_biz_idint业务IDbk_module_idint模块IDbk_host_idint主机IDcreatorstring本条数据创建者modifierstring本条数据的最后修改人员create_timestring创建时间last_timestring更新时间bk_supplier_accountstring开发商账号info 中的每个元素对应存储模型 metadata.ServiceInstance其中id是服务实例主键name在响应中即服务实例名称源码注释表明服务实例与主机、模块、进程模板存在绑定关系。需要注意count是符合过滤条件的总数而不是当前页返回条数分页遍历时应以count与page.start page.limit的推进配合使用。底层实现从路由到 MongoDB 查询下面按请求处理顺序拆解该接口的完整调用链便于排查查不到数据这类问题。1. 路由注册与权限校验接口路由在 proc_server 中注册为POST /findmany/proc/service_instance绑定处理器SearchServiceInstancesInModuleservice.go。权限层面serviceinstance.go 定义了findServiceInstancePattern资源类型为meta.ProcessServiceInstance动作FindMany业务 id 从请求体bk_biz_id提取DefaultBizIDGetter因此调用方必须同时具备该业务的访问权限与list_service_instance的资源权限。2. 处理器层参数校验与查询选项组装SearchServiceInstancesInModule 的处理逻辑反序列化入参后若bk_host_ids长度超过BKMaxPageSize1000直接报错通过input.Page.Validate(false)校验分页参数非法时返回CCErrCommPageLimitIsExceeded组装 ListServiceInstanceOption始终带上BusinessIDbk_module_id非 0 时转换为ModuleIDs: []int64{input.ModuleID}search_key、selectors、bk_host_ids原样透传。3. coreservice 存储层过滤条件的组装与执行请求经 coreAPI 到达 coreservice 的 processOperation.ListServiceInstance这是理解各参数底层行为的关键代码必选校验BusinessID 0时返回CCErrCommParamsInvalid对应文档中bk_biz_id的必选要求租户隔离过滤条件固定包含bk_biz_id与bk_supplier_account开发商账号即响应中的bk_supplier_account字段从源码结构看服务实例数据是按供应商账号维度隔离的主机过滤bk_host_ids映射为bk_host_id: {$in: [...]}是这些主机上任意一个存在服务实例即命中的语义模块过滤bk_module_id同样走$in内部以数组表达支持单值名称模糊搜索search_key被包装成正则.*search_key.*作用在name字段上$like因此它是子串包含语义而非前缀匹配且未转义正则元字符调用方传特殊符号时应留意匹配范围可能比预期宽标签过滤先执行Selectors.Validate()operator 非法、values 数量不合规都会在此拦截并返回CCErrCommParamsInvalid通过后ToMgoFilter()生成labels.key上的条件并与基础过滤合并查询执行先Find(filter).Count()得到总数再Fields(...).Sort(page.Sort).Start(page.Start).Limit(page.Limit).All()分页拉取实例数据表为cc_ServiceInstancetablenames.go最终组装成MultipleServiceInstance{Count, Info}返回对应响应中的data.count与data.info。4. 内部复用与相关接口同一个ListServiceInstance存储方法在仓库中被大量内部逻辑复用从源码结构看它不仅是开放 API 的后端也是进程管理各功能的公共查询底座创建服务实例前先按模块查已存在的实例做去重排除serviceinstance.go服务模板下发、进程模板差异计算等流程按service_template_id 模块维度分页拉取实例processinstance.go。与之相邻、可按场景替换使用的兄弟接口同样可在 bk_apigw_resources_bk-cmdb.yaml 中查到接口后端路径适用场景list_service_instance_by_host/api/v3/findmany/proc/service_instance/with_host已知单台主机查其关联的服务实例list_service_instance_by_set_template/api/v3/findmany/proc/service/set_template/list_service_instance/biz/{bk_biz_id}按集群模板set_template反查服务实例list_service_instance_detail/api/v3/findmany/proc/service_instance/details需要联动进程实例关系等详情时实践要点小结必选与上限bk_biz_id必选bk_host_ids单次最多 1000 个page.limit最大 500且start、limit均不能为负search_key 是模糊包含底层为.*key.*正则匹配实例名称做精确查找时应结合模块/主机条件收敛selectors 只过滤 labels过滤字段是labels.keykey必须与服务实例上已存在的标签键一致且各 operator 对values数量有严格校验数据隔离查询结果天然限定在bk_biz_id与当前供应商账号范围内跨业务、跨开发商的数据查不到属于预期行为限流网关侧默认 100 req/s 的令牌桶大租户批量翻页建议按count规划分页并在客户端侧做速率控制。参考文件API 文档list_service_instance、open API 网关定义、资源授权定义路由与处理器路由注册、SearchServiceInstancesInModule、权限配置数据模型ListServiceInstanceOption、GetServiceInstanceInModuleInput / ServiceInstance存储实现processOperation.ListServiceInstance、selector 过滤实现、分页校验赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 服务实例列表查询接口list_service_instance详解蓝鲸配置平台 bk cmdb 服务实例列表查询接口list_service_instance详解本指南基于蓝鲸智云配置平台BlueKing CMDBb后端企业应用运维蓝鲸配置平台 bk-cmdb API 指南按服务实例查询进程实例列表list_process_instance蓝鲸配置平台 bk cmdb API 指南按服务实例查询进程实例列表list_process_instance 导读 list_process_insta后端企业应用运维bk-cmdb 服务分类列表查询接口 list_service_category 详解从 API 网关到 Mongo 查询的完整链路bk cmdb 服务分类列表查询接口 list_service_category 详解从 API 网关到 Mongo 查询的完整链路本篇基于蓝鲸智云配置平台后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

bk-cmdb 开放 API 详解：list_service_instance 按业务查询服务实例列表

相关推荐

QOwnNotes Homepage 建议 API 接入指南：本地书签搜索引擎配置与源码原理

AI剪纸特效：工艺语义建模与负空间拓扑生成

Odoo 17数据字典中文版：字段类型、表结构及报表查询避坑指南

更多资讯

两相短路故障Matlab/Simulink仿真模型搭建与波形分析详解

带注解的深度学习入门源码：MNIST神经网络训练与调参避坑指南

8086系统结构深度解析：从寄存器到分段寻址的底层原理

微信小程序闹钟源码实战：从定时逻辑到真机唤醒的完整避坑指南

C语言手写FFT：从DFT到O(N log N)的实战指南

易语言大漠模块封装与免注册调用实战指南

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？