草料开放平台文档

简体中文

English

简体中文

English

主题

检索记录行摘要 ​

按多维条件检索记录的行摘要——每行包含记录的关键属性和还原出的「字段名 = 值」。主要用途是承接 按指标出数 返回的下钻条件：把某个分组的 drill_down 原样传入，就能看到构成那个数字的具体记录。

与 获取记录列表 的分工：

本接口（searchRecords）getRecords
定位分析下钻、条件检索完整数据读取、数据同步
返回行摘要（关键属性 + 字段名值对）记录完整渲染
翻页无翻页，limit 封顶 200支持 page_token 翻页
附带同条件总数 total总数 + 下一页游标

注：本接口刻意不提供翻页。结果不够用时，收窄时间窗或增加过滤条件；要总量用 metrics/query。

请求示例 ​

python
import requests

url = "https://open.cli.im/api/v2/rpc/record/searchRecords"
data = {
    "filters": {"project_ids": ["1104"]},
    "time": {"from": 1751299200, "to": 1756684800},
    "limit": 50
}
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/record/searchRecords' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"filters":{"project_ids":["1104"]},"time":{"from":1751299200,"to":1756684800},"limit":50}'

请求参数 ​

参数类型必填说明
filtersobject否过滤条件，键与 metrics/query 的 scope 完全一致（form_ids、project_ids、qrcode_ids、process_status_text、result_value_texts、field_equals 等）
timeobject否时间窗（epoch 秒），from/to 两端都可以只给一边
limitinteger否返回条数，默认 50，上限 200

完整返回示例 ​

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "result": {
      "rows": [
        {
          "record_id": "900123456",
          "submitted_at": 1755000000,
          "form_id": "990114256",
          "qrcode_id": "99001",
          "project_id": "1104",
          "member_id": "8899",
          "record_number": "00123",
          "process_status": 2,
          "process_status_text": "已完成",
          "result_value": "合格",
          "fields": [
            { "field_id": "86293827551234", "field_name": "检查结果", "value": "异常" },
            { "field_id": "86293827551235", "field_name": "运行温度(℃)", "value": "95" }
          ]
        }
      ],
      "total": 240,
      "truncated": false,
      "limit": 50
    },
    "notes": ["这里是行摘要，不是完整正文；要看某条记录的全部字段与审核链，用 record/getRecord。"]
  }
}

响应结构 ​

路径类型说明
rows[].record_idstring记录 ID，可用于 获取单条记录
rows[].submitted_atinteger|null提交时间（epoch 秒）
rows[].form_id / qrcode_id / project_id / member_idstring|null记录归属：表单 / 活码 / 分区 / 提交人
rows[].record_numberstring|null记录编号（文本，可能带前导零）
rows[].process_status_textstring|null处理进度文本
rows[].result_valuestring|null结果值文本
rows[].fields[]array表单字段摘要：field_id、field_name（用户起的字段名；表单结构取不到时为 null）、value
totalinteger|null满足同一条件的总条数；统计失败时为 null，行结果不受影响
truncatedboolean是否被 limit 截断。为 true 时收窄条件，而不是尝试翻页

接入建议 ​

  • 与 metrics/query 搭配：分组结果里每组的 drill_down.filters 与 drill_down.time 原样传入本接口，total 会与该组数值一致
  • 行摘要不含记录完整内容（附件、审核链等），需要时拿 record_id 调 获取单条记录
  • 读懂 fields 里的值，可配合 获取表单结构 查看字段与选项定义

错误响应 ​

json
{
  "code": 400,
  "message": "invalid_argument: ……",
  "data": {}
}

常见错误：invalid_argument（filters 含不认识的键）、query_timeout（收窄条件后再试）、upstream_unavailable（稍后再试）。其余见 错误码说明。