跳到主要内容

数据查询

先用最小请求读取第一页，再逐步加入条件与排序。本文是 HTTP 请求体；与 MCP 工具的 current/size 参数不同。

分页读取​

POST /open-api/openapi/form/page，请求头使用业务认证与签名。

{
  "table": "YOUR_FORM_ID",
  "navi": {"page": 1, "vol": 10}
}

page 从 1 开始；页面文档说明 vol 最大为 100，正式部署仍应按实际校验和限额控制。读取响应的 data.records 与 data.total，不要用当前页长度推断总数。

接口的通用业务响应通常为 code/msg/data/ok。遇到业务错误时处理实际返回，不能因为 HTTP 为 200 就认定查到了正确结果。

条件和排序​

以下示例按一个真实文本列查询。替换表单与列名；compare=10 用于本例标量等值条件，不可直接套用 JSON 选项字段。

{
  "table": "YOUR_FORM_ID",
  "navi": {"page": 1, "vol": 10},
  "conditions": {
    "join": "AND",
    "items": [
      {
        "join": "AND",
        "var": "YOUR_TEXT_COLUMN",
        "compare": 10,
        "values": ["目标文字"]
      }
    ]
  },
  "orders": [{"column": "YOUR_SORT_COLUMN", "direction": "ASC"}]
}
参数要求
conditionsJSON 对象，不能先 stringify 成字符串
items条件或子组列表，可以递归嵌套
var当前接口要求的真实列标识
compare整数比较码，按字段类型与支持的运算选择
values数组，即使只有一个比较值
orderscolumn 与 ASC/DESC；多规则按约定顺序核对

join 表示当前节点与同层前一项的连接方式。多个子条件需要 OR 时，每个同层子项都应对应 OR，不能只写父组 join=OR 而保留子项 AND。

单选、多选、开关等字段使用真实存储值，且需要适用 JSON/选项的比较方式；先确认协议，不能因为页面显示“待处理”就直接按文本查它。

读取详情​

POST /open-api/openapi/form/detail。从前一次列表取得真实记录 ID，按 ID 列构造条件：

{
  "table": "YOUR_FORM_ID",
  "conditions": {
    "join": "AND",
    "items": [
      {"join": "AND", "var": "id", "compare": 10, "values": ["YOUR_RECORD_ID"]}
    ]
  }
}

读取 data 中的目标详情，核对记录、字段与应用归属。该 HTTP 条件格式不能替代 MCP form_detail 的工具参数，也不能与匿名分享的 URL 记录 ID 混用。

选择字段与高级查询​

页面还提供 columns、joins、groups 等参数：

参数用途
columns.metadata选择输出列，使用接口要求的实际字段标识
columns.excludeMetadata排除不需要的列
joins关联表和连接条件，核对源表、目标表及字段
groups分组字段及对应查询口径

先验证单表查询，再联调关联与分组。请求指定列不等于获得额外字段权限，不能用关联查询扩大授权范围。

最后分别核对：命中、不命中、空值、第一页与下一页、排序和权限差异。查询成功后才开始写入。

按接口继续​

完整请求及返回形态分别见V1 分页查询、V1 列表及V1 详情。同一读取链会按 navi 的有无决定数组或分页等结果形态，不只按 URL 名称判断。