列举记录

API 说明

端到端写入校验可配合 场景:写入约 10 行 使用。

列举指定多维表数据表中的记录,支持按视图、字段、筛选条件与分页参数控制返回结果。可先浏览多维表格快速开始。

注意事项:

使用限制:

请求说明

字段值
请求地址https://openapi.wps.cn/v7/coop/dbsheet/{file_id}/sheets/{sheet_id}/records
HTTP 方法POST
签名方式KSO-1
限频策略应用 10 次/秒(按 app_id);超限返回 429000001
权限要求查询多维表(应用授权) kso.dbsheet.read
查询多维表(用户授权) kso.dbsheet.read
查询和管理多维表(应用授权) kso.dbsheet.readwrite
查询和管理多维表(用户授权) kso.dbsheet.readwrite

请求头(Headers)

Header 名称参数类型是否必填可选值限制示例描述
Content-Typestring是application/json固定为 application/jsonapplication/json请求内容类型
X-Kso-Datestring是-必须符合 RFC1123 规范Thu, 29 May 2026 03:00:00 GMTKSO-1 签名所需的 RFC1123 格式日期时间
X-Kso-Authorizationstring是--KSO-1 AK…:…KSO-1 签名值,详见「签名方法」
Authorizationstring是-必须以 Bearer 开头Bearer {access_token}授权凭证,格式为:Bearer {access_token},获取方式详见「认证授权概述」

路径参数(Path)

属性名参数类型是否必填可选值限制示例描述
file_idstring是-字符长度[1,128];需要 url_encoding"file_example_001"文件 ID
sheet_idinteger是-正整数3数据表 ID(sheet_id),不是文件 ID

请求体(Body)

请求体格式: application/json

请求示例

请求须携带 Authorization 与 KSO-1 签名头 X-Kso-Date、X-Kso-Authorization,算法见 KSO-1 签名方法。

cURL

bash
curl -X POST "https://openapi.wps.cn/v7/coop/dbsheet/file_example_001/sheets/3/records" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "X-Kso-Date: Thu, 29 May 2026 03:00:00 GMT" \
  -H "X-Kso-Authorization: {kso1_signature}" \
  -d '{
    "prefer_id": false,
    "text_value": "original",
    "page_size": 100,
    "fields": [],
    "filter": {
      "mode": "AND",
      "criteria": [
        {
          "field": "状态",
          "operator": "Equals",
          "values": ["进行中"]
        }
      ]
    },
    "show_record_extra_info": true,
    "show_fields_info": true
  }'

fields 传 [] 或省略该字段均表示返回全部字段。若只要部分列,改为例如 "fields": ["名称", "数量", "状态"]。

精简请求示例(仅必填头与最小 Body):

bash
curl -X POST "https://openapi.wps.cn/v7/coop/dbsheet/file_example_001/sheets/3/records" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Kso-Date: Thu, 29 May 2026 03:00:00 GMT" \
  -H "X-Kso-Authorization: {kso1_signature}" \
  -H "Content-Type: application/json" \
  -d '{
    "page_size": 100,
    "fields": []
  }'

响应体(Response)

HTTP状态码: 200
响应体格式: application/json

响应示例

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "fields_schema": [
      {
        "id": "B",
        "name": "名称",
        "type": "MultiLineText",
        "data": {
          "unique_value": false
        }
      },
      {
        "id": "C",
        "name": "数量",
        "type": "Number",
        "data": {
          "number_format": "0_ "
        }
      },
      {
        "id": "D",
        "name": "状态",
        "type": "SingleSelect",
        "data": {
          "allow_add_item_while_inputting": false,
          "items": [
            {
              "id": "opt1",
              "value": "未开始"
            },
            {
              "id": "opt2",
              "value": "进行中"
            }
          ]
        }
      }
    ],
    "records": [
      {
        "id": "rec001",
        "fields": "{\"名称\":\"示例记录\",\"数量\":12,\"状态\":\"进行中\"}",
        "created_time": "2026-05-29T03:00:00Z",
        "creator": "123456",
        "last_modified_by": "123456",
        "last_modified_time": "2026-05-29T04:00:00Z"
      }
    ],
    "page_token": ""
  }
}

错误码

HTTP状态码错误码错误描述排查建议
400400000002请求参数格式有误检查请求体 JSON、必填路径参数
400400000003请求参数取值无效sheet_id/视图不存在、filter 非法、fields 指定了不存在的字段等
401401000001access_token 无效或已过期检查 Authorization 头中的 token 是否正确,是否已过期,需重新获取
403403000001权限不足无文件读权限,或高级权限禁止查看记录(E_DBSHEET_AD_RECORD_VISIT)
403403410005文件不存在核对 file_id
429429000001请求频率超限已触发该接口文档中的限频策略(应用 10 次/秒,按 app_id)。请降低请求频率后重试
500500410002内核指令执行失败查看完整 msg 后重试或联系支持
500500000004服务内部错误请稍后重试,若持续出现请联系技术支持

场景对照表见 错误码业务场景。