文档文档

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

为了让您控制 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 接受使用 InfluxData 的 Line Protocol 数据格式 通过 HTTP 写入数据。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、类型、TICKscript 以及允许访问的数据库保留策略对列表定义。

定义或更新任务

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

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

属性用途
id任务的唯一标识符。如果为空，将选择随机 ID。
template-id（可选）要使用的模板 ID，而不是指定 TICKscript 和类型。
type任务类型：stream 或 batch。
dbrps任务允许访问的数据库保留策略对列表。
script脚本的内容。
statusenabled 或 disabled 之一。
vars一组用于覆盖 TICKscript 中任何已定义变量的变量。

使用 PATCH 时，如果缺少任何属性，则任务将保持未修改状态。

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

变量

变量对象具有以下形式

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

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

类型示例值描述
booltrue“true” 或 “false”
int42任意整数值
float2.5 或 67任意数值
duration“1s” 或 1000000000以纳秒为单位解释的任何整数值或 influxql 持续时间字符串，（即 10000000000 为 10 秒）
string“a string”任意字符串值
regex“^abc.*xyz”表示有效的 Go 正则表达式的任意字符串值 https://golang.ac.cn/pkg/regexp/
lambda“"value" > 5”任何作为有效 TICKscript lambda 表达式的字符串
star""不需要值，星号类型变量表示 TICKscript 中的字面量 *（即 .groupBy(*)）
list[{“type”: TYPE, “value”: VALUE}]变量对象列表。当前列表只能包含字符串或星号变量

示例

创建 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 请求。

查询参数默认用途
dot-viewattributeslabels 或 attributes 之一。标签的可读性较差，但可以正确呈现标签中包含的所有信息。
script-formatformattedformatted 或 raw 之一。Raw 将返回与定义方式相同的脚本。Formatted 将首先格式化脚本。
replay-id正在运行的回放的可选 ID。返回的任务信息将位于正在运行的回放的任务上下文中。

除了 上面 列出的属性外，任务还具有以下只读属性。

属性描述
dotGraphViz DOT 语法格式的任务 DAG 表示。
executing任务当前是否正在执行。
error执行任务时遇到的任何错误。
stats有关任务的统计信息映射。
created任务首次创建的日期
modified任务上次修改的日期
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 请求。

查询参数默认用途
pattern根据模式过滤结果。使用标准 shell glob 匹配，有关更多详细信息，请参阅 此处。
fields要返回的字段列表。如果为空，则返回所有字段。始终返回字段 id 和 link。
dot-viewattributeslabels 或 attributes 之一。标签的可读性较差，但可以正确呈现标签中包含的所有信息。
script-formatformattedformatted 或 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。
type模板类型：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 请求。

查询参数默认用途
script-formatformattedformatted 或 raw 之一。Raw 将返回与定义方式相同的脚本。Formatted 将首先格式化脚本。

除了 上面 列出的属性外，模板还具有以下只读属性。

属性描述
vars来自 TICKscript 的命名变量集，包含其类型、默认值和描述。
dotGraphViz DOT 语法格式的模板 DAG 表示。注意：标签与属性无关紧要，因为模板永远不会执行。
error读取模板时遇到的任何错误。
created模板首次创建的日期
modified模板上次修改的日期

示例

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

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 请求。

查询参数默认用途
pattern根据模式过滤结果。使用标准 shell glob 匹配，有关更多详细信息，请参阅 此处。
fields要返回的字段列表。如果为空，则返回所有字段。始终返回字段 id 和 link。
script-formatformattedformatted 或 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 请求。

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

请求在录制开始后立即返回，并且不等待其完成。返回录制 ID 以便稍后标识录制。

Stream
参数用途
id录制的唯一标识符。如果为空，将选择一个随机标识符。
task任务的 ID，用于仅录制任务的 DBRP 的数据。
stop录制流数据直到停止日期。
Batch
参数用途
id录制的唯一标识符。如果为空，将选择一个随机标识符。
task任务的 ID，录制任务中定义的查询结果。
start将要录制数据的最早日期。RFC3339Nano 格式。
stopend
将要录制数据的最晚日期。如果未指定，则使用当前时间。RFC3339Nano 格式数据。
参数用途
id录制的唯一标识符。如果为空，将选择一个随机标识符。
typeQuery
query录制类型，stream 或 batch。
query要执行的查询。

cluster

示例

配置的 InfluxDB 集群的名称。如果为空，则使用默认集群。

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

注意：录制本身类型为流录制或批处理录制，并且只能回放到相应类型的任务。因此，当您录制原始查询的结果时，必须指定要创建的录制类型。

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

使用 stream 方法创建录制

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

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

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

使用 query 方法创建录制，指定 stream 类型。

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"
}

响应

使用 query 方法创建录制，指定 batch 类型。

{
    "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创建具有自定义 ID 的录制。

等待录制

所有录制都分配有一个 ID，该 ID 以此格式返回，并带有链接。

成功，录制已开始。

属性描述
为了确定录制何时完成，您必须向返回的链接发出 GET 请求，通常类似于 /kapacitor/v1/recordings/RECORDING_ID。录制具有以下只读属性。
size磁盘上录制的大小（以字节为单位）。
errordate
status录制完成的日期。
error创建录制时遇到的任何错误。

示例

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
}

status

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
}

recording 或 finished 之一。

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
}

响应

代码含义
200progress
202介于 0 和 1 之间的数字，指示录制的大概进度。
404录制完成后。

删除录制

或者如果录制失败。

DELETE /kapacitor/v1/recordings/RECORDING_ID

响应

代码含义
204成功

成功，录制不再运行。

列出录制

成功，录制存在但未完成。

查询参数默认用途
pattern根据模式过滤结果。使用标准 shell glob 匹配，有关更多详细信息，请参阅 此处。
fields要返回的字段列表。如果为空，则返回所有字段。始终返回字段 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成功

管理回放

不存在此类录制。

回放数据而不录制

参数默认用途
id等待回放删除回放
task列出回放
要回放录制，请向 /kapacitor/v1/replays/ 发出 POST 请求random
回放的唯一标识符。如果为空，则选择随机 ID。task任务的 ID。
recording录制的 ID。recording-time

示例

false

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

如果为 true，则使用录制中的时间，否则相对于当前时间调整时间。

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

clock

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

响应

fast

{
    "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": {},
}
代码含义
201fast 或 real 之一。如果为 real，则等待与录制中的时间相对应的实际时间过去。如果为 fast，则无延迟地回放数据。例如，如果时钟为 real，则持续时间为 5 分钟的流录制将需要 5 分钟才能回放。

要删除录制，请向 /kapacitor/v1/recordings/RECORDING_ID 端点发出 DELETE 请求。

使用默认参数回放录制。

方法描述
batch以实时模式回放录制并保留录制时间。
query使用自定义 ID 回放录制。
Batch
参数默认用途
id等待回放请求在回放开始后立即返回，并提供回放 ID 和链接。
task成功，回放已开始。
start也可以直接回放数据，而无需先录制数据。这是通过发出类似于 batch 或 query 录制的请求来完成的，但它不是存储数据，而是立即针对任务回放数据。使用 stream 录制立即针对任务回放数据等同于启用任务，因此不支持。
stop回放批处理任务中查询的结果。回放显式查询的结果。
回放的唯一标识符。如果为空，则选择随机 ID。task任务的 ID。
recording录制的 ID。recording-time
将要录制数据的最晚日期。如果未指定，则使用当前时间。RFC3339Nano 格式数据。
参数默认用途
id等待回放请求在回放开始后立即返回，并提供回放 ID 和链接。
taskrandom
query录制类型，stream 或 batch。
query要执行的查询。
回放的唯一标识符。如果为空，则选择随机 ID。task任务的 ID。
recording录制的 ID。recording-time

示例

回放的唯一标识符。如果为空，则选择随机 ID。

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

task

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)",
}

响应

start

{
    "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": {}
}

将要回放数据的最早日期。RFC3339Nano 格式。

代码含义
201end

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

将要回放数据的最晚日期。如果未指定，则使用当前时间。RFC3339Nano 格式数据。

task

属性描述
status任务的 ID，针对任务回放查询结果。
error使用 batch 方法执行回放，指定开始时间。
error针对任务回放查询结果。

示例

创建具有自定义 ID 的回放。

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": {}
}

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

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
            }
        }
    }
}

注意：对于以这种方式创建的回放，recording ID 将为空，因为未使用或创建任何录制。

成功，回放已开始。

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与录制一样，您可以向 /kapacitor/v1/replays/REPLAY_ID 端点发出 GET 请求，以获取回放的状态。
202除了 上面 列出的属性外，回放还具有以下只读属性。
404status

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

replaying 或 finished 之一。

DELETE /kapacitor/v1/replays/REPLAY_ID

响应

代码含义
204成功

progress

回放录制

介于 0 和 1 之间的数字，指示回放的大概进度。

查询参数默认用途
pattern根据模式过滤结果。使用标准 shell glob 匹配，有关更多详细信息，请参阅 此处。
fields要返回的字段列表。如果为空，则返回所有字段。始终返回字段 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" : ""
        }
    ]
}

管理警报

error

执行回放时发生的任何错误

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

获取回放的状态。

主题

创建和删除主题

示例

DELETE /kapacitor/v1/alerts/topics/system

回放完成后。

列出主题

查询参数默认用途
主题状态列出主题事件主题事件
pattern*列出主题处理程序

示例

获取主题处理程序

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"
        }
    ]
}

如果回放已完成，则 stats 字段包含有关回放的统计信息。

更新主题处理程序

示例

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"},
}

或者如果回放失败。

删除主题处理程序

查询参数默认用途
主题状态列出主题事件警报分组到主题中。警报处理程序“侦听”主题中的任何新事件。您可以在 TICKscript 中指定警报主题，或者将为您生成一个。

示例

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"
            }
        }
    ]
}

成功，回放不再运行。

当在 TICKscript 或处理程序中引用主题时，会动态创建主题。要删除主题，请向 /kapacitor/v1/alerts/topics/<topic id> 发出 DELETE 请求。这将删除主题的所有已知事件和状态。

示例

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"
    }
}

成功，回放存在但未完成。

注意：由于主题是动态创建的，因此如果为主题创建了新事件，则主题可能会在删除后重新返回。

查询参数默认用途
pattern*要查询可用主题列表，请向 /kapacitor/v1/alerts/topics 发出 GET 请求。

min-level

示例

OK

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"
        }
    ]
}

仅返回大于或等于 min-level 的主题。有效值包括 OK、INFO、WARNING、CRITICAL。

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
}

不存在此类回放。

pattern

示例

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/replays/REPLAY_ID 端点发出 DELETE 请求。

根据模式过滤结果。使用主题 ID 上的标准 shell glob 匹配，有关更多详细信息，请参阅 此处。

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": ""
}

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

获取所有主题。

获取 WARNING 或 CRITICAL 状态下的所有主题。

要查询主题的状态，请向 /kapacitor/v1/alerts/topics/<topic id> 发出 GET 请求。

示例

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

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": ""
}

min-level

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/replays 发出 GET 请求来列出给定录制的回放。

仅返回大于或等于 min-level 的事件。有效值包括 OK、INFO、WARNING、CRITICAL。

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

您可以向 /kapacitor/v1/alerts/topics/<topic id>/events/<event id> 发出 GET 请求，以查询主题中的特定事件。

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

pattern

启用和禁用配置覆盖

默认情况下，覆盖配置的功能是启用的。如果您不希望启用此功能，可以通过 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/<section name>/[<element name>]

示例

/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/<name of store> 发出 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 对象

属性描述
name用户名
password密码
type用户类型 (normal 或 admin，参见 User)
permissions有效用户权限字符串列表 (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/<name> 端点。

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

属性用途
password密码
type用户类型 (normal 或 admin，参见 User)
permissions有效用户权限字符串列表 (none, api, config_api, write_points, all)

示例

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

删除用户

要删除用户，请使用 DELETE 请求方法和 /kapacitor/v1/users/<name> 端点。

示例

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

管理 Flux 任务

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

创建 Flux 任务

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

POST /kapacitor/v1/api/v2/tasks

在您的请求中提供以下内容 (* 必需)

标头

  • * Content-type: application/json

请求正文

具有以下模式的 JSON 对象

  • * flux: Flux 任务代码
  • status: Flux 任务状态 (active 或 inactive，默认为 active)
  • description: 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

在您的请求中提供以下内容 (* 必需)

标头

  • * Content-type: application/json

查询参数

  • after: 列出特定任务 ID 之后的任务
  • limit: 限制返回的任务数量 (默认为 500)
  • name: 按名称过滤任务
  • status: 按状态过滤任务 (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}

在您的请求中提供以下内容 (* 必需)

标头

  • * Content-type: application/json

路径参数

  • * taskID: 要更新的任务 ID

请求正文

具有以下模式的 JSON 对象

  • cron: 覆盖 cron Flux 任务选项
  • description: 新任务描述
  • every: 覆盖 every Flux 任务选项
  • flux: 新 Flux 任务代码
  • name: 覆盖 name Flux 任务选项
  • offset: 覆盖 offset Flux 任务选项
  • status: 新 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

在您的请求中提供以下内容 (* 必需)

标头

  • * Content-type: 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 端点获取

查询参数默认用途
pattern*要查询可用主题列表，请向 /kapacitor/v1/alerts/topics 发出 GET 请求。

示例

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/<service name> 端点发出 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 |

重新加载 sideload

您可以通过向 kapacitor/v1/sideload/reload 发送 HTTP POST 请求（正文为空）来触发重新加载所有 sideload 源。

示例

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/ 端点生成一个 HTML 页面，其中包含内置 Go 性能分析列表以及每个性能分析的超链接。

性能分析描述
block导致阻塞同步原语的堆栈跟踪。
goroutine所有当前 goroutine 的堆栈跟踪。
heap堆分配的堆栈跟踪采样。
mutex持有争用互斥锁的持有者的堆栈跟踪。
threadcreate导致创建新操作系统线程的堆栈跟踪。

要访问上面列出的 /debug/pprof/ 性能分析之一，请使用以下 cURL 请求，将 <profile> 替换为性能分析的名称。生成的性能分析输出到文件，为 <path/to/output-file> 指定的文件。

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

在以下示例中，cURL 命令将生成的堆性能分析输出到 <path/to/output-file> 中指定的文件

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 或 Enterprise
AWS

  • 美西（俄勒冈）

GCP
Azure
默认
自定义

有关更多信息，请参见 InfluxDB Cloud 区域 或 InfluxDB OSS URL。

感谢您的反馈！

请告诉我们如何做得更好

谢谢！

不用了，谢谢

Flux 的未来

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

阅读更多

现已全面上市

InfluxDB 3 Core 和 Enterprise

快速启动。更快扩展。

获取更新

InfluxDB 3 Core 是一个开源、高速、近实时数据引擎，可实时收集和处理数据，并将其持久化到本地磁盘或对象存储。InfluxDB 3 Enterprise 构建在 Core 的基础上，增加了高可用性、只读副本、增强的安全性以及数据压缩，以实现更快的查询和优化的存储。InfluxDB 3 Enterprise 的免费层可供非商业家庭或业余爱好者使用。

有关更多信息，请查看