跳转到主要内容
POST
/
monit
/
tools
/
invoke
调用监控对象工具
curl --request POST \
  --url 'https://api.flashcat.cloud/monit/tools/invoke?app_key=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": 10001,
  "target_locator": "web-01",
  "tools": [
    {
      "tool": "os.overview",
      "params": {}
    },
    {
      "tool": "net.tcp_ping",
      "params": {
        "host": "10.0.0.10",
        "port": 3306
      }
    }
  ]
}
'
{
  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
  "data": {
    "target": {
      "kind": "host",
      "locator": "web-01"
    },
    "results": [
      {
        "tool": "os.overview",
        "tool_version": "0.5.0",
        "data": {
          "data": {
            "sample_interval_sec": 3,
            "degraded": false,
            "degradation_reasons": []
          },
          "summary": "os.overview ...",
          "truncated": {
            "truncated": false
          }
        },
        "error": null,
        "agent_elapsed_ms": 3120,
        "e2e_elapsed_ms": 3188
      },
      {
        "tool": "net.tcp_ping",
        "tool_version": "0.5.0",
        "data": null,
        "error": {
          "code": "target_unreachable",
          "message": "dial tcp 10.0.0.10:3306: i/o timeout"
        },
        "agent_elapsed_ms": 0,
        "e2e_elapsed_ms": 2008
      }
    ],
    "error": null
  }
}

调用限制

速率限制600 次/分钟;10 次/秒 每账户
权限任意有效的 app_key(只读;不受特定权限分类约束)

使用说明

  • 单次调用至多 8 个工具(MaxToolsPerInvoke);超出需在客户端拆分。8 个工具的上限与单监控对象 Agent 的并发能力对齐。
  • 工具在 Agent 上并行执行;webapi 返回的 results[] 与请求中的 tools[] 顺序对齐。
  • 长耗时:客户端超时至少设置 35 秒。该接口面向 AI-SRE / 人工排障流程,不适用于交互式 UI。
  • 请求级错误(target_unavailableambiguous_target_kindunknown_toolset_hashforward_failed)以 HTTP 200 返回,data.error 不为空,data.results = []
  • 单工具失败以 HTTP 200 返回,data.error = null,results[i].error 被填充——务必同时检查三层(外层信封 errordata.error、再到每个 results[i].error)。
  • 每条结果带两个耗时字段:agent_elapsed_ms(Agent 自报,不含网络)与 e2e_elapsed_ms(webapi 观测的端到端)。两者差距较大表示网络 / 边缘侧慢,而非工具执行慢。
  • /monit/tools/catalog 返回的 input_schema 构造 tools[].params。对于无参工具,务必显式传 params: {}

授权

app_key
string
query
必填

在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证,请妥善保管。

请求体

application/json
target_locator
string
必填

监控对象标识。校验规则与 /monit/tools/catalog 相同。

tools
object[]
必填

至多 8 个工具调用;webapi 会并发执行,并按入参顺序返回结果。

Required array length: 1 - 8 elements
account_id
integer<int64>

可选的一致性校验。若提供,必须等于已认证账户。

target_kind
string

可选的 target kind;省略时自动推断。

响应

成功

成功响应结构。2xx 响应中 request_id 标识本次调用(同时出现在 Flashcat-Request-Id 响应头中),data 为接口业务 payload。失败响应使用不同结构,参见 ErrorResponse

request_id
string
必填

本次请求的唯一 ID,也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object
必填

每个接口自己的业务 payload,详见各接口的 200 响应 schema。