草料开放平台文档

简体中文

English

简体中文

English

主题

指标目录 ​

数据分析类调用的入口接口。一次返回两样东西：

  • 业务对象目录：这个组织有哪些表单、分区、活码、周期计划——全部带用户自己起的名字
  • 指标清单：当前组织可以计算哪些指标（已按组织实际情况裁剪，例如没有配周期计划的组织不会列出计划类指标）

拿到目录和指标清单后，用 按指标出数 计算具体数字。

注：指标与分析类接口（metrics/*、record/searchRecords）的 data 结构为 {result, notes, next_actions}：result 是业务数据；notes 是口径提示（统计范围、降级情况等），建议逐条阅读；next_actions 是接下来通常该调用什么的建议。

请求示例 ​

python
import requests

url = "https://open.cli.im/api/v2/rpc/metrics/list"
data = {"limit": 30}
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/list' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"limit": 30}'

请求参数 ​

参数类型必填说明
limitinteger否每类对象最多返回多少条，默认 30，上限 100

完整返回示例 ​

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "result": {
      "catalog": {
        "forms": [
          {
            "form_id": "990114256",
            "name": "设备日常巡检表",
            "type": 0,
            "project_id": "1104",
            "last_active_at": 1754898000,
            "has_cycle_plan": true
          }
        ],
        "plans": [
          {
            "plan_id": "548",
            "target_form_id": "990114256",
            "target_form_name": "设备日常巡检表",
            "cycle_type": "day",
            "execute_status": "running"
          }
        ],
        "qrcodes": [
          {
            "qrcode_id": "99001",
            "name": "巡逻点-1",
            "coding": "qk3mJHJ",
            "form_id": "990114256",
            "project_id": "1104",
            "disabled": false
          }
        ],
        "projects": [
          { "project_id": "1104", "name": "消防管理", "parent_id": null }
        ],
        "degraded": []
      },
      "metrics": [
        {
          "name": "record_submission_count",
          "title": "记录提交量",
          "description": "时间窗内提交的记录条数。最基础的活动量，几乎对所有组织都适用。",
          "format": "integer",
          "layer": "L0.5",
          "applicability": "has_records",
          "dimensions": ["form", "qrcode", "project", "process_status_text", "result_value_text", "day", "month"],
          "limitations": ["按记录提交时间（record_add_time）落在时间窗内筛选。", "已删除的记录不计入。"]
        }
      ],
      "saved_definitions": [],
      "distribution_dimensions": ["process_status_text", "result_value_text"]
    },
    "notes": ["……口径提示……"]
  }
}

响应结构 ​

路径类型说明
data.result.catalog.forms[]array表单目录：form_id、name（用户起的表单名）、project_id（所属分区）、last_active_at（最近有记录的时间）、has_cycle_plan（是否配了周期计划）
data.result.catalog.plans[]array周期计划目录：plan_id、target_form_id/name（计划针对的表单）、cycle_type（day/week/month 等）
data.result.catalog.qrcodes[]array活码目录：qrcode_id、name、coding、form_id、project_id、disabled
data.result.catalog.projects[]array分区目录：project_id、name、parent_id（父分区，无则为 null）
data.result.catalog.degraded[]array哪几块目录本次查询失败（值为 forms/plans/qrcodes/projects）。出现在这里表示对应目录是「没查到」而不是「组织里没有」，基于它的结论请先别下
data.result.metrics[]array可计算的指标：name（调用 metrics/query 时的指标名）、title、description、format（integer 计数 / ratio 比例）、dimensions（可用的分组维度）、limitations（口径与注意事项）
data.result.distribution_dimensions[]array适合做「分布」的维度提示
data.notes[]array本次结果的口径提示

注：目录返回的是「最近活跃优先」的前 N 条，用于了解组织概况；要完整名单用对应的列表接口——活码列表、分区列表、批量模板列表。

接入建议 ​

  • 拿到指标 name 后，先看 指标定义 了解口径，再用 按指标出数 计算
  • 目录里的 form_id、project_id、qrcode_id 都可以作为出数时 scope 的过滤值

错误响应 ​

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

message 以错误码 slug 开头（如 invalid_argument、upstream_unavailable），后接具体说明；按说明调整参数或稍后重试即可。其余错误码定义见：错误码说明。