后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文基于蓝鲸智云配置平台BlueKing CMDB开源仓库的 API 网关文档 list_service_instance_by_host.md完整讲解list_service_instance_by_host接口的请求参数、分页规则、调用示例与响应结构并结合proc_server、coreservice源码揭示其底层查询链路与权限模型帮助读者在蓝鲸 CMDB 的进程服务管理场景中按主机维度快速获取服务实例信息用于资产盘点、进程拓扑梳理或二次开发集成。一、接口概述list_service_instance_by_host是蓝鲸 CMDB 开放 API 中用于「根据主机 id 获取绑定到主机上的服务实例列表」的接口属于**进程服务管理proc**模块的查询类能力。在 CMDB 的进程服务模型中服务实例Service Instance是主机Host与进程模板绑定后产生的运行实体一台主机上可以运行多个进程主机绑定服务模板后即生成对应的服务实例服务实例归属于某个模块module。该接口正是面向这种主机 → 服务实例的反向查询场景设计的常用于前端「主机详情页」展示该主机上运行的进程服务列表自动化平台按主机维度同步、盘点进程实例排查主机上服务实例与模板、模块的对应关系。接口对应的完整请求路径为POST /api/v3/findmany/proc/service_instance/with_host该映射关系定义在 bk_apigw_resources_bk-cmdb.yaml 中/api/v3/findmany/proc/service_instance/with_host: post: operationId: list_service_instance_by_host description: 通过主机查询关联的服务实例列表 x-bk-apigateway-resource: isPublic: false allowApplyPermission: true backend: type: HTTP method: post path: /api/v3/findmany/proc/service_instance/with_host pluginConfigs: - type: bk-rate-limit yaml: | rates: __default: - period: 1 tokens: 100从中可以看到该资源是**非公开isPublic: false**的调用方需要申请权限后端透传至 CMDB 的proc_server服务并配置了默认限流策略每秒 100 令牌。二、输入参数说明接口采用 HTTP POST JSON Body 方式传参完整参数如下参数名称参数类型必选描述bk_biz_idint是业务 idbk_host_idint是主机 ID用于获取绑定到该主机的服务实例信息pageobject否分页查询条件2.1 page 子参数参数名称参数类型必选描述startint是记录开始位置从 0 开始limitint是每页限制条数最大 500从源码数据结构看服务端实际接收的输入体比文档参数更完整。在 process.go 中定义了ListServiceInstancesWithHostInput// ListServiceInstancesWithHostInput TODO type ListServiceInstancesWithHostInput struct { BizID int64 json:bk_biz_id HostID int64 json:bk_host_id SearchKey *string json:search_key Selectors selector.Selectors json:selectors Page BasePage json:page }除了文档列出的bk_biz_id、bk_host_id、page之外该输入结构还支持两个可选字段search_key对服务实例名称name的模糊搜索关键字后端会将其转换为正则表达式做匹配selectors基于标签labels的查询选择器用于按标签过滤服务实例。这两个字段在文档示例中未展示但属于真实可用的扩展查询能力。2.2 必填校验服务端对参数的校验逻辑位于 serviceinstance.go 的ListServiceInstancesWithHost处理函数中if input.HostID 0 { ctx.RespErrorCodeOnly(common.CCErrCommHTTPInputInvalid, list service instances with host, but got empty host id. input: %v, input) return }即bk_host_id为 0未传或传空时直接返回输入参数非法错误因此调用方务必保证该字段有效。而bk_biz_id的合法性则由 coreservice 层的查询逻辑兜底校验详见下文「底层查询链路」小节。分页参数page对应的BasePage定义于 page.go包含sort、limit、start、enable_count等字段limit受全局最大分页条数BKMaxPageSize约束文档中标注的「最大 500」与该限制保持一致。三、调用示例请求示例JSON Body{ bk_biz_id: 1, page: { start: 0, limit: 1 }, bk_host_id: 26 }要点说明bk_biz_id与bk_host_id组合定位业务 1 中的主机 26page.start 0表示从第一条记录开始返回page.limit 1表示本次只取 1 条可用于验证接口连通性或做分页遍历实际使用时可将limit调大不超过 500以减少请求次数。若需要利用扩展查询能力可追加可选参数例如按名称模糊搜索并结合标签过滤{ bk_biz_id: 1, bk_host_id: 26, search_key: test, selectors: [ { key: test1, operator: exists } ], page: { start: 0, limit: 10 } }四、响应示例与数据结构4.1 完整响应示例{ result: true, code: 0, message: success, permission: null, data: { count: 1, info: [ { bk_biz_id: 1, id: 1, name: test, labels: { test1: 1 }, service_template_id: 32, bk_host_id: 26, bk_module_id: 12, creator: admin, modifier: admin, create_time: 2021-12-31T03:11:54.992Z, last_time: 2021-12-31T03:11:54.992Z, bk_supplier_account: 0 } ] } }4.2 顶层响应字段参数名称参数类型描述resultbool请求成功与否。true 表示成功false 表示失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败时返回的错误信息permissionobject权限信息无权限限制时为 nulldataobject请求返回的数据4.3 data 字段参数名称参数类型描述countint满足条件的总数infoarray返回结果列表4.4 info 数组元素字段参数名称参数类型描述idint服务实例 IDnamestring服务实例名称bk_module_idint服务实例所属模块模型idservice_template_idint服务模板 IDlabelsmap标签信息bk_host_idint主机 idcreatorstring本条数据创建者modifierstring本条数据的最后修改人员create_timestring创建时间last_timestring更新时间bk_supplier_accountstring开发商供应商账号4.5 服务实例数据结构的源码印证上述响应字段在 process.go 中由ServiceInstance结构体直接定义字段一一对应// ServiceInstance is a service, which created when a host binding with a service template. type ServiceInstance struct { BizID int64 field:bk_biz_id json:bk_biz_id bson:bk_biz_id ID int64 field:id json:id bson:id Name string field:name json:name bson:name Labels selector.Labels field:labels json:labels bson:labels // the template id can not be updated, once the service is created. // it can be 0 when the service is not created with a service template. ServiceTemplateID int64 field:service_template_id json:service_template_id bson:service_template_id HostID int64 field:bk_host_id json:bk_host_id bson:bk_host_id // the module that this service belongs to. ModuleID int64 field:bk_module_id json:bk_module_id bson:bk_module_id Creator string field:creator json:creator bson:creator Modifier string field:modifier json:modifier bson:modifier CreateTime time.Time field:create_time json:create_time bson:create_time LastTime time.Time field:last_time json:last_time bson:last_time SupplierAccount string field:bk_supplier_account json:bk_supplier_account bson:bk_supplier_account }值得注意的语义细节service_template_id的注释明确说明服务实例一旦创建其关联的模板 ID 便不可更新同时该字段可以为 0表示该服务实例并非通过服务模板创建例如手工创建的裸服务实例服务实例物理存储于 MongoDB 的cc_ServiceInstance集合该集合名在 tablenames.go 中定义为BKTableNameServiceInstance cc_ServiceInstancecreate_time/last_time在 Go 侧为time.Time类型序列化后以 RFC3339 格式如2021-12-31T03:11:54.992Z输出即文档示例所示的时间戳格式。五、完整请求链路与底层实现5.1 从网关到 coreservice 的调用链从源码可以还原该接口的完整调用链API 网关层bk_apigw_resources_bk-cmdb.yaml将operationId: list_service_instance_by_host映射到后端路径/api/v3/findmany/proc/service_instance/with_host并套用默认限流bk-rate-limit1 秒 100 令牌。proc_server 路由层service.go 注册了内部路由POST /findmany/proc/service_instance/with_host绑定处理器ListServiceInstancesWithHost。proc_server 业务处理层ListServiceInstancesWithHostserviceinstance.go解码输入、校验bk_host_id非空然后构造ListServiceInstanceOption并调用ps.CoreAPI.CoreService().Process().ListServiceInstance(...)将查询下沉至 coreservice 的进程服务接口。coreservice 实现层coreservice的 process 操作实现ListServiceInstanceservice_instance.go真正执行 MongoDB 查询并组装返回结果。其中第 2 步的路由注册源码如下utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /findmany/proc/service_instance/with_host, Handler: ps.ListServiceInstancesWithHost})5.2 底层查询逻辑coreservice 实现coreservice 的ListServiceInstance是理解该接口行为的关键其核心逻辑为业务隔离若BusinessID 0直接返回参数非法错误对应bk_biz_id必填查询条件中固定拼接bk_biz_id与bk_supplier_account供应商账号过滤实现业务级数据隔离主机过滤bk_host_id会被包装为bk_host_id ∈ [hostID]的 IN 条件service_instance.go本质是按主机 ID 在服务实例集合中做精确匹配名称模糊搜索当传入search_key时会将其转换为正则.*key.*的 LIKE 条件作用于name字段标签选择器selectors经校验后转换为 MongoDB 标签过滤条件与已有条件合并分页与排序使用page.sort排序、page.start偏移、page.limit限制条数查询并先Count统计总数最终返回MultipleServiceInstance{Count: total, Info: instances}。该实现同时印证了响应中count总数与info当前页数据两个字段的来源count来自独立的Count查询info来自带分页的All查询二者在一次请求内完成。5.3 权限模型该接口的权限控制定义在 serviceinstance.go 的鉴权解析器中{ Name: findServiceInstanceByHostPattern, Description: 根据主机服务实例, Pattern: /api/v3/findmany/proc/service_instance/with_host, HTTPMethod: http.MethodPost, BizIDGetter: DefaultBizIDGetter, ResourceType: meta.ProcessServiceInstance, ResourceAction: meta.FindMany, }即该请求会被映射为对服务实例资源ProcessServiceInstance的 findmany批量查询操作进行鉴权业务 ID 取自请求中的bk_biz_id。这解释了为何 API 网关配置中该资源isPublic: false且allowApplyPermission: true调用方需要拥有对应业务下服务实例的查询权限或申请该资源权限方可成功调用。六、前端调用示例仓库内实际用法该接口在蓝鲸 CMDB 前端也有直接对应调用定义于 service-instance.jsconst actions { getHostServiceInstances(context, { params, config }) { return $http.post(findmany/proc/service_instance/with_host, params, config) }, // ... }前端通过 Vuex actiongetHostServiceInstances封装了同一后端路径的 POST 请求服务于主机详情页中服务实例列表的展示场景这也验证了该接口「主机详情 → 服务实例列表」的典型使用方式。七、常见问题与使用建议请求失败并提示主机 ID 非法确认bk_host_id字段已正确传入且不为 0参考上文input.HostID 0的校验逻辑。分页 limit 超限page.limit最大为 500超过该值会被判为非法分页参数分页遍历时可基于data.count计算总页数用start递增翻页。查询结果为空确认主机是否已绑定服务模板并生成服务实例注意service_template_id可为 0非模板创建的服务实例不能仅凭模板 ID 判断。权限不足该资源默认非公开需在 API 网关侧申请list_service_instance_by_host资源权限且用户需具备对应业务下服务实例的查询权限。善用扩展参数需要按名称或标签筛选时可通过search_key与selectors在请求层过滤减少客户端二次处理成本。八、参考链接接口文档原文list_service_instance_by_host.mdAPI 网关资源定义bk_apigw_resources_bk-cmdb.yaml输入/输出数据结构定义process.go、process.goproc_server 处理器与路由serviceinstance.go、service.gocoreservice 底层查询实现service_instance.go权限解析定义serviceinstance.go前端封装调用service-instance.js数据表名定义tablenames.go赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云配置平台 bk-cmdb API 实战list_service_instance_by_host 查询主机绑定服务实例列表蓝鲸智云配置平台 bk cmdb API 实战list_service_instance_by_host 查询主机绑定服务实例列表 导读 本指南深入讲解蓝鲸智后端企业应用运维蓝鲸配置平台 bk-cmdb API 指南按服务实例查询进程实例列表list_process_instance蓝鲸配置平台 bk cmdb API 指南按服务实例查询进程实例列表list_process_instance 导读 list_process_insta后端企业应用运维蓝鲸配置平台 bk-cmdb 服务实例列表查询接口list_service_instance详解蓝鲸配置平台 bk cmdb 服务实例列表查询接口list_service_instance详解 本指南基于蓝鲸智云配置平台BlueKing CMDBb后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考