Documentation

Kapacitor

Kapacitor HTTP API 参考文档

使用Kapacitor HTTP API管理Kapacitor任务、模板、录音，收集故障排除数据等。

一般信息

  • Kapacitor 默认在 端口 9092 提供 HTTP API。
  • 以下每个部分定义了可用的API端点及其输入和输出。
  • 所有请求都使用基础路径 /kapacitor/v1/ 进行版本管理和命名空间划分。
在本节中

HTTP响应代码

所有请求都可以返回这些响应代码：

响应代码含义
2xx请求成功，内容取决于请求。
4xx无效请求，参考错误以了解请求的具体问题。重复请求将继续返回相同的错误。
5xx服务器无法处理请求，请参考错误原因。重复请求可能会在服务器问题解决后成功。

错误

所有请求可以以以下格式返回JSON，以提供关于失败请求的更多信息。

{ "error" : "error message" }

查询参数与 JSON 主体

查询参数仅用于GET请求。
所有其他请求期望在JSON主体中包含参数。

这个 /kapacitor/v1/write 端点是这个规则的一个例外，因为 Kapacitor 与 InfluxDB /write 端点兼容。

当创建资源时，Kapacitor API服务器返回一个 link 对象，其 href 为资源的链接。 客户端应该能够使用从之前的调用中提供的链接而无需任何路径操作。

标识符

为了让您控制ID，Kapacitor API 允许客户端为各种资源指定ID。如果您不指定ID，Kapacitor会为该资源生成一个随机的UUID。

所有ID必须匹配以下正则表达式（基本上是数字、unicode字母、-、. 和 _。）:

^[-\._\p{L}0-9]+$`

向后兼容性

目前，Kapacitor 处于 1.x 版本，确保所有新版本将与以前的版本向后兼容。这直接适用于 API。可能会对 API 进行更新，但在 1.x 版本中，现有的端点将不会以向后不兼容的方式进行更改。

技术预览

当一个新特性被添加到Kapacitor时，它可能会在“技术预览”版本中添加几个小版本，然后再被提升为完全支持的v1特性。技术预览特性在被提升为v1特性之前，可能会以向后不兼容的方式进行更改。技术预览允许新特性在保持定期发布的同时成熟。

为了清楚哪些API的特性处于技术预览中，使用基础路径 /kapacitor/v1preview。 如果您希望预览这些新特性，请在请求中使用路径 /kapacitor/v1preview 而不是 /kapacitor/v1。 所有v1端点都可以在v1preview路径下使用，因此您的客户端无需配置多个路径。 技术预览端点仅在v1preview路径下可用。

使用技术预览意味着您可能需要更新您的客户端，以应对预览端点的重大变化。

写入数据

Kapacitor 接受通过 HTTP 以 InfluxData 的 Line Protocol 数据格式 写入数据。kapacitor/v1/write 终端在本质上与 InfluxDB /write 终端相同。

查询参数目的
db写入的数据库名称。
rp写入的保留策略名称。

Kapacitor 根据其数据库和保留策略对所有点进行范围划分。 因此，您必须为写入指定 rp，以便 Kapacitor 使用正确的保留策略。

示例

将数据写入Kapacitor。

POST /kapacitor/v1/write?db=DB_NAME&rp=RP_NAME
cpu,host=example.com value=87.6

为了与等效的 InfluxDB /write 端点保持兼容，/write 端点是 /kapacitor/v1/write 端点的别名。

POST /write?db=DB_NAME&rp=RP_NAME
cpu,host=example.com value=87.6

管理任务

任务表示Kapacitor要执行的工作。 任务由其id、类型、TICK脚本和其被允许访问的数据库保留策略对的列表定义。

定义或更新任务

要定义一个任务，请向/kapacitor/v1/tasks端点发送POST请求。
如果任务已经存在，则使用PATCH方法修改任务的任何属性。

使用具有以下选项的JSON对象定义一个任务：

属性目的
id任务的唯一标识符。如果为空，将选择一个随机 ID。
模板ID(可选) 用于替代指定TICKscript和类型的模板ID。
类型任务类型： stream 或 batch。
dbrps任务被允许访问的数据库保留策略对列表。
script脚本的内容。
状态可以是 enabled 或 disabled。
vars一组变量，用于覆盖TICKscript中定义的任何变量。

使用 PATCH 时，如果任何属性缺失，任务将保持不变。

注意： 在修补任务时，正在运行的任务不会做出任何更改。 任务必须被禁用并重新启用，才能使更改生效。

变量

vars对象的形式如下：

{
    "field_name" : {
        "value": <VALUE>,
        "type": <TYPE>
    },
    "another_field" : {
        "value": <VALUE>,
        "type": <TYPE>
    }
}

以下是有效类型及示例值的表格。

类型示例值描述
布尔值真“真” 或 “假”
整数42任何整数值
浮点数2.5 或 67任何数字值
持续时间“1秒” 或 1000000000任何以纳秒为单位的整数值或 influxql 持续时间字符串（即 10000000000 是 10秒）
字符串“a string”任何字符串值
正则表达式“^abc.*xyz”表示有效的 Go 正则表达式的任何字符串值 https://golang.org/pkg/regexp/
lambda“"value" > 5”任何有效的 TICKscript lambda 表达式的字符串
星号""不需要值，星号类型变量表示TICKscript中的字面量 * (即 .groupBy(*))
list[{“type”: TYPE, “value”: VALUE}]一个 var 对象的列表。当前列表只能包含字符串或星号变量

示例

使用 id 值 TASK_ID 创建一个新任务。要从模板创建任务，请添加 template-id。

POST /kapacitor/v1/tasks
{
    "id" : "TASK_ID",
    "template-id" : "TEMPLATE_ID", 
    "type" : "stream",
    "dbrps": [{"db": "DATABASE_NAME", "rp" : "RP_NAME"}],
    "script": "stream\n    |from()\n        .measurement('cpu')\n",
    "vars" : {
        "var1": {
            "value": 42,
            "type": "float"
        }
    }
}

响应任务详细信息。

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/tasks/TASK_ID"},
    "id" : "TASK_ID",
    "template-id" : "TEMPLATE_ID",
    "type" : "stream",
    "dbrps" : [{"db": "DATABASE_NAME", "rp" : "RP_NAME"}],
    "script" : "stream\n    |from()\n        .measurement('cpu')\n",
    "dot" : "digraph TASK_ID { ... }",
    "vars" : {
        "var1": {
            "value": 42,
            "type": "float"
        }
    },
    "status" : "enabled",
    "executing" : true,
    "error" : "",
    "created": "2006-01-02T15:04:05Z07:00",
    "modified": "2006-01-02T15:04:05Z07:00",
    "stats" : {},
    "template-id": "TASK_ID"
}

仅修改任务的 dbrps。

PATCH /kapacitor/v1/tasks/TASK_ID
{
    "dbrps": [{"db": "NEW_DATABASE_NAME", "rp" : "NEW_RP_NAME"}]
}

注意：设置任何 DBRP 将覆盖所有存储的 DBRP。设置任何变量将覆盖所有存储的变量。

启用现有任务。

PATCH /kapacitor/v1/tasks/TASK_ID
{
    "status" : "enabled",
}

禁用现有任务。

PATCH /kapacitor/v1/tasks/TASK_ID
{
    "status" : "disabled",
}

定义一个在创建时启用的新任务。

POST /kapacitor/v1/tasks
{
    "id" : "TASK_ID",
    "template-id" : "TEMPLATE_ID",
    "type" : "stream",
    "dbrps" : [{"db": "DATABASE_NAME", "rp" : "RP_NAME"}],
    "script" : "stream\n    |from()\n        .measurement('cpu')\n",
    "status" : "enabled"
}

响应包含创建的任务。

{
    "id" : "TASK_ID",
    "template-id" : "TEMPLATE_ID",
    "link" : {"rel": "self", "href": "/kapacitor/v1/tasks/TASK_ID"}
}

响应

代码意义
200任务已创建，包含任务信息。
404任务不存在

获取一个任务

要获取有关任务的信息，请向 /kapacitor/v1/tasks/TASK_ID 端点发出 GET 请求。

查询参数默认值目的
点视图属性可以是 labels 或 attributes。标签的可读性较差，但会正确呈现包含在标签中的所有信息。
脚本格式已格式化可以是 formatted 或 raw 之一。Raw 将返回与定义时完全相同的脚本。Formatted 将首先格式化脚本。
replay-id运行重放的可选ID。返回的任务信息将基于运行重放的任务上下文。

一个任务除了以上列出的属性外，还有这些只读属性。

属性描述
dotGraphViz DOT 语法格式化的任务DAG表示。
执行中任务是否正在执行中。
错误执行任务时遇到的任何错误。
stats关于任务的统计信息地图。
created任务首次创建的日期
修改时间任务最后修改的日期
last-enabled任务最后一次设置为状态 enabled 的日期

示例

使用默认值获取任务信息。如果任务与模板相关联，则模板 ID 会包含在响应中。

GET /kapacitor/v1/tasks/TASK_ID

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/tasks/TASK_ID"},
    "id" : "TASK_ID",
    "template-id" : "TEMPLATE_ID",
    "type" : "stream",
    "dbrps" : [{"db": "DATABASE_NAME", "rp" : "RP_NAME"}],
    "script" : "stream\n    |from()\n        .measurement('cpu')\n",
    "dot" : "digraph TASK_ID { ... }",
    "status" : "enabled",
    "executing" : true,
    "error" : "",
    "created": "2006-01-02T15:04:05Z07:00",
    "modified": "2006-01-02T15:04:05Z07:00",
    "last-enabled": "2006-01-03T15:04:05Z07:00",
    "stats" : {},
    "template-id": "TASK_ID"
}

仅使用DOT内容中的标签获取有关任务的信息，并跳过格式步骤。

GET /kapacitor/v1/tasks/TASK_ID?dot-view=labels&script-format=raw

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/tasks/TASK_ID"},
    "id" : "TASK_ID",
    "template-id" : "TEMPLATE_ID",
    "type" : "stream",
    "dbrps" : [{"db": "DATABASE_NAME", "rp" : "RP_NAME"}],
    "script" : "stream|from().measurement('cpu')",
    "dot" : "digraph TASK_ID { ... }",
    "status" : "enabled",
    "executing" : true,
    "error" : "",
    "created": "2006-01-02T15:04:05Z07:00",
    "modified": "2006-01-02T15:04:05Z07:00",
    "last-enabled": "2006-01-03T15:04:05Z07:00",
    "stats" : {}
}

响应

代码意义
200成功
404任务不存在

删除任务

要删除一个任务，向 /kapacitor/v1/tasks/TASK_ID 端点发出 DELETE 请求。

DELETE /kapacitor/v1/tasks/TASK_ID

响应

代码意义
204成功

注意： 删除不存在的任务并不是一个错误，将返回204成功。

列出任务

要获取关于多个任务的信息，向 /kapacitor/v1/tasks 端点发送 GET 请求。

查询参数默认值目的
模式根据模式过滤结果。使用标准的shell glob匹配，详细信息请参见此处。
字段要返回的字段列表。如果为空，则返回所有字段。字段 id 和 link 始终返回。
点视图属性可以是 labels 或 attributes。标签的可读性较差，但会正确呈现包含在标签中的所有信息。
脚本格式已格式化可以是 formatted 或 raw 之一。Raw 将返回与定义时完全相同的脚本。Formatted 将首先格式化脚本。
offset0用于分页任务的偏移计数。
limit100返回的最大任务数量。

示例

获取所有任务列表的详细信息。

GET /kapacitor/v1/tasks

{
    "tasks" : [
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/tasks/TASK_ID"},
            "id" : "TASK_ID",
            "type" : "stream",
            "dbrps" : [{"db": "DATABASE_NAME", "rp" : "RP_NAME"}],
            "script" : "stream|from().measurement('cpu')",
            "dot" : "digraph TASK_ID { ... }",
            "status" : "enabled",
            "executing" : true,
            "error" : "",
            "stats" : {},
            "template-id" : "TEMPLATE_ID"
        },
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/tasks/ANOTHER_TASK_ID"},
            "id" : "ANOTHER_TASK_ID",
            "type" : "stream",
            "dbrps" : [{"db": "DATABASE_NAME", "rp" : "RP_NAME"}],
            "script" : "stream|from().measurement('cpu')",
            "dot" : "digraph ANOTHER_TASK_ID{ ... }",
            "status" : "disabled",
            "executing" : true,
            "error" : "",
            "stats" : {},
            "template-id" : "TEMPLATE_ID"
        }
    ]
}

可选地，您可以指定一个 glob pattern 来仅列出匹配的任务。

GET /kapacitor/v1/tasks?pattern=TASK*

{
    "tasks" : [
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/tasks/TASK_ID"},
            "id" : "TASK_ID",
            "type" : "stream",
            "dbrps" : [{"db": "DATABASE_NAME", "rp" : "RP_NAME"}],
            "script" : "stream|from().measurement('cpu')",
            "dot" : "digraph TASK_ID { ... }",
            "status" : "enabled",
            "executing" : true,
            "error" : "",
            "stats" : {},
            "template-id" : "TEMPLATE_ID"
        }
    ]
}

获取所有任务，但仅获取状态、执行和错误字段。

GET /kapacitor/v1/tasks?fields=status&fields=executing&fields=error

{
    "tasks" : [
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/tasks/TASK_ID"},
            "id" : "TASK_ID",
            "status" : "enabled",
            "executing" : true,
            "error" : "",
        },
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/tasks/ANOTHER_TASK_ID"},
            "id" : "ANOTHER_TASK_ID",
            "status" : "disabled",
            "executing" : true,
            "error" : "",
        }
    ]
}

响应

代码意义
200成功

注意：如果模式不匹配任何任务，将返回一个空列表，并且状态为200成功。

自定义任务 HTTP 端点

在TICKscript中，可以通过HTTPOut节点暴露近期数据的缓存。数据可在路径/kapacitor/v1/tasks/TASK_ID/ENDPOINT_NAME获取。

示例

对于TICKscript：

stream
    |from()
        .measurement('cpu')
    |window()
        .period(60s)
        .every(60s)
    |httpOut('mycustom_endpoint')

GET /kapacitor/v1/tasks/TASK_ID/mycustom_endpoint

{
    "series": [
        {
            "name": "cpu",
            "columns": [
                "time",
                "value"
            ],
            "values": [
                [
                    "2015-01-29T21:55:43.702900257Z",
                    55
                ],
                [
                    "2015-01-29T21:56:43.702900257Z",
                    42
                ],
            ]
        }
    ]
}

输出与对InfluxDB进行数据查询的结果相同。

管理模板

您还可以定义任务模板。 任务模板由模板 TICKscript 和任务类型定义。

定义模板

要定义一个模板 POST 到 /kapacitor/v1/templates 端点。
如果模板已经存在，则使用 PATCH 方法修改模板的任何属性。

使用具有以下选项的JSON对象定义模板：

属性目的
id模板的唯一标识符。如果为空，将选择一个随机ID。
类型模板类型： stream 或 batch。
script脚本的内容。

使用PATCH时，如果缺少任何选项，将保持不修改。

更新模板

更新现有模板时，所有相关任务将用新的模板定义重新加载。 重新加载相关任务时，如果有错误，将返回第一个错误。 如果发生错误，任何已更新为新定义的任务将恢复为旧定义。 这确保了一个模板的所有相关任务要么一起成功，要么一起失败。

因此，如果模板引入了 TICKscript 中的重大变更，您将无法更新该模板。 为了以破坏性的方式更新模板，您有两个选项：

  1. 创建一个新模板，并将每个任务重新分配给新模板，必要时更新任务变量。
  2. 如果破坏性更改是向前兼容的（即添加了一个新的必需变量），首先更新每个任务所需的变量，然后在所有任务准备好后更新模板。

示例

创建一个新的模板，ID为 TEMPLATE_ID。

POST /kapacitor/v1/templates
{
    "id" : "TEMPLATE_ID",
    "type" : "stream",
    "script": "stream\n    |from()\n        .measurement('cpu')\n"
}

使用模板 id 和 link 的响应。

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/templates/TASK_ID"},
    "id" : "TASK_ID",
    "type" : "stream",
    "script" : "stream\n    |from()\n        .measurement('cpu')\n",
    "dot" : "digraph TASK_ID { ... }",
    "error" : "",
    "created": "2006-01-02T15:04:05Z07:00",
    "modified": "2006-01-02T15:04:05Z07:00",
}

仅修改模板的脚本。

PATCH /kapacitor/v1/templates/TEMPLATE_ID
{
    "script": "stream|from().measurement('mem')"
}

响应

代码意义
200模板已创建，包含模板信息。
404模板不存在

获取模板

要获取有关模板的信息，请向 /kapacitor/v1/templates/TEMPLATE_ID 端点发送 GET 请求。

查询参数默认值目的
脚本格式已格式化可以是 formatted 或 raw 之一。Raw 将返回与定义时完全相同的脚本。Formatted 将首先格式化脚本。

一个模板除了上述的属性外，还具有这些只读属性。

属性描述
varsTICKscript中命名变量的集合，包括它们的类型、默认值和描述。
dotGraphViz DOT 语法格式化的模板DAG表示。注意：标签与属性没有关系，因为模板从未执行。
错误读取模板时遇到的任何错误。
created模板首次创建的日期
修改时间模板最后修改的日期

示例

获取有关模板的默认信息。

GET /kapacitor/v1/templates/TEMPLATE_ID

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/templates/TEMPLATE_ID"},
    "id" : "TASK_ID",
    "type" : "stream",
    "script" : "var x = 5\nstream\n    |from()\n        .measurement('cpu')\n",
    "vars": {"x":{"value": 5, "type":"int", "description": "threshold value"}},
    "dot" : "digraph TASK_ID { ... }",
    "error" : "",
    "created": "2006-01-02T15:04:05Z07:00",
    "modified": "2006-01-02T15:04:05Z07:00",
}

响应

代码意义
200成功
404模板不存在

删除模板

要删除模板，请向 /kapacitor/v1/templates/TEMPLATE_ID 端点发送 DELETE 请求。

注意: 删除模板会使所有关联的任务变为孤立状态。孤立任务的当前状态将保持不变，但孤立任务将无法被启用。

DELETE /kapacitor/v1/templates/TEMPLATE_ID

响应

代码意义
204成功

注意：删除不存在的模板不是错误，并将返回204成功。

列表模板

要获取有关多个模板的信息，请向 /kapacitor/v1/templates 接口发出 GET 请求。

查询参数默认值目的
模式根据模式过滤结果。使用标准的shell glob匹配，详细信息请参见此处。
字段要返回的字段列表。如果为空，则返回所有字段。字段 id 和 link 始终返回。
脚本格式已格式化可以是 formatted 或 raw 之一。Raw 将返回与定义时完全相同的脚本。Formatted 将首先格式化脚本。
offset0用于在模板中分页的偏移计数。
limit100返回的模板的最大数量。

示例

获取所有模板。

GET /kapacitor/v1/templates

{
    "templates" : [
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/templates/TEMPLATE_ID"},
            "id" : "TEMPLATE_ID",
            "type" : "stream",
            "script" : "stream|from().measurement('cpu')",
            "dot" : "digraph TEMPLATE_ID { ... }",
            "error" : ""
        },
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/templates/ANOTHER_TEMPLATE_ID"},
            "id" : "ANOTHER_TEMPLATE_ID",
            "type" : "stream",
            "script" : "stream|from().measurement('cpu')",
            "dot" : "digraph ANOTHER_TEMPLATE_ID{ ... }",
            "error" : ""
        }
    ]
}

可选择性地指定一个 glob pattern 以仅列出匹配的模板。

GET /kapacitor/v1/template?pattern=TEMPLATE*

{
    "templates" : [
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/templates/TEMPLATE_ID"},
            "id" : "TEMPLATE_ID",
            "type" : "stream",
            "script" : "stream|from().measurement('cpu')",
            "dot" : "digraph TEMPLATE_ID { ... }",
            "error" : ""
        }
    ]
}

获取所有模板，但只获取 script 和 error 字段。

GET /kapacitor/v1/templates?fields=status&fields=executing&fields=error

{
    "templates" : [
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/templates/TEMPLATE_ID"},
            "id" : "TEMPLATE_ID",
            "script" : "stream|from().measurement('cpu')",
            "error" : ""
        },
        {
            "link" : {"rel":"self", "href":"/kapacitor/v1/templates/ANOTHER_TEMPLATE_ID"},
            "id" : "ANOTHER_TEMPLATE_ID",
            "script" : "stream|from().measurement('cpu')",
            "error" : ""
        }
    ]
}

响应

代码意义
200成功

注意: 如果模式不匹配任何模板，将返回一个空列表，并且状态码为200表示成功。

管理录音

Kapacitor 可以保存数据录音并将其重新播放到指定任务上。

创建录音

有三种方法可以使用Kapacitor记录数据：要创建一个记录，请向/kapacitor/v1/recordings/METHOD端点发送POST请求。

方法描述
流记录传入的数据流。
batch记录批处理任务中查询的结果。
query记录显式查询的结果。

请求在录音开始后返回，而不需要等待它结束。
返回一个录音 ID 以便后续识别录音。

流
参数目的
id录音的唯一标识符。如果为空，则会选择一个随机的。
任务任务的ID，仅用于记录该任务的DBRP数据。
停止记录流数据直到停止日期。
批处理
参数目的
id录音的唯一标识符。如果为空，将选择一个随机的标识符。
任务任务的ID，记录在任务中定义的查询结果。
开始将记录数据的最早日期。RFC3339Nano 格式。
stop将记录数据的最新日期。如果未指定，则使用当前时间。RFC3339Nano 格式的数据。
查询
参数目的
id录音的唯一标识符。如果为空，则会选择一个随机的标识符。
类型记录的类型， stream 或 batch。
query要执行的查询。
cluster已配置的 InfluxDB 集群的名称。如果为空，则使用默认集群。

注意: 录音本身被标记为流录音或批量录音，只能重放到相应类型的任务。因此，当您记录原始查询的结果时，必须指定您希望创建的录音类型。

示例

使用 stream 方法创建录音

POST /kapacitor/v1/recordings/stream
{
    "task" : "TASK_ID",
    "stop" : "2006-01-02T15:04:05Z07:00"
}

使用batch方法创建一个记录，指定开始时间。

POST /kapacitor/v1/recordings/batch
{
    "task" : "TASK_ID",
    "start" : "2006-01-02T15:04:05Z07:00"
}

使用指定 stream 类型的 query 方法创建录音。

POST /kapacitor/v1/recordings/query
{
    "query" : "SELECT mean(usage_idle) FROM cpu WHERE time > now() - 1h GROUP BY time(10m)",
    "type" : "stream"
}

使用指定batch类型的query方法创建一个录音。

POST /kapacitor/v1/recordings/query
{
    "query" : "SELECT mean(usage_idle) FROM cpu WHERE time > now() - 1h GROUP BY time(10m)",
    "type" : "batch"
}

创建一个具有自定义ID的录音。

POST /kapacitor/v1/recordings/query
{
    "id" : "MY_RECORDING_ID",
    "query" : "SELECT mean(usage_idle) FROM cpu WHERE time > now() - 1h GROUP BY time(10m)",
    "type" : "batch"
}

响应

所有录音都分配一个ID，以这种格式返回，并带有链接。

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0"},
    "id" : "e24db07d-1646-4bb3-a445-828f5049bea0",
    "type" : "stream",
    "size" : 0,
    "date" : "2006-01-02T15:04:05Z07:00",
    "error" : "",
    "status" : "running",
    "progress" : 0
}
代码意义
201成功，录音已开始。

等待录音

为了确定录音何时结束，您必须向返回的链接发出一个GET请求，通常类似于 /kapacitor/v1/recordings/RECORDING_ID。

录音具有这些只读属性。

属性描述
size磁盘上录音的大小（以字节为单位）。
日期录音结束的日期。
错误创建录音时遇到的任何错误。
状态其中之一是 recording 或 finished。
progress表示录音大致进度的介于 0 和 1 之间的数字。

示例

GET /kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0"},
    "id" : "e24db07d-1646-4bb3-a445-828f5049bea0",
    "type" : "stream",
    "size" : 1980353,
    "date" : "2006-01-02T15:04:05Z07:00",
    "error" : "",
    "status" : "running",
    "progress" : 0.75
}

一旦录音完成。

GET /kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0"},
    "id" : "e24db07d-1646-4bb3-a445-828f5049bea0",
    "type" : "stream",
    "size" : 1980353,
    "date" : "2006-01-02T15:04:05Z07:00",
    "error" : "",
    "status" : "finished",
    "progress" : 1
}

或者如果录音失败。

GET /kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0"},
    "id" : "e24db07d-1646-4bb3-a445-828f5049bea0",
    "type" : "stream",
    "size" : 1980353,
    "date" : "2006-01-02T15:04:05Z07:00",
    "error" : "error message explaining failure",
    "status" : "failed",
    "progress" : 1
}

响应

代码意义
200成功，录音已经不再进行。
202成功，录音存在但尚未完成。
404此记录不存在。

删除录音

要删除一个录音，请向 /kapacitor/v1/recordings/RECORDING_ID 端点发送 DELETE 请求。

DELETE /kapacitor/v1/recordings/RECORDING_ID

响应

代码意义
204成功

注意：删除一个不存在的录音不是错误，将返回204成功。

列出录音

要列出所有录音，请向 /kapacitor/v1/recordings 端点发出 GET 请求。 录音按日期排序。

查询参数默认值目的
模式根据模式过滤结果。使用标准的shell glob匹配，详细信息请参见此处。
字段要返回的字段列表。如果为空，则返回所有字段。字段 id 和 link 始终返回。
offset0用于分页任务的偏移计数。
limit100返回的最大任务数量。

示例

GET /kapacitor/v1/recordings

{
    "recordings" : [
        {
            "link" : {"rel": "self", "href": "/kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0"},
            "id" : "e24db07d-1646-4bb3-a445-828f5049bea0",
            "type" : "stream",
            "size" : 1980353,
            "date" : "2006-01-02T15:04:05Z07:00",
            "error" : "",
            "status" : "finished",
            "progress" : 1
        },
        {
            "link" : {"rel": "self", "href": "/kapacitor/v1/recordings/8a4c06c6-30fb-42f4-ac4a-808aa31278f6"},
            "id" : "8a4c06c6-30fb-42f4-ac4a-808aa31278f6",
            "type" : "batch",
            "size" : 216819562,
            "date" : "2006-01-02T15:04:05Z07:00",
            "error" : "",
            "status" : "finished",
            "progress" : 1
        }
    ]
}

响应

代码意义
200成功

管理重播

回放录音

要重播录音，请向 /kapacitor/v1/replays/ 发送 POST 请求

参数默认值目的
idrandom重放的唯一标识符。如果为空，则选择一个随机ID。
任务任务的ID。
录音录音的ID。
recording-timefalse如果为真，使用录音中的时间，否则相对于当前时间调整时间。
时钟快速fast或real之一。如果real则等待真实时间与录音中的时间相对应。如果fast则无延迟地重放数据。例如，如果时钟是real，则持续时间为5分钟的流录音将需要5分钟进行重放。

示例

使用默认参数重放录音。

POST /kapacitor/v1/replays/
{
    "task" : "TASK_ID",
    "recording" : "RECORDING_ID"
}

以实时模式播放录音并保留录音时间。

POST /kapacitor/v1/replays/
{
    "task" : "TASK_ID",
    "recording" : "RECORDING_ID",
    "clock" : "real",
    "recording-time" : true,
}

使用自定义 ID 重新播放录音。

POST /kapacitor/v1/replays/
{
    "id" : "MY_REPLAY_ID",
    "task" : "TASK_ID",
    "recording" : "RECORDING_ID"
}

响应

请求在重放开始后返回，并提供重放ID和链接。

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/replays/ad95677b-096b-40c8-82a8-912706f41d4c"},
    "id" : "ad95677b-096b-40c8-82a8-912706f41d4c",
    "task" : "TASK_ID",
    "recording" : "RECORDING_ID",
    "clock" : "fast",
    "recording-time" : false,
    "status" : "running",
    "progress" : 0,
    "error" : "",
    "stats": {},
}
代码意义
201成功，重放已开始。

无需录制重放数据

也可以直接重放数据而不先进行录制。这是通过发出类似于batch或query录制的请求来完成的，但不是存储数据，而是立即对任务进行重放。使用stream录制立即对任务进行重放等同于启用该任务，因此不支持。

方法描述
batch在批处理任务中重放查询的结果。
query重放显式查询的结果。
批处理
参数默认值目的
idrandom重放的唯一标识符。如果为空，将选择一个随机的。
任务任务的ID，重放在任务中定义的查询结果。
开始将回放数据的最早日期。RFC3339Nano 格式。
停止现在数据将被重播的最新日期。如果未指定，则使用当前时间。RFC3339Nano 格式的数据。
recording-timefalse如果为真，使用录音中的时间，否则相对于当前时间调整时间。
时钟快速fast或real之一。如果real则等待真实时间与录音中的时间相对应。如果fast则无延迟地重放数据。例如，如果时钟是real，则持续时间为5分钟的流录音将需要5分钟进行重放。
查询
参数默认值目的
idrandom回放的唯一标识符。如果为空，将选择一个随机的。
任务任务的ID，重放针对该任务的查询结果。
query要执行的查询。
cluster配置的 InfluxDB 集群的名称。如果为空，则使用默认集群。
recording-timefalse如果为真，使用录音中的时间，否则相对于当前时间调整时间。
时钟快速fast或real之一。如果real则等待真实时间与录音中的时间相对应。如果fast则无延迟地重放数据。例如，如果时钟是real，则持续时间为5分钟的流录音将需要5分钟进行重放。

示例

使用batch方法指定开始时间进行回放。

POST /kapacitor/v1/replays/batch
{
    "task" : "TASK_ID",
    "start" : "2006-01-02T15:04:05Z07:00"
}

重放查询针对任务的结果。

POST /kapacitor/v1/replays/query
{
    "task" : "TASK_ID",
    "query" : "SELECT mean(usage_idle) FROM cpu WHERE time > now() - 1h GROUP BY time(10m)",
}

使用自定义ID创建回放。

POST /kapacitor/v1/replays/query
{
    "id" : "MY_REPLAY_ID",
    "task" : "TASK_ID",
    "query" : "SELECT mean(usage_idle) FROM cpu WHERE time > now() - 1h GROUP BY time(10m)",
}

响应

所有回放都分配一个ID，以这种格式返回，并带有链接。

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/replays/e24db07d-1646-4bb3-a445-828f5049bea0"},
    "id" : "e24db07d-1646-4bb3-a445-828f5049bea0",
    "task" : "TASK_ID",
    "recording" : "",
    "clock" : "fast",
    "recording-time" : false,
    "status" : "running",
    "progress" : 0.57,
    "error" : "",
    "stats": {}
}

注意: 以这种方式创建的回放，recording ID 将为空，因为没有使用或创建录音。

代码意义
201成功，回放已经开始。

等待回复

像录音一样，您可以发送一个 GET 请求到 /kapacitor/v1/replays/REPLAY_ID 端点以获取重放的状态。

重放具有这些只读属性，除此之外还有上面列出的属性。

属性描述
状态可以是 replaying 或 finished。
progress一个介于0和1之间的数字，表示回放的大致进度。
错误在执行重放时发生的任何错误

示例

获取回放的状态。

GET /kapacitor/v1/replays/ad95677b-096b-40c8-82a8-912706f41d4c

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/replays/ad95677b-096b-40c8-82a8-912706f41d4c"},
    "id" : "ad95677b-096b-40c8-82a8-912706f41d4c",
    "task" : "TASK_ID",
    "recording" : "RECORDING_ID",
    "clock" : "fast",
    "recording-time" : false,
    "status" : "running",
    "progress" : 0.57,
    "error" : "",
    "stats": {}
}

一旦重放完成。

GET /kapacitor/v1/replays/ad95677b-096b-40c8-82a8-912706f41d4c

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/replays/ad95677b-096b-40c8-82a8-912706f41d4c"},
    "id" : "ad95677b-096b-40c8-82a8-912706f41d4c",
    "task" : "TASK_ID",
    "recording" : "RECORDING_ID",
    "clock" : "fast",
    "recording-time" : false,
    "status" : "finished",
    "progress" : 1,
    "error" : "",
    "stats": {
        "task-stats": {
            "throughput": 0
        },
        "node-stats": {
            "alert2": {
                "alerts_triggered": 5,
                "avg_exec_time_ns": 1267486,
                "collected": 8,
                "crits_triggered": 2,
                "emitted": 0,
                "errors": 0,
                "infos_triggered": 0,
                "oks_triggered": 1,
                "warns_triggered": 2,
                "working_cardinality": 1
            },
            "from1": {
                "avg_exec_time_ns": 0,
                "collected": 8,
                "emitted": 8,
                "errors": 0,
                "working_cardinality": 0
            },
            "stream0": {
                "avg_exec_time_ns": 0,
                "collected": 8,
                "emitted": 8,
                "errors": 0,
                "working_cardinality": 0
            }
        }
    }
}

如果重放已经完成，stats 字段包含关于重放的统计信息。

或者如果重放失败。

GET /kapacitor/v1/replays/ad95677b-096b-40c8-82a8-912706f41d4c

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/replays/ad95677b-096b-40c8-82a8-912706f41d4c"},
    "id" : "ad95677b-096b-40c8-82a8-912706f41d4c",
    "task" : "TASK_ID",
    "recording" : "RECORDING_ID",
    "clock" : "fast",
    "recording-time" : false,
    "status" : "failed",
    "progress" : 1,
    "error" : "error message explaining failure",
    "stats": {}
}

响应

代码意义
200成功，回放不再运行。
202成功，回复存在但尚未完成。
404不存在这样的回放。

删除重播

要删除一个回放，请向 /kapacitor/v1/replays/REPLAY_ID 端点发出 DELETE 请求。

DELETE /kapacitor/v1/replays/REPLAY_ID

响应

代码意义
204成功

注意: 删除一个不存在的重放并不是错误，将返回204成功。

列出回复

您可以通过向 /kapacitor/v1/replays 发送 GET 请求来列出给定录音的重放。

查询参数默认值目的
模式根据模式过滤结果。使用标准的shell glob匹配，详细信息请参见此处。
字段要返回的字段列表。如果为空，则返回所有字段。字段 id 和 link 始终返回。
offset0用于分页任务的偏移计数。
limit100返回的最大任务数量。

示例

GET /kapacitor/v1/replays

{
    "replays": [
        {
            "link" : {"rel": "self", "href": "/kapacitor/v1/replays/ad95677b-096b-40c8-82a8-912706f41d4c"},
            "id" : "ad95677b-096b-40c8-82a8-912706f41d4c",
            "task" : "TASK_ID",
            "recording" : "RECORDING_ID",
            "clock" : "fast",
            "recording-time" : false,
            "status" : "finished",
            "progress" : 1,
            "error" : ""
        },
        {
            "link" : {"rel": "self", "href": "/kapacitor/v1/replays/be33f0a1-0272-4019-8662-c730706dac7d"},
            "id" : "be33f0a1-0272-4019-8662-c730706dac7d",
            "task" : "TASK_ID",
            "recording" : "RECORDING_ID",
            "clock" : "fast",
            "recording-time" : false,
            "status" : "finished",
            "progress" : 1,
            "error" : ""
        }
    ]
}

管理警报

Kapacitor 可以生成和处理警报。 API 允许您查看任何警报的当前状态，并为警报配置各种处理程序。

主题

警报被分组到主题中。
一个警报处理程序在某个主题上“监听”任何新的事件。
您可以在TICKscript中指定警报主题，或者为您生成一个。

创建和删除主题

主题在被 TICKscripts 或处理程序引用时动态创建。
要删除一个主题，请向 /kapacitor/v1/alerts/topics/ 发送 DELETE 请求。
这将删除该主题的所有已知事件和状态。

注意: 由于主题是动态创建的，如果为该主题创建了新事件，已删除的主题可能会重新出现。

示例

DELETE /kapacitor/v1/alerts/topics/system

列出主题

要查询可用主题的列表，请向 /kapacitor/v1/alerts/topics 发送 GET 请求。

查询参数默认值目的
min-levelOK仅返回大于或等于最小级别的主题。有效值包括 OK、INFO、WARNING、CRITICAL。
模式*根据模式过滤结果。使用主题ID上的标准shell glob匹配，详细信息请参见 this。

示例

获取所有主题。

GET /kapacitor/v1/alerts/topics

{
    "link": {"rel":"self","href":"/kapacitor/v1/alerts/topics"},
    "topics": [
        {
            "link": {"rel":"self","href":"/kapacitor/v/alerts/topics/system"},
            "events-link" : {"rel":"events","href":"/kapacitor/v1/alerts/topics/system/events"},
            "handlers-link": {"rel":"handlers","href":"/kapacitor/v1/alerts/topics/system/handlers"},
            "id": "system",
            "level":"CRITICAL"
        },
        {
            "link": {"rel":"self","href":"/kapacitor/v1/alerts/topics/app"},
            "events-link" : {"rel":"events","href":"/kapacitor/v1/alerts/topics/app/events"},
            "handlers-link": {"rel":"handlers","href":"/kapacitor/v1/alerts/topics/app/handlers"},
            "id": "app",
            "level":"OK"
        }
    ]
}

获取所有处于警告或严重状态的主题。

GET /kapacitor/v1/alerts/topics?min-level=WARNING

{
    "link": {"rel":"self","href":"/kapacitor/v1/alerts/topics"},
    "topics": [
        {
            "link": {"rel":"self","href":"/kapacitor/v1/alerts/topics/system"},
            "events-link" : {"rel":"events","href":"/kapacitor/v1/alerts/topics/system/events"},
            "handlers-link": {"rel":"handlers","href":"/kapacitor/v1/alerts/topics/system/handlers"},
            "id": "system",
            "level":"CRITICAL"
        }
    ]
}

主题状态

要查询主题的状态，请对 /kapacitor/v1/alerts/topics/ 发起一个 GET 请求。

示例

GET /kapacitor/v1/alerts/topics/system

{
    "link": {"rel":"self","href":"/kapacitor/v1/alerts/topics/system"},
    "id": "system",
    "level":"CRITICAL"
    "events-link" : {"rel":"events","href":"/kapacitor/v1/alerts/topics/system/events"},
    "handlers-link": {"rel":"handlers","href":"/kapacitor/v1/alerts/topics/system/handlers"},
}

列出主题事件

要查询主题内的所有事件，请对 /kapacitor/v1/alerts/topics//events 发出 GET 请求。

查询参数默认值目的
min-levelOK仅返回大于或等于最小级别的事件。有效值包括 OK，INFO，WARNING，CRITICAL。

示例

GET /kapacitor/v1/alerts/topics/system/events

{
    "link": {"rel":"self","href":"/kapacitor/v1/alerts/topics/system/events"},
    "topic": "system",
    "events": [
        {
            "link":{"rel":"self","href":"/kapacitor/v1/alerts/topics/system/events/cpu"},
            "id": "cpu",
            "state": {
                "level": "WARNING",
                "message": "cpu is WARNING",
                "time": "2016-12-01T00:00:00Z",
                "duration": "5m"
            }
        },
        {
            "link":{"rel":"self","href":"/kapacitor/v1/alerts/topics/system/events/mem"},
            "id": "mem",
            "state": {
                "level": "CRITICAL",
                "message": "mem is CRITICAL",
                "time": "2016-12-01T00:10:00Z",
                "duration": "1m"
            }
        }
    ]
}

主题事件

您可以通过对 /kapacitor/v1/alerts/topics//events/ 发起GET请求来查询特定主题中的特定事件。

示例

GET /kapacitor/v1/alerts/topics/system/events/cpu

{
    "link":{"rel":"self","href":"/kapacitor/v1/alerts/topics/system/events/cpu"},
    "id": "cpu",
    "state": {
        "level": "WARNING",
        "message": "cpu is WARNING",
        "time": "2016-12-01T00:00:00Z",
        "duration": "5m"
    }
}

列出主题处理程序

处理程序是在主题中创建的。 您可以通过向 /kapacitor/v1/alerts/topics//handlers 发出 GET 请求来获取为主题配置的处理程序列表。

查询参数默认值目的
模式*根据模式过滤结果。对服务名称使用标准的shell glob匹配，更多细节请参见this。

注意: 匿名处理程序（自动从 TICKscripts 创建）将不会在其关联的匿名主题下列出，因为它们不是通过 API 配置的。

示例

获取system主题的处理程序。

GET /kapacitor/v1/alerts/topics/system/handlers

{
    "link":{"rel":"self","href":"/kapacitor/v1/alerts/topics/system/handlers"},
    "topic": "system",
    "handlers": [
        {
            "link":{"rel":"self","href":"/kapacitor/v1/alerts/topics/system/handlers/slack"},
            "id":"slack",
            "kind":"slack",
            "options":{
              "channel":"#alerts"
            },
        },
        {
            "link":{"rel":"self","href":"/kapacitor/v1/alerts/topics/system/handlers/smtp"},
            "id":"smtp",
            "kind":"smtp"
        }
    ]
}

这个 main:alert_cpu:alert5 主题表示一个来自于在 TICKscript 中明确定义处理程序的任务的自动生成主题。匿名处理程序无法通过 API 列出或修改。

GET /kapacitor/v1/alerts/topics/main:alert_cpu:alert5/handlers

{
    "link":{"rel":"self","href":"/kapacitor/v1/alerts/topics/system/handlers"},
    "topic": "main:alert_cpu:alert5",
    "handlers": null
}

获取主题处理器

要查询有关特定处理程序的信息，请向 /kapacitor/v1/alerts/topics//handlers/ 发出GET请求。

示例

GET /kapacitor/v1/alerts/topics/system/handlers/slack

{
  "link": {
    "rel": "self",
      "href": "/kapacitor/v1/alerts/topics/system/handlers/slack"
  },
  "id": "slack",
  "kind": "slack",
  "options": {
    "channel": "#alerts"
  },
  "match": ""
}

创建主题处理器

要创建一个新的处理程序，请向 /kapacitor/v1/alerts/topics/system/handlers 发送 POST 请求。

POST /kapacitor/v1/alerts/topics/system/handlers
{
  "id":"slack",
  "kind":"slack",
  "options": {
    "channel":"#alerts"
  }
}

{
  "link": {
    "rel": "self",
      "href": "/kapacitor/v1/alerts/topics/system/handlers/slack"
  },
  "id": "slack",
  "kind": "slack",
  "options": {
    "channel": "#alerts"
  },
  "match": ""
}

更新主题处理器

要更新现有的处理程序，您可以向 /kapacitor/v1/alerts/topics/system/handlers/ 发出 PUT 或 PATCH 请求。

使用PUT将替换整个处理程序，而使用PATCH可以修改处理程序的特定部分。

PATCH将把JSON补丁对象应用到现有的处理程序，详情请参见 rfc6902。

示例

使用PATCH方法更新处理程序的主题和操作。

PATCH /kapacitor/v1/alerts/topics/system/handlers/slack
[
    {"op":"replace", "path":"/topics", "value":["system", "test"]},
    {"op":"replace", "path":"/options/channel", "value":"#testing_alerts"}
]

{
  "link": {
    "rel": "self",
      "href": "/kapacitor/v1/alerts/topics/system/handlers/slack"
  },
  "id": "slack",
  "kind": "slack",
  "options": {
    "channel": "#testing_alerts"
  },
  "match": ""
}

使用PUT方法替换整个处理程序。

PUT /kapacitor/v1/alerts/topics/system/handlers/slack
{
  "id": "slack",
  "kind":"slack",
  "options": {
    "channel":"#testing_alerts"
  }
}

{
  "link": {
    "rel": "self",
      "href": "/kapacitor/v1/alerts/topics/system/handlers/slack"
  },
  "id": "slack",
  "kind": "slack",
  "options": {
    "channel": "#testing_alerts"
  },
  "match": ""
}

删除主题处理程序

要移除现有处理程序，请向 /kapacitor/v1/alerts/topics/system/handlers/ 发出 DELETE 请求。

DELETE /kapacitor/v1/alerts/topics/system/handlers/<handler id>

覆盖 Kapacitor 配置

您可以通过API设置某些配置部分的配置覆盖。 通过API设置的覆盖总是优先于配置文件中可能存在的内容。 可用于覆盖的部分包括InfluxDB集群和警报处理程序部分。

该API的目的是在不需要重启Kapacitor进程的情况下，允许动态配置敏感凭据。因此，建议使用配置文件或API来管理这些配置部分，而不是两者都使用。这将有助于消除关于给定配置选项来源的任何混淆。

启用和禁用配置覆盖

默认情况下，能够覆盖配置的功能是启用的。 如果您不希望启用此功能，可以通过 config-override 配置部分将其禁用。

[config-override]
  enabled = false

如果 config-override 服务被禁用，则相关的 API 端点将返回 403 禁止访问错误。

从错误的配置中恢复

如果您以某种方式创建了导致Kapacitor崩溃或其他故障的配置，您可以通过skip-config-overrides顶级配置选项在启动时禁用应用覆盖。

# This configuration option is only a safe guard and should not be needed in practice.
skip-config-overrides = true

这使您仍然可以访问API，以修复在启动期间不应用的任何不希望的配置。

注意: 将此选项设置为环境变量 KAPACITOR_SKIP_CONFIG_OVERRIDES=true 可能是最简单和最安全的，因为它是暂时的。这样您就不必修改您磁盘上的配置文件或意外地将其保留在原位，后续可能会导致问题。

概述

配置API端点的路径如下：

/kapacitor/v1/config/

/[]

示例:

/kapacitor/v1/config/smtp/
/kapacitor/v1/config/influxdb/localhost
/kapacitor/v1/config/influxdb/remote

可选的 element name 路径元素对应于条目列表中的特定项。

例如，上述路径对应以下配置部分：

[smtp]
    # SMTP configuration here

[[influxdb]]
    name = "localhost"
    # InfluxDB configuration here for the "localhost" cluster

[[influxdb]]
    name = "remote"
    # InfluxDB configuration here for the "remote" cluster

获取当前配置

要检索当前配置，请向所需路径执行GET请求。返回的配置将是配置文件中的合并值以及存储在覆盖中的内容。返回的内容将是配置对象的JSON编码版本。

所有敏感信息将不会在请求体中返回。 相反，将返回一个布尔值，指示该值是否为空。 每个元素返回一个被删除选项的列表。

示例

检索所有可以被重写的配置部分。

GET /kapacitor/v1/config

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/config"},
    "sections": {
        "influxdb": {
            "link" : {"rel": "self", "href": "/kapacitor/v1/config/influxdb"},
            "elements": [
                {
                    "link" : {"rel": "self", "href": "/kapacitor/v1/config/influxdb/localhost"},
                    "options": {
                        "name": "localhost",
                        "urls": ["http://localhost:8086"],
                        "default": true,
                        "username": "",
                        "password": false
                    },
                    "redacted" : [
                        "password"
                    ]
                },
                {
                    "link" : {"rel": "self", "href": "/kapacitor/v1/config/influxdb/remote"},
                    "options": {
                        "name": "remote",
                        "urls": ["http://influxdb.example.com:8086"],
                        "default": false,
                        "username": "jim",
                        "password": true
                    },
                    "redacted" : [
                        "password"
                    ]
                }
            ]
        },
        "smtp": {
            "link" : {"rel": "self", "href": "/kapacitor/v1/config/smtp"},
            "elements": [{
                "link" : {"rel": "self", "href": "/kapacitor/v1/config/smtp/"},
                "options": {
                    "enabled": true,
                    "host": "smtp.example.com",
                    "port": 587,
                    "username": "bob",
                    "password": true,
                    "no-verify": false,
                    "global": false,
                    "to": [ "oncall@example.com"],
                    "from": "kapacitor@example.com",
                    "idle-timeout": "30s"
                },
                "redacted" : [
                    "password"
                ]
            }]
        }
    }
}

仅检索SMTP部分。

GET /kapacitor/v1/config/smtp

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/config/smtp"},
    "elements": [{
        "link" : {"rel": "self", "href": "/kapacitor/v1/config/smtp/"},
        "options": {
            "enabled": true,
            "host": "smtp.example.com",
            "port": 587,
            "username": "bob",
            "password": true,
            "no-verify": false,
            "global": false,
            "to": ["oncall@example.com"],
            "from": "kapacitor@example.com",
            "idle-timeout": "30s"
        },
        "redacted" : [
            "password"
        ]
    }]
}

从SMTP部分检索单个元素。

GET /kapacitor/v1/config/smtp/

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/config/smtp/"},
    "options": {
        "enabled": true,
        "host": "smtp.example.com",
        "port": 587,
        "username": "bob",
        "password": true,
        "no-verify": false,
        "global": false,
        "to": ["oncall@example.com"],
        "from": "kapacitor@example.com",
        "idle-timeout": "30s"
    },
    "redacted" : [
        "password"
    ]
}

注意: 不是列表的部分可以视为其元素名称为空字符串。

仅检索InfluxDB部分。

GET /kapacitor/v1/config/influxdb

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/config/influxdb"},
    "elements" : [
        {
            "link" : {"rel": "self", "href": "/kapacitor/v1/config/influxdb/localhost"},
            "options": {
               "name": "localhost",
               "urls": ["http://localhost:8086"],
               "default": true,
               "username": "",
               "password": false
            },
            "redacted" : [
                "password"
            ]
        },
        {
            "link" : {"rel": "self", "href": "/kapacitor/v1/config/influxdb/remote"},
            "options": {
                "name": "remote",
                "urls": ["http://influxdb.example.com:8086"],
                "default": false,
                "username": "jim",
                "password": true
            },
            "redacted" : [
                "password"
            ]
        }
    ]
}

仅检索InfluxDB部分的 remote 元素。

GET /kapacitor/v1/config/influxdb/remote

{
    "link" : {"rel": "self", "href": "/kapacitor/v1/config/influxdb/remote"},
    "options": {
        "name": "remote",
        "urls": ["http://influxdb.example.com:8086"],
        "default": false,
        "username": "jim",
        "password": true
    },
    "redacted" : [
        "password"
    ]
}

注意: 密码值不会被返回，但true值表示已设置非空密码。

响应

代码意义
200成功
403配置覆盖服务未启用

覆盖配置值

要覆盖配置中的一个值，请向所需路径发出POST请求。 请求应包含一个描述需要修改内容的JSON对象。

使用以下顶级操作：

键描述
set设置配置覆盖中的值。
delete从配置覆盖中删除值。
add向列表配置部分添加一个新元素。
remove从列表配置部分中移除之前添加的元素。

请求中未指定的配置选项将保持不变。

示例

要禁用SMTP警报处理程序：

POST /kapacitor/v1/config/smtp/
{
    "set":{
        "enabled": false
    }
}

要删除SMTP警报处理程序的覆盖：

POST /kapacitor/v1/config/smtp/
{
    "delete":[
        "enabled"
    ]
}

动作可以在单个请求中组合。启用SMTP处理程序，设置它的主机并移除端口覆盖。

POST /kapacitor/v1/config/smtp/
{
    "set":{
        "enabled": true,
        "host": "smtp.example.com"
    },
    "delete":[
        "port"
    ]
}

添加一个新的InfluxDB集群：

POST /kapacitor/v1/config/influxdb
{
    "add":{
        "name": "example",
        "urls": ["https://influxdb.example.com:8086"],
        "default": true,
        "disable-subscriptions": true
    }
}

移除现有的 InfluxDB 集群覆盖：

POST /kapacitor/v1/config/influxdb
{
    "remove":[
        "example"
    ]
}

注意: 只能移除重写，这意味着在配置中存在的InfluxDB集群无法被移除。

修改现有的 InfluxDB 集群：

POST /kapacitor/v1/config/influxdb/remote
{
    "set":{
        "disable-subscriptions": false,
    },
    "delete": [
        "default"
    ]
}

响应

代码意义
200成功
403配置覆盖服务未启用
404指定的配置部分/选项不存在

管理存储

Kapacitor 提供了一些可以在底层存储上执行的操作。

警告: 所有存储操作都是直接操作底层存储数据库。在执行任何这些操作之前，请始终备份数据库。

备份存储

向 /kapacitor/v1/storage/backup 发起GET请求将返回Kapacitor数据库的转储。 要从备份中恢复，请用备份请求的内容替换 kapacitor.db 文件。

# Create a backup.
curl http://localhost:9092/kapacitor/v1/storage/backup > kapacitor.db

# Restore a backup.
# The destination path is dependent on your configuration.
cp kapacitor.db ~/.kapacitor/kapacitor.db

商店

Kapacitor的底层存储系统被组织成不同的存储。在每个单独的存储上可以执行各种操作。

警告: 所有存储操作都直接操作底层存储数据库。在执行任何这些操作之前，请务必备份数据库。

可用操作：

操作描述
rebuild重新建立商店中的所有索引，此操作可能非常耗费资源。

要执行一个操作，请向 /kapacitor/v1/storage/stores/ 发起 POST 请求

示例

POST /kapacitor/v1/storage/stores/tasks
{
    "action" : "rebuild"
}

响应

代码意义
204成功
400未知操作
404指定的商店不存在

用户

Kapacitor 开放了管理用户的操作。

列出所有用户

要列出用户，请使用GET请求方法和/kapacitor/v1/users端点。

示例

curl GET "http://localhost:9092/kapacitor/v1/users"

创建用户

要创建用户，请使用POST请求方法与/kapacitor/v1/users端点。

将用户定义为具有以下属性的JSON对象：

属性描述
姓名用户名
密码密码
类型用户类型 (normal 或 admin, 查看 User)
权限有效用户权限字符串的列表 (none, api, config_api, write_points, all)

查看 Kapacitor 用户类型和权限。

示例

curl --XPOST 'http://localhost:9092/kapacitor/v1/users' \
  --data '{
    "name": "stan",
    "password": "pass",
    "type":"normal",
    "permissions": ["config_api"]
}'

更新用户

要更新用户，请使用 PATCH 请求方法和 /kapacitor/v1/users/ 端点。

将修改后的用户定义为具有以下属性的JSON对象：

属性目的
密码密码
类型用户类型 (normal 或 admin, 见 User)
权限有效用户权限字符串列表 (none, api, config_api, write_points, all)

示例

curl -XPATCH "http://localhost:9092/kapacitor/v1/users/bob" -d '{ "password": "pass", "type":"admin", "permissions":["all"] }'

删除用户

要删除用户，请使用带有 /kapacitor/v1/users/ 端点的 DELETE 请求方法。

示例

curl -XDELETE "http://localhost:9092/kapacitor/v1/users/steve"

管理 Flux 任务

Kapacitor 提供管理 Flux 任务的操作。有关更多信息，请参见 使用 Flux 任务。

创建一个 Flux 任务

使用以下请求方法和端点来创建一个新的Kapacitor Flux任务。

POST /kapacitor/v1/api/v2/tasks

请在请求中提供以下内容 (* 必填)：

标题

  • * 内容类型： application/json

请求体

具有以下架构的JSON对象：

  • * flux: Flux 任务代码
  • 状态: Flux 任务状态 (active 或 inactive, 默认是 active)
  • 描述: Flux 任务描述
curl --request POST 'http://localhost:9092/kapacitor/v1/api/v2/tasks' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\n\nhost = \"http://localhost:8086\"\ntoken = \"\"\n\nfrom(bucket: \"db/rp\", host:host, token:token)\n\t|> range(start: -1h)\n\t|> filter(fn: (r) =>\n\t\t(r._measurement == \"cpu\"))\n\t|> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))\n\t|> filter(fn: (r) =>\n\t\t(r.cpu == \"cpu-total\"))\n\t|> aggregateWindow(every: 1h, fn: max)\n\t|> to(bucket: \"cpu_usage_user_total_1h\", host:host, token:token)",
    "status": "active",
    "description": "Downsample CPU data every hour"
}'

列出 Flux 任务

使用以下请求方法和端点来列出Kapacitor Flux任务。

GET /kapacitor/v1/api/v2/tasks

请在请求中提供以下内容 (* 必填)：

标题

  • * 内容类型： application/json

查询参数

  • after: 列出特定任务ID之后的任务
  • limit: 限制返回的任务数量（默认为500）
  • name: 按名称筛选任务
  • 状态: 按状态筛选任务 (active 或 inactive)

示例

列出所有 Flux 任务
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks' \
  --header 'Content-Type: application/json'
列出有限数量的Flux任务
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks' \
  --header 'Content-Type: application/json' \
  --data-urlencode "limit=1"
按名称列出特定的Flux任务
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks' \
  --header 'Content-Type: application/json' \
  --data-urlencode "name=example-flux-task-name"
在特定任务ID之后列出Flux任务
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks' \
  --header 'Content-Type: application/json' \
  --data-urlencode "after=000x00xX0xXXx00"
仅列出活动的 Flux 任务
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks' \
  --header 'Content-Type: application/json' \
  --data-urlencode "status=active"

更新一个 Flux 任务

使用以下请求方法和端点来更新一个新的Kapacitor Flux任务。

PATCH /kapacitor/v1/api/v2/tasks/{taskID}

请在请求中提供以下内容 (* 必填)：

标题

  • * 内容类型: application/json

路径参数

  • * taskID: 更新的任务ID

请求体

具有以下架构的JSON对象：

  • cron: 重写 cron Flux 任务选项
  • 描述: 新任务描述
  • 每个: 重写 every Flux 任务选项
  • flux: 新的 Flux 任务代码
  • name: 覆盖 name Flux 任务选项
  • offset: 重写 offset Flux 任务选项
  • 状态: 新的Flux任务状态 (active 或 inactive)
示例

以下示例使用任务 ID 000x00xX0xXXx00。

更新 Flux 任务代码
curl --request PATCH 'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "flux": "option task = {name: \"Updated task name\", every: 1h}\n\nhost = \"http://localhost:8086\"\ntoken = \"\"\n\nfrom(bucket: \"db/rp\", host:host, token:token)\n\t|> range(start: -1h)\n\t|> filter(fn: (r) =>\n\t\t(r._measurement == \"cpu\"))\n\t|> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))\n\t|> filter(fn: (r) =>\n\t\t(r.cpu == \"cpu-total\"))\n\t|> aggregateWindow(every: 1h, fn: max)\n\t|> to(bucket: \"cpu_usage_user_total_1h\", host:host, token:token)"
}'
启用或禁用Flux任务
curl --request PATCH 'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00' \
  --header 'Content-Type: application/json' \
  --data-raw '{"status": "inactive"}'
覆盖 Flux 任务选项
curl --request PATCH 'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "every": "1d",
    "name": "New task name",
    "offset": "15m"
}'

删除一个 Flux 任务

使用以下请求方法和端点来删除一个Kapacitor Flux任务。

DELETE /kapacitor/v1/api/v2/tasks/{taskID}

请在请求中提供以下内容 (* 必填)：

路径参数

  • * taskID: 要删除的任务 ID
# Delete task ID 000x00xX0xXXx00
curl --request DELETE 'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00'

列出Kapacitor Flux任务运行

使用以下请求方法和端点来列出 Kapacitor Flux 任务运行。

GET /kapacitor/v1/api/v2/tasks/{taskID}/runs

请在请求中提供以下内容 (* 必填)：

标题

  • * 内容类型： application/json

路径参数

  • * taskID: 任务ID

查询参数

  • after: 列出在特定运行ID之后的任务运行
  • afterTime: 返回在此时间（RFC3339 时间戳）之后发生的任务运行
  • beforeTime: 返回在此时间之前发生的任务运行（RFC3339 时间戳）
  • limit: 限制返回的任务运行数量（默认是100）
示例

以下示例使用任务 ID 000x00xX0xXXx00。

列出Flux任务的所有运行
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00/runs' \
  --header 'Content-Type: application/json'
列出一个Flux任务的有限运行次数
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00/runs' \
  --header 'Content-Type: application/json' \
  --data-urlencode "limit=10"
在特定运行ID之后列出Flux任务运行
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00/runs' \
  --header 'Content-Type: application/json' \
  --data-urlencode "after=XXX0xx0xX00Xx0X"
列出在时间范围内发生的 Flux 任务运行
curl --GET 'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00/runs' \
  --header 'Content-Type: application/json' \
  --data-urlencode 'afterTime=2021-01-01T00:00:00Z' \
  --data-urlencode 'beforeTime=2021-01-31T00:00:00Z'

重试Kapacitor Flux任务运行

使用以下请求方法和端点来重试Kapacitor Flux任务运行。

POST /kapacitor/v1/api/v2/tasks/{taskID}/runs/{runID}/retry

请在请求中提供以下内容 (* 必填)：

路径参数

  • * taskID: 任务ID
  • * runID: 重试的运行ID
# Retry run ID XXX0xx0xX00Xx0X for task ID 000x00xX0xXXx00
curl --request POST \
  'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00/runs/XXX0xx0xX00Xx0X'

显示任务的所有运行日志

使用以下请求方法和端点来显示Kapacitor Flux任务日志。

GET /kapacitor/v1/api/v2/tasks/{taskID}/log

请在请求中提供以下内容 (* 必填)：

路径参数

  • * taskID: 任务ID
# Get logs for task ID 000x00xX0xXXx00
curl --request GET \
  'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00/logs'

显示特定Flux任务运行的日志

使用以下请求方法和端点来显示特定Kapacitor Flux任务运行的日志。

GET /kapacitor/v1//api/v2/tasks/{taskID}/runs/{runID}/logs

请在请求中提供以下内容 (* 必填)：

路径参数

# Get logs for task ID 000x00xX0xXXx00, run ID XXX0xx0xX00Xx0X
curl --request GET \
  'http://localhost:9092/kapacitor/v1/api/v2/tasks/000x00xX0xXXx00/runs/XXX0xx0xX00Xx0X/logs'

日志记录

日志 API 正在以 技术预览 的形式发布。 Kapacitor 允许用户使用 HTTP 远程检索 Kapacitor 日志 分块传输编码。 日志可以使用对应于日志条目的键值对进行查询。 这些键值对作为查询参数指定。

日志API将以两种格式返回日志：

要接收JSON格式的日志，请指定 Content-Type: application/json。 如果Kapacitor接收到除 application/json 以外的任何内容类型，日志将以logfmt格式返回。

每个返回给客户端的块将包含一个完整的日志，后面跟着一个 \n。

示例

日志以JSON格式

GET /kapacitor/v1preview/logs?task=mytask
Content-Type: application/json

返回以下内容

{"ts":"2017-11-08T17:40:47.183-05:00","lvl":"info","msg":"created log session","service":"sessions","id":"7021fb9d-467e-482f-870c-d811aa9e74b7","content-type":"application/json","tags":"nil"}
{"ts":"2017-11-08T17:40:47.183-05:00","lvl":"info","msg":"created log session","service":"sessions","id":"7021fb9d-467e-482f-870c-d811aa9e74b7","content-type":"application/json","tags":"nil"}
{"ts":"2017-11-08T17:40:47.183-05:00","lvl":"info","msg":"created log session","service":"sessions","id":"7021fb9d-467e-482f-870c-d811aa9e74b7","content-type":"application/json","tags":"nil"}

以 logfmt 格式的日志

GET /kapacitor/v1preview/logs?task=mytask

返回以下内容

ts=2017-11-08T17:42:47.014-05:00 lvl=info msg="created log session" service=sessions id=ce4d7819-1e38-4bf4-ba54-78b0a8769b7e content-type=
ts=2017-11-08T17:42:47.014-05:00 lvl=info msg="created log session" service=sessions id=ce4d7819-1e38-4bf4-ba54-78b0a8769b7e content-type=
ts=2017-11-08T17:42:47.014-05:00 lvl=info msg="created log session" service=sessions id=ce4d7819-1e38-4bf4-ba54-78b0a8769b7e content-type=

测试服务

Kapacitor利用各种服务集成。 以下API端点提供了一种方法，让用户运行简单测试，以确保服务配置正确。

列出可测试的服务

可以在 /kapacitor/v1/service-tests 端点获得可测试的服务列表

查询参数默认值目的
模式*根据模式过滤结果。对服务名称使用标准的shell glob匹配，更多细节请参见this。

示例

GET /kapacitor/v1/service-tests

{
    "link": {"rel":"self", "href": "/kapacitor/v1/service-tests"},
    "services" : [
        {
            "link": {"rel":"self", "href": "/kapacitor/v1/service-tests/influxdb"},
            "name": "influxdb",
            "options": {
                "cluster": ""
            }
        },
        {
            "link": {"rel":"self", "href": "/kapacitor/v1/service-tests/slack"},
            "name": "slack",
            "options": {
                "message": "test slack message",
                "channel": "#alerts",
                "level": "CRITICAL"
            }
        },
        {
            "link": {"rel":"self", "href": "/kapacitor/v1/service-tests/smtp"},
            "name": "smtp",
            "options": {
                "to": ["user@example.com"],
                "subject": "test subject",
                "body": "test body"
            }
        }
    ]
}

响应

代码意义
200成功

测试一个服务

要测试一个服务，向 /kapacitor/v1/service-tests/ 端点发送一个 POST 请求。 POST 请求的主体内容取决于测试中的服务。要确定可用选项，请对相同的端点使用 GET 请求。返回的选项也是默认选项。

示例

要查看Slack服务的可用选项和默认选项，请运行以下请求。

GET /kapacitor/v1/service-tests/slack

{
    "link": {"rel":"self", "href": "/kapacitor/v1/service-tests/slack"},
    "name": "slack"
    "options": {
        "message": "test slack message",
        "channel": "#alerts",
        "level": "CRITICAL"
    }
}

使用自定义选项测试Slack服务集成：

POST /kapacitor/v1/service-tests/slack
{
    "message": "my custom test message",
    "channel": "@user",
    "level": "OK"
}

成功的响应看起来像：

{
    "success": true,
    "message": ""
}

失败的响应看起来像：

{
    "success": false,
    "message": "could not connect to slack"
}

响应

代码意义
200成功，即使被测试的服务失败，仍然会返回200作为测试正确完成的标志。

杂项

ping

您可以“ping”Kapacitor服务器以验证您是否成功连接。 Ping请求只会以204响应。

注意: Kapacitor 服务器版本在所有请求中通过 X-Kapacitor-Version HTTP 头返回。如果您只需要验证您所连接的服务器版本，Ping 是一个有用的请求。

示例

GET /kapacitor/v1/ping

响应：

| Code | Meaning |
| ---- | ------- |
| 204  | Success |

重新加载侧载

您可以通过向 kapacitor/v1/sideload/reload 发送一个空体的HTTP POST请求来触发所有旁加载源的重新加载。

示例

POST /kapacitor/v1/sideload/reload

响应：

| Code | Meaning |
| ---- | ------- |
| 204  | Success |

/debug/vars HTTP 端点

Kapacitor 通过 /debug/vars 端点公开统计信息和运行时信息，可以使用以下 cURL 命令访问：

curl http://localhost:9092/kapacitor/v1/debug/vars

服务器统计信息以JSON格式显示。

注意： 您可以使用Telegraf Kapacitor 输入插件从指定的Kapacitor实例收集指标（使用/debug/vars端点）。有关测量和字段的列表，请参见插件README。

/debug/pprof HTTP 端点

Kapacitor 支持 Go net/http/pprof 端点，这对于故障排除很有帮助。pprof 包提供了 pprof 可视化工具所需的运行时分析数据。

curl http://localhost:9092/kapacitor/v1/debug/pprof/

此 /debug/pprof/ 端点生成一个包含内置 Go 配置文件列表及每个文件超链接的 HTML 页面。

个人信息描述
块导致在同步原语上阻塞的堆栈跟踪。
goroutine所有当前 goroutine 的堆栈跟踪。
堆对堆分配的堆栈跟踪进行采样。
互斥锁竞争互斥锁的持有者的堆栈跟踪。
threadcreate导致新操作系统线程创建的堆栈跟踪。

要访问上面列出的其中一个 /debug/pprof/ 配置文件，请使用以下 cURL 请求，将 替换为配置文件的名称。结果配置文件输出到指定的文件中，路径为 。

curl -o <path/to/output-file> http://localhost:9092/kapacitor/v1/debug/pprof/<profile>

在以下示例中，cURL 命令将生成的堆配置文件输出到指定的 文件中：

curl -o <path/to/output-file> http://9092/kapacitor/v1/debug/pprof/heap

您也可以使用Go pprof 交互工具访问Kapacitor /debug/pprof/ 配置文件。
例如，要使用此工具查看Kapacitor实例的堆配置文件，您可以使用如下命令：

go tool pprof http://localhost:9092/kapacitor/v1/debug/pprof/heap

有关 Go /net/http/pprof 包和交互式 pprof 分析与可视化工具的更多信息，请参见：

路线

显示可用的API路由

GET /kapacitor/v1/:routes
© 2025 InfluxData, Inc.

你在哪里运行InfluxDB？

选择您的 InfluxDB Cloud 区域和集群 或您的 InfluxDB OSS URL，我们将为您定制代码示例。 识别您的 InfluxDB Cloud 集群。

  • InfluxDB Cloud
  • InfluxDB OSS or Enterprise
AWS

  • 美国西部（俄勒冈州）

谷歌云平台
微软 Azure
默认
自定义

有关更多信息，请参见 InfluxDB Cloud regions 或 InfluxDB OSS URLs。

感谢您的反馈!

让我们知道我们可以做得更好的地方：

谢谢！

No thanks

Flux的未来

Flux 正在进入维护模式。您可以像现在一样继续使用它，而无需对您的代码进行任何更改。

阅读更多

InfluxDB 3 开源版本现已公开Alpha测试

InfluxDB 3 Open Source is now available for alpha testing, licensed under MIT or Apache 2 licensing.

我们将发布两个产品作为测试版的一部分。

InfluxDB 3 核心，是我们新的开源产品。 它是一个用于时间序列和事件数据的实时数据引擎。 InfluxDB 3 企业版是建立在核心基础之上的商业版本，增加了历史查询能力、读取副本、高可用性、可扩展性和细粒度安全性。

有关如何开始的更多信息，请查看：