开放能力导航
首页/飞书/调用手册
飞书调用手册

查询并新增多维表格记录

读取已授权数据表的记录，并新增一条文本示例数据，覆盖分页与字段格式。

官方资料核对 2026-10-15示例代码，未进行真实接口实测
← 返回平台功能

接入准备

  • 查询开通 base:record:retrieve，新增开通 base:record:create；也可使用覆盖相应操作的 bitable:app。
  • 在目标表添加文档应用并赋予相应资源权限；高级权限表还需确认当前应用可访问数据表。
  • 示例先在测试表建立多行文本字段 事项，避免类型不匹配。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

FEISHU_ACCESS_TOKEN
先运行应用消息场景的获取凭证操作，将响应 access_token 放入服务端环境变量；不是 App Secret。
FEISHU_BASE_TOKEN
普通 /base/ 地址中的资源 Token；/wiki/ 形式需先解析知识库节点的 obj_token。
FEISHU_TABLE_ID
数据表 ID；可从地址 table 参数取得。
终端
export FEISHU_ACCESS_TOKEN='replace_with_tenant_access_token'
export FEISHU_BASE_TOKEN='replace_with_base_app_token'
export FEISHU_TABLE_ID='tbl_replace_with_table_id'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    按应用消息场景取得令牌；在多维表格 → 更多 → 添加文档应用，添加本应用。

  2. 02

    普通 /base/ 链接路径中的标识为 app_token，URL 的 table 参数为 table_id；不要把应用 App ID 当成 app_token。

  3. 03

    将两个资源标识填入环境变量，先查询，确认 fields 的字段名，再执行新增。

  4. 04

    查询有 has_more=true 时，将返回的 page_token URL 编码后加入下一次请求，直到 false；新增保存 record_id。

调用 01

查询记录

本例只返回事项字段；首次请求省略 page_token。

POSThttps://open.feishu.cn/open-apis/bitable/v1/apps/${FEISHU_BASE_TOKEN}/tables/${FEISHU_TABLE_ID}/records/search?page_size=20

请求头

Authorization
Bearer ${FEISHU_ACCESS_TOKEN}
Content-Type
application/json; charset=utf-8

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置类型 / 必填说明
app_token / table_idPathstring必填多维表格资源 Token 与数据表 ID，均需真实且已授权。
page_sizeQueryinteger可选默认 20，最大 500。
page_tokenQuerystring可选首次不填；从上次 data.page_token 取得，作为查询参数必须 URL 编码。
field_names请求体string[]可选只返回指定列，名称要逐字匹配；本例事项需为已有字段。
filter请求体object可选按条件筛选，例如 conjunction=and，conditions=[{field_name:事项,operator:contains,value:[测试]}]；实际请求需用合法 JSON。
view_id请求体string可选按视图查询；指定 filter 或 sort 时会忽略 view_id，不能据此把视图当访问控制。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cURL
cat > request-body.json <<'JSON'
{
  "field_names": [
    "事项"
  ],
  "automatic_fields": false
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://open.feishu.cn/open-apis/bitable/v1/apps/${FEISHU_BASE_TOKEN}/tables/${FEISHU_TABLE_ID}/records/search?page_size=20" \
  --header "Authorization: Bearer ${FEISHU_ACCESS_TOKEN}" \
  --header "Content-Type: application/json; charset=utf-8" \
  --data-binary @request-body.json
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://open.feishu.cn/open-apis/bitable/v1/apps/${FEISHU_BASE_TOKEN}/tables/${FEISHU_TABLE_ID}/records/search?page_size=20")
headers = {
    "Authorization": expand("Bearer ${FEISHU_ACCESS_TOKEN}"),
    "Content-Type": expand("application/json; charset=utf-8"),
}
body = {
    "field_names": [
        "事项",
    ],
    "automatic_fields": False,
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "code" in result and result["code"] != 0:
    raise SystemExit("平台返回业务错误，请结合下方排错说明检查响应")
Node.js
// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://open.feishu.cn/open-apis/bitable/v1/apps/${FEISHU_BASE_TOKEN}/tables/${FEISHU_TABLE_ID}/records/search?page_size=20");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${FEISHU_ACCESS_TOKEN}",
  "Content-Type": "application/json; charset=utf-8"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "field_names": [
    "事项"
  ],
  "automatic_fields": false
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "code") && result["code"] !== 0) {
  throw new Error('平台返回业务错误，请结合下方排错说明检查响应');
}

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。读取 data.items；has_more=true 时继续携带新的 page_token。 以下为结构示意，非本站实测结果。

JSON
{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "record_id": "rec_example",
        "fields": {
          "事项": [
            {
              "type": "text",
              "text": "接入测试"
            }
          ]
        }
      }
    ],
    "has_more": false,
    "total": 1
  }
}

常见错误与排查

1254003app_token 错误
核对 /base/ 资源标识，知识库链接先解析节点。
1254024字段名不合法
核对事项是否存在，包括空格、换行与字段类型。
1254302缺少高级权限
为调用身份配置表或多维表格的相应管理权限。

调用注意

  • 查询限频 20 次/秒；has_more 与 page_token 才是续页依据，不按 total 自行猜页。
  • 非零 code 即失败，即使 HTTP 为 200。
查询多维表格记录
调用 02

新增单条记录

执行会向测试表新增一行；fields 的键为字段名称，值按字段类型填写。

POSThttps://open.feishu.cn/open-apis/bitable/v1/apps/${FEISHU_BASE_TOKEN}/tables/${FEISHU_TABLE_ID}/records

请求头

Authorization
Bearer ${FEISHU_ACCESS_TOKEN}
Content-Type
application/json; charset=utf-8

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置类型 / 必填说明
fields请求体object必填字段名称到值的映射。本例事项是多行文本，传字符串；人员/附件/日期字段不能照抄该格式。
client_tokenQuerystring可选UUIDv4 幂等标识；同一业务重试复用，新的新增动作换值。
ignore_consistency_checkQueryboolean可选默认 false 保持一致性检查，本手册不建议为了吞吐改为 true。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cURL
cat > request-body.json <<'JSON'
{
  "fields": {
    "事项": "接入测试：待处理事项"
  }
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://open.feishu.cn/open-apis/bitable/v1/apps/${FEISHU_BASE_TOKEN}/tables/${FEISHU_TABLE_ID}/records" \
  --header "Authorization: Bearer ${FEISHU_ACCESS_TOKEN}" \
  --header "Content-Type: application/json; charset=utf-8" \
  --data-binary @request-body.json
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://open.feishu.cn/open-apis/bitable/v1/apps/${FEISHU_BASE_TOKEN}/tables/${FEISHU_TABLE_ID}/records")
headers = {
    "Authorization": expand("Bearer ${FEISHU_ACCESS_TOKEN}"),
    "Content-Type": expand("application/json; charset=utf-8"),
}
body = {
    "fields": {
        "事项": "接入测试：待处理事项",
    },
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "code" in result and result["code"] != 0:
    raise SystemExit("平台返回业务错误，请结合下方排错说明检查响应")
Node.js
// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://open.feishu.cn/open-apis/bitable/v1/apps/${FEISHU_BASE_TOKEN}/tables/${FEISHU_TABLE_ID}/records");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${FEISHU_ACCESS_TOKEN}",
  "Content-Type": "application/json; charset=utf-8"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "fields": {
    "事项": "接入测试：待处理事项"
  }
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "code") && result["code"] !== 0) {
  throw new Error('平台返回业务错误，请结合下方排错说明检查响应');
}

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。新增记录 ID 在 data.record.record_id。 以下为结构示意，非本站实测结果。

JSON
{
  "code": 0,
  "msg": "success",
  "data": {
    "record": {
      "record_id": "rec_new_example",
      "fields": {
        "事项": "接入测试：待处理事项"
      }
    }
  }
}

常见错误与排查

1254045字段名不存在
核对 fields 中键名与表结构。
1254291写入冲突
同表串行处理读写；发生超时先查询业务标识，避免盲目重复新增。

调用注意

  • 接口频率上限 50 次/秒，但同一数据表应串行读写，避免冲突；这是上限，不是建议并发数。
  • 普通文本示例不适用于人员、关联、附件等结构，先按真实列类型转换。
新增多维表格记录

注意事项

  • 套餐和高级权限会影响表容量及可操作范围；此场景不创建表结构、不修改已有行。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
  2. 02
    查询多维表格记录核验日期 2026-10-15
  3. 03
    新增多维表格记录核验日期 2026-10-15

飞书的其他调用手册

向群发送 Webhook 通知获取应用令牌并发送消息创建云文档并追加正文

← 返回飞书的全部功能