Airtable 数据管理

通过 curl 操作 Airtable REST API：记录增删改查、筛选

Airtable — 库、表和记录

通过 curl 和 terminal 工具直接调用 Airtable 的 REST API。无需 MCP 服务器、无需 OAuth 流程、无需 Python SDK——仅需 curl 和个人访问令牌。

前置条件

   AIRTABLE_API_KEY=pat_your_token_here

> 注意：旧版 key... API 密钥已于 2024年2月 废弃。现在仅支持 PAT 和 OAuth 令牌。

API 基础

curl 基础模式：

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

-s 隐藏 curl 的进度条——每次调用都带上它，保持 Hermes 输出干净。通过 python3 -m json.tool（始终可用）或 jq（如果已安装）格式化可读 JSON。

字段类型（请求体格式）

在创建/更新请求体的顶层传入 "typecast": true，让 Airtable 自动转换值（例如，即时创建新的选项、将 "42" 转为 42）。

常用查询

列出令牌可见的库

curl -s "https://api.airtable.com/v0/meta/bases" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

列出库的表和模式

curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

在执行修改前使用此命令——确认确切的字段名称和 ID、显示选择字段的 options.choices、以及主字段名称。

列出记录（前10条）

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

获取单条记录

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

筛选记录（filterByFormula）

Airtable 公式必须进行 URL 编码。使用 Python 标准库处理——不要手动编码：

FORMULA="{Status}='Todo'"
ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA")
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

常用公式模式：

排序 + 选择特定字段

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

查询参数中的方括号必须进行 URL 编码（%5B / %5D）。

使用命名视图

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

视图会在服务端应用其已保存的筛选 + 排序。

常用修改操作

创建一条记录

curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"fields":{"Name":"新任务","Status":"待办","Priority":"高"}}' | python3 -m json.tool

一次创建最多 10 条记录

curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "typecast": true,
    "records": [
      {"fields": {"Name": "任务 A", "Status": "待办"}},
      {"fields": {"Name": "任务 B", "Status": "进行中"}}
    ]
  }' | python3 -m json.tool

批量端点每次最多 10 条记录。对于更大批量的插入，循环以 10 条为批次并短暂休眠，遵守 5次/秒/库 的限制。

更新记录（PATCH — 合并更新，保留未更改的字段）

curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"fields":{"Status":"已完成"}}' | python3 -m json.tool

通过合并字段进行 Upsert（无需 ID）

curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "performUpsert": {"fieldsToMergeOn": ["Email"]},
    "records": [
      {"fields": {"Email": "user@example.com", "Status": "活跃"}}
    ]
  }' | python3 -m json.tool

performUpsert 对合并字段值不存在的记录执行创建，对已存在的记录执行更新。非常适合幂等同步。

删除一条记录

curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

一次删除最多 10 条记录

curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" 
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

分页

列表端点每页最多返回 100 条记录。如果响应中包含 "offset": "..."，在下次请求中传回它。循环直到该字段不存在：

OFFSET=""
while :; do
  URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100"
  [ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET"
  RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY")
  echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]'
  OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))')
  [ -z "$OFFSET" ] && break
done

典型 Hermes 工作流程

常见陷阱

Hermes 重要说明