草料开放平台文档

简体中文

English

简体中文

English

主题

按指标出数 ​

数据分析的主力接口。回答「多少、占比、分布、趋势」类问题：给定指标名和时间窗，返回数字；加 group_by 得到分布；每个分组结果自带下钻条件——原样传给 检索记录行摘要，就能看到构成这个数字的具体记录。

请求示例 ​

python
import requests

url = "https://open.cli.im/api/v2/rpc/metrics/query"
data = {
    "metric": "record_submission_count",
    "time": {"from": 1751299200, "to": 1756684800},
    "group_by": "project"
}
headers = {
    "Authorization": "Bearer <你的API Key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=data, headers=headers)
print(response.text)
bash
curl -X POST 'https://open.cli.im/api/v2/rpc/metrics/query' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"metric":"record_submission_count","time":{"from":1751299200,"to":1756684800},"group_by":"project"}'

请求参数 ​

参数类型必填说明
metricstring是指标名，从 指标目录 取
timeobject是时间窗（epoch 秒）：{"from": 起始, "to": 结束}，两端都含。结束时间超过当前时间会被自动截断到现在
group_bystring否分组维度，必须在该指标 dimensions 声明的范围内。记录类指标支持：form（表单）、qrcode（活码）、project（分区）、process_status_text（处理进度）、result_value_text（结果值）、day（按日）、month（按月）
scopeobject否统计范围过滤，键见下表
limitinteger否分组条数上限，默认 30，上限 200

scope 过滤键 ​

键类型说明
form_idsstring[]限定到这些表单
qrcode_idsstring[]限定到这些活码
project_idsstring[]限定到这些分区
member_idsstring[]限定到这些提交人
process_statusinteger[]限定处理进度（数值枚举）
process_status_textstring[]限定处理进度文本，如 待处理
audit_stage_idsstring[]限定当前审核阶段
auditor_user_idsstring[]限定审核人
state_idsstring[]限定状态变更涉及的状态
result_valuesstring[]限定结果值（多选型），如 合格
result_value_textsstring[]限定结果值文本（单值型）
field_equalsobject[]表单字段精确匹配：[{"field_id": "…", "value": "…"}]

完整返回示例 ​

按分区统计最近两个月的记录提交量：

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "result": {
      "metric": "record_submission_count",
      "title": "记录提交量",
      "format": "integer",
      "time": { "from": 1751299200, "to": 1756684800 },
      "group_by": "project",
      "result": {
        "value": null,
        "groups": [
          {
            "group_key": "1104",
            "group_label": "消防管理",
            "value": 240,
            "drill_down": {
              "filters": { "project_ids": ["1104"] },
              "time": { "from": 1751299200, "to": 1756684800 }
            }
          },
          {
            "group_key": "1101",
            "group_label": "初始分区",
            "value": 46,
            "drill_down": {
              "filters": { "project_ids": ["1101"] },
              "time": { "from": 1751299200, "to": 1756684800 }
            }
          }
        ]
      },
      "drill_down": { "filters": {}, "time": { "from": 1751299200, "to": 1756684800 } }
    },
    "notes": [
      "按记录提交时间（record_add_time）落在时间窗内筛选。",
      "已删除的记录不计入。"
    ]
  }
}

不带 group_by 时返回单值：result.value 为 {"group_key": null, "value": 286}，result.groups 为空数组。

响应结构 ​

路径类型说明
data.result.result.valueobject|null无 group_by 时的单值；有 group_by 时为 null
data.result.result.groups[]array分组结果，按数值降序
groups[].group_keystring|null分组键。form/qrcode/project 维度下是 ID，展示请用 group_label；此键用于下钻
groups[].group_labelstring|null分组的可读名（表单名/分区名/码名）；解析不到时回落为 group_key
groups[].valuenumber该组的数值
groups[].numerator / denominatornumber比例类指标附带的分子、分母
groups[].breakdownobject计划类指标附带的四桶明细（done/missed/pending/skipped，加总恒等于 planned）
groups[].drill_downobject这一组自己的下钻条件：{filters, time} 原样传给 检索记录行摘要，即可看到构成这个数字的记录
data.result.drill_downobject|null整个结果范围的下钻条件；计划类指标为 null（它的数不落在记录上）
data.notes[]array口径提示：统计范围、软删过滤、名字解析失败等，逐条阅读

提示：group_label 为空字符串对应的占位符是 (未填写)——它是有效值（该字段没填的记录），往往还是最大的一组，同样可以下钻。

接入建议 ​

  • 数数用本接口，不要通过拉记录列表自己数——又慢又容易超出返回上限
  • 做报表时用 group_label 展示、用 drill_down 做「点击查看明细」
  • 时间对比（环比/趋势）用 group_by: "day" 或 "month" 一次拿到序列

错误响应 ​

json
{
  "code": 400,
  "message": "invalid_argument: 维度 \"plan_target_form\" 不适用于 record_submission_count；可用维度：form / qrcode / project / process_status_text / result_value_text / day / month",
  "data": {}
}

常见错误：

  • invalid_argument — 时间窗缺失/倒置、维度不在该指标的 dimensions 内、scope 有不认识的键
  • metric_not_found — 指标名不存在
  • query_timeout — 查询超时；收窄时间窗或减少分组后再试，不要原样立即重试
  • upstream_unavailable — 查询通道暂不可用，稍后再试

其余错误码定义见：错误码说明。