跳转到主要内容
POST
查询 RUM 数据

时间范围对齐与缓存

为便于重复查询复用缓存结果,聚合查询的时间范围会被对齐到网格:
  • format=time_series:起始时间向下、结束时间向上取整到 interval。时间桶的数量和位置不变,首尾两个桶覆盖完整区间,而不是部分区间。
  • 聚合(非时序)查询:起始时间向下、结束时间向上取整到 max(1 分钟, 时间范围 ÷ 1226 向上取到下一个标准间隔档),例如 24 小时对齐到 2 分钟,7 天对齐到 10 分钟,30 天对齐到 1 小时。时间范围短于 100 个网格步长时不对齐、不缓存。起始端最多多出一个网格步长的数据;结束端取整到未来,该部分没有数据。
  • 明细/列表查询(无聚合、分页),以及 SQL 中含有 now() 等随执行时间变化的函数的查询,不做对齐也不缓存。
最近时间的数据结果最多可能滞后 60 秒。

限制说明

使用说明

  • 单次请求可提交 1 到 10 个查询;每个查询的 id 会成为响应对象中的 key。
  • start_time、end_time 为 Unix 毫秒时间戳,跨度不超过 31 天。服务端会自动追加时间范围与账户过滤条件,sql 中无需再写。
  • FROM 填写 RUM 数据表名:sessions、views、actions、errors、resources、long_tasks、vitals、issues 或 sourcemaps(也接受单数形式)。列名即 POST /rum/field/list 返回的 field_key。
  • 若查询在顶层 AND 条件中用 = 或 IN 限定了 application_id,调用者必须能读取这些应用:所属团队不包含调用者的私有应用会让整个请求返回 AccessDenied,不存在的应用返回 ResourceNotFound,单次请求最多涉及 50 个不同应用。未限定应用的查询会自动跳过调用者无权读取的私有应用。
  • SQL 语法错误、time_zone 无效或时间范围不合法时,整个请求返回 InvalidParameter。之后阶段才失败的查询(表或列不存在、search_after_ctx 无效、数据库报错)只在该查询自己的结果中返回 error,错误码为 InternalError,其他查询仍正常返回 data;dql 解析失败同样只影响该查询,错误码为 InvalidParameter,报错信息带上该查询原文。
  • values 按列组织:values[i] 是列 fields[i] 在所有行上的取值。
  • table 查询最多返回 1,000 行;未写 LIMIT 或超过 1,000 时按 1,000 处理。不含聚合、带 ORDER BY 且没有 OFFSET 的查询在本页取满时会返回 search_after_ctx,用相同的 sql 带上它即可取下一页。
  • time_series 查询会在最前面插入 ts 列(时间桶起点,Unix 毫秒),并按它分组、排序。桶宽以毫秒在 interval 中返回,取值为固定档位(1、2、5、10、20、50、100、200、500 毫秒;1、2、5、10、15、30 秒;1、2、5、10、15、30 分钟;1、2、3、6、12 小时;1、2、3、7 天;30、60、90、180 天)中同时不小于 interval 和「时间跨度 ÷ max_points」的最小一档。
  • 时间跨度较大时,聚合查询可能基于抽样数据执行;此时响应带有 sampling,且 COUNT、SUM、COUNT(DISTINCT) 列已乘以 scale_factor。设置 disable_sampling: true 可始终查询全量数据。

授权

app_key
string
query
必填

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

请求体

application/json

指定时间范围内的一组 RUM 数据查询。

end_time
integer<int64>
必填

查询窗口结束时间,Unix 毫秒时间戳。最大跨度 31 天。

示例:

1712707200000

queries
object[]
必填

并发执行的查询列表,允许 1 到 10 个。

Required array length: 1 - 10 elements
start_time
integer<int64>
必填

查询窗口起始时间,Unix 毫秒时间戳。

示例:

1712620800000

响应

成功

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

request_id
string
必填

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

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

从请求中的查询 ID 到该查询结果或错误的映射。