kibana-streams

Kibana Streams

通过 Kibana Streams REST API 读取流元数据、设置和附件，并管理流的生命周期（启用、禁用、重新同步）。Streams 是在 Kibana 中管理数据的一种实验性方式，API 和行为可能会发生变化。本技能仅涵盖读取操作和生命周期操作；创建、更新、删除、分叉及其他变更操作可能会在后续版本中添加。

有关详细的端点和参数，请参阅 references/streams-api-reference.md。

使用场景

• 列出所有流，或获取单个流的定义和元数据
• 读取流的摄取设置，或查询流的 ES|QL 定义
• 列出关联到某个流的附件（仪表板、规则、SLO）
• 启用、禁用或重新同步流

前提条件

项目	描述
Kibana URL	Kibana 端点（例如 https://localhost:5601 或 Cloud 部署 URL）
身份验证	API 密钥或基本身份验证（参阅 elasticsearch-authn 技能）
权限	读取操作需要 read_stream；生命周期 API 需要 manage_stream

在非默认空间中操作时，请使用空间范围路径 /s/{space_id}/api/streams。有关角色配置（Kibana 功能权限和 Elasticsearch 级权限），请参阅 Streams 所需权限。

API 基础路径和标头

• 基础路径： 向 <kibana_url>/api/streams 发送 GET 或 POST 请求（在空间中操作时使用 /s/<space_id>/api/streams）。
• 读取操作： 通常不需要额外的标头；请遵循每个端点的 官方 API 文档。
• 生命周期操作： POST /api/streams/_disable、_enable 和 _resync 会修改数据；请根据 Kibana 版本的要求发送 kbn-xsrf: true （或等效标头）。

操作（读取 + 生命周期）

读取

操作	方法	路径
获取流列表	GET	/api/streams
获取单个流	GET	/api/streams/{name}
获取摄取流设置	GET	/api/streams/{name}/_ingest
获取查询流设置	GET	/api/streams/{name}/_query
获取流附件	GET	/api/streams/{streamName}/attachments

生命周期

操作	方法	路径
禁用流	POST	/api/streams/_disable
启用流	POST	/api/streams/_enable
重新同步流	POST	/api/streams/_resync

路径参数：{name} 和 {streamName} 都是流标识符（值相同；API 文档中使用了这两种名称）。

生命周期与保留期（摄取设置）

摄取设置（GET /api/streams/{name}/_ingest）包含两个独立的生命周期部分：

• 流生命周期（ingest.lifecycle）— 控制流数据的保留时长。使用 lifecycle.dsl.data_retention（例如 "30d"）设置明确的保留期，或对子流使用 lifecycle.inherit。用户询问“设置保留期”“更新保留期”或“更改流的保留期”时，通常指的就是这一项。
• 失败存储生命周期（ingest.failure_store.lifecycle）— 仅控制失败文档（未成功处理的文档）的保留时长。除非用户明确提及失败存储或失败文档的保留期，否则很少需要更改这一项。

用户要求设置或更新保留期时，应针对流的主生命周期（lifecycle.dsl.data_retention），而不是失败存储，除非用户明确询问失败存储或失败文档。

示例

列出流

curl -X GET "${KIBANA_URL}/api/streams" \
  -H "Authorization: ApiKey <base64-api-key>"

获取单个流

curl -X GET "${KIBANA_URL}/api/streams/my-stream" \
  -H "Authorization: ApiKey <base64-api-key>"

获取查询流设置

curl -X GET "${KIBANA_URL}/api/streams/my-stream/_query" \
  -H "Authorization: ApiKey <base64-api-key>"

获取流附件

# Attachments (dashboards, rules, SLOs linked to the stream)
curl -X GET "${KIBANA_URL}/api/streams/my-stream/attachments" \
  -H "Authorization: ApiKey <base64-api-key>"

禁用、启用或重新同步流

# Disable streams (request body per API docs) — deletes wired stream data; warn and confirm before proceeding
curl -X POST "${KIBANA_URL}/api/streams/_disable" \
  -H "Authorization: ApiKey <base64-api-key>" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{}'

# Enable streams
curl -X POST "${KIBANA_URL}/api/streams/_enable" \
  -H "Authorization: ApiKey <base64-api-key>" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{}'

# Resync streams
curl -X POST "${KIBANA_URL}/api/streams/_resync" \
  -H "Authorization: ApiKey <base64-api-key>" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{}'

有关请求和响应正文（例如需要时 _disable/_enable/_resync 的请求正文），请查看 Streams API 操作页面。

指南

• 用户要求设置或更新保留期时，应默认理解为流的数据保留期（ingest.lifecycle / lifecycle.dsl.data_retention）。除非用户明确询问失败存储或失败文档，否则不要只更改失败存储的保留期。
• 此技能不支持其他变更操作（创建、更新、删除、分叉、附件管理等）。完整的延后操作列表请参阅 references/streams-api-reference.md。
• **重大事件及其检测查询不在本技能范围内。**有关重大事件、SigEvents 或知识指标的请求，属于专用的重大事件技能，该技能使用 platform.sig_events.* Agent Builder 工具。/api/streams/{name}/queries 和 /api/streams/{name}/significant_events 端点已弃用，并计划从 Kibana 中移除——请勿在此处使用。
• 请勿将查询流与重大事件查询混淆。/api/streams/{name}/_query 是查询流（与 wired 和 classic 并列的一种流类型）的 ES|QL 定义；它与检测查询无关。
• **禁用流可能会导致 wired 流的数据丢失。**禁用 API 会删除 wired 流数据（classic 流数据会保留）。调用禁用操作前，请提醒用户并确认他们了解风险（且已备份数据，或不再需要这些数据）。
• 如果用户只需检查流状态，请优先使用读取操作；只有在需要启用、禁用或重新同步流时，才使用生命周期 API。