列举记录
API 说明
端到端写入校验可配合 场景:写入约 10 行 使用。
列举指定多维表数据表中的记录,支持按视图、字段、筛选条件与分页参数控制返回结果。可先浏览多维表格快速开始。
注意事项:
- 需要文件读权限。
sheet_id通过路径传递。prefer_id为 true 时,请求与响应中的字段标识按字段 ID 解析/返回。records[].fields为 JSON 字符串,内容为字段名(或字段 ID)到单元格值的映射;各字段值格式详见 字段和参数说明。filter写法见 筛选规则说明。- 使用
page_size与page_token进行游标分页;响应中的page_token表示还有后续数据时可继续请求。 fields、filter、view_id等查询参数均可省略。filter.criteria[].values随operator变化:Empty/NotEmpty不要传values。
使用限制:
- 需要多维表相关权限(
kso.dbsheet.read或kso.dbsheet.readwrite)才能调用该接口。 - 支持应用授权与用户授权。
请求说明
| 字段 | 值 |
|---|---|
| 请求地址 | 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-Type | string | 是 | application/json | 固定为 application/json | application/json | 请求内容类型 |
| X-Kso-Date | string | 是 | - | 必须符合 RFC1123 规范 | Thu, 29 May 2026 03:00:00 GMT | KSO-1 签名所需的 RFC1123 格式日期时间 |
| X-Kso-Authorization | string | 是 | - | - | KSO-1 AK…:… | KSO-1 签名值,详见「签名方法」 |
| Authorization | string | 是 | - | 必须以 Bearer 开头 | Bearer {access_token} | 授权凭证,格式为:Bearer {access_token},获取方式详见「认证授权概述」 |
路径参数(Path)
| 属性名 | 参数类型 | 是否必填 | 可选值 | 限制 | 示例 | 描述 |
|---|---|---|---|---|---|---|
| file_id | string | 是 | - | 字符长度[1,128];需要 url_encoding | "file_example_001" | 文件 ID |
| sheet_id | integer | 是 | - | 正整数 | 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状态码 | 错误码 | 错误描述 | 排查建议 |
|---|---|---|---|
| 400 | 400000002 | 请求参数格式有误 | 检查请求体 JSON、必填路径参数 |
| 400 | 400000003 | 请求参数取值无效 | sheet_id/视图不存在、filter 非法、fields 指定了不存在的字段等 |
| 401 | 401000001 | access_token 无效或已过期 | 检查 Authorization 头中的 token 是否正确,是否已过期,需重新获取 |
| 403 | 403000001 | 权限不足 | 无文件读权限,或高级权限禁止查看记录(E_DBSHEET_AD_RECORD_VISIT) |
| 403 | 403410005 | 文件不存在 | 核对 file_id |
| 429 | 429000001 | 请求频率超限 | 已触发该接口文档中的限频策略(应用 10 次/秒,按 app_id)。请降低请求频率后重试 |
| 500 | 500410002 | 内核指令执行失败 | 查看完整 msg 后重试或联系支持 |
| 500 | 500000004 | 服务内部错误 | 请稍后重试,若持续出现请联系技术支持 |
场景对照表见 错误码业务场景。