跳转到主要内容
POST
查询结构化数据

调用限制

使用说明

  • 数据源由 ds_type 加 ds_name 指定,而不是数据源 ID。数据源必须属于当前账户且已启用。若数据源限制了可查询的团队,只有这些团队的成员、其管理团队以及账户所有者或管理员可以查询,其他人会收到 AccessDenied。
  • 此公开接口以 monit-edge v0.65.0 为最低受支持版本。迁移期间,WebAPI 仍保留旧版 Edge 适配器:query.v2 结果仍可能保留 frames、records 或 samples,而 legacy rows 只能提供其已保留的信息。这些适配器不会改变最低支持版本;旧协议缺少 query.v3 的取消和错误生命周期语义,legacy rows 已丢失的数据也无法恢复。
  • 公开响应格式固定为 query_result.v1,与 Edge 内部查询协议版本无关。必须根据 result.kind(frames、records 或 samples)分发结果,不要根据 ds_type 或 Edge 版本猜测结果形态。
  • frames 结果可以包含多个表格或时序 Frame。字段值按列组织,同一 Frame 中所有字段的值数量一致。
  • records 结果可以包含嵌套 JSON 和 null record。超出 JavaScript 安全整数范围的整数字面量会以十进制字符串返回。
  • samples 结果包含标签集合和瞬时值。值可以是数字,也可以是字符串 NaN、+Inf 或 -Inf。
  • Prometheus 表达式在下发查询前会做语法检查,表达式非法时返回 HTTP 400。
  • 请求体上限为 256 KiB,完整成功响应上限为 10 MiB,超限均返回 HTTP 413。结果超过 1,000 行时返回 HTTP 400。请缩短时间范围、减少字段或在数据源侧聚合。
  • 查询失败使用非 2xx HTTP 状态码和标准错误 envelope。
  • WebAPI 跨实例转发和 Edge 执行合计可能耗时 35 秒。客户端超时建议至少设为 40 秒,并在调用方放弃查询时向下传播取消信号。

授权

app_key
string
query
必填

在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 app_key 或请求头 Fd-App-Key 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集,请妥善保管。

请求体

application/json

结构化查询接口的请求体。

ds_type
enum<string>
必填

数据源类型,需要与 ds_name 一起匹配账户下一个已启用的数据源。

  • prometheus:Prometheus 兼容数据源,expr 为 PromQL。
  • loki:Grafana Loki,expr 为 LogQL。
  • victorialogs:VictoriaLogs。
  • sls:阿里云日志服务(SLS)。
  • tencent_cls:腾讯云日志服务(CLS),需要 monit-edge v0.66.0 或更高版本。
  • elasticsearch:Elasticsearch。
  • mysql:MySQL,expr 为 SQL。
  • postgres:PostgreSQL,expr 为 SQL。
  • oracle:Oracle 数据库,expr 为 SQL。
  • clickhouse:ClickHouse,expr 为 SQL。

其他数据源类型(例如 MongoDB、Redis、Kafka)会被拒绝。

可用选项:
clickhouse,
elasticsearch,
loki,
mysql,
oracle,
postgres,
prometheus,
sls,
tencent_cls,
victorialogs
ds_name
string
必填

数据源名称,可从 /monit/datasource/list 获取。数据源必须已启用;账户下不存在该名称的数据源时返回 HTTP 400。

expr
string
必填

使用 ds_type 对应查询语言的表达式(prometheus 为 PromQL,loki 为 LogQL,SQL 类数据源为 SQL,等等)。必填,最大 64 KiB(tencent_cls 为 12 KiB)。此接口不支持 Loki 的 $__auto,请使用固定时长,例如 [5m]。Prometheus 表达式在下发前会做语法检查。

Minimum string length: 1
account_id
integer<int64>

可选的一致性校验。若提供,必须等于已认证账户,否则请求以 AccessDenied 失败。查询始终以已认证账户执行。

delay_seconds
integer
默认值:0

回看偏移,单位秒,取值 0 到 86400。应用于点查询(Prometheus、Loki stats、VictoriaLogs stats);明细 / raw 查询忽略该字段。当 args 带有绝对时间 <source>.time 且 Edge 为 v0.74.0 或更高版本时,以绝对时间为准,不再应用此偏移。

必填范围: 0 <= x <= 86400
args
object

额外的查询参数,字符串键值对;键按数据源加前缀(例如 sls.project、loki.type)。最多 128 项,键最长 256 字节,值最长 64 KiB,总计不超过 128 KiB。可接受的参数取决于 ds_type:

  • prometheus:可选 prometheus.time,评估时间,Unix 秒,不能晚于当前时间。
  • loki、victorialogs:<source>.type 取 stats(默认)或 raw。stats 可带 <source>.time(Unix 秒,不能晚于当前时间)。raw 必须给出时间范围,可用 <source>.start + <source>.end(Unix 秒),或 <source>.timespan.value + <source>.timespan.unit(s、m、h 或 d),跨度不超过 6 小时,并可带 <source>.limit,取值 1 到 1001。
  • sls:必须提供 sls.project 和 sls.logstore。可选 sls.lines(1 到 100)、sls.offset(0 或更大),以及不超过 6 小时的时间范围,可用 sls.from + sls.to(Unix 秒)或 sls.timespan.value + sls.timespan.unit 给出。
  • tencent_cls:必须提供 tencent_cls.region、tencent_cls.topic_id、tencent_cls.query_mode(raw 或 analysis)和 tencent_cls.syntax(cql 或 lucene)。可选 tencent_cls.limit(1 到 100,仅 raw 模式,需要 monit-edge v0.67.0 或更高版本),以及时间范围,可用 tencent_cls.from + tencent_cls.to(Unix 秒)或 tencent_cls.timespan.value + tencent_cls.timespan.unit 给出,raw 模式不超过 6 小时,analysis 模式不超过 24 小时。其他任何键都会被拒绝。
  • elasticsearch:es.type 只能为 sql 或不传,其他值会被拒绝。
  • mysql、postgres、oracle、clickhouse:未定义任何参数。

绝对时间 <source>.time 只对其对应的数据源类型有效。v0.74.0 之前的 Edge 通过回看偏移近似实现,且只接受最近 86,400 秒内的时间。

响应

成功

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

request_id
string
必填

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

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

与 Edge 版本无关的稳定结构化查询响应。