用 API 做批量操作

批量操作真正的难点是分页、限流和幂等,而不是发请求。

自动化现场与效率2026-10-24约 2 分钟382 字

把手工点击换成 API 调用,第一版通常很顺,第二版开始遇到分页漏数据、限流被封、重复执行三类问题。

认证信息不要写进代码

令牌放环境变量或权限 600 的配置文件:

bash
export API_TOKEN="$(cat /root/.config/api-token)"
curl -sS -H "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/v1/items?page=1"

脚本进版本库时,先确认没有把令牌带进去。

分页

三种常见分页:页码、游标、偏移。页码最容易漏数据——翻页过程中数据变动会导致跳过或重复。

bash
page=1
while :; do
  resp=$(curl -sS -H "Authorization: Bearer $API_TOKEN" \
    "https://api.example.com/v1/items?page=$page&limit=100")
  n=$(printf '%s' "$resp" | jq '.items | length')
  [ "$n" -eq 0 ] && break
  printf '%s' "$resp" | jq -r '.items[] | [.id,.name] | @tsv'
  page=$((page+1))
  [ "$page" -gt 200 ] && break   # 防御性上限
done

游标分页更稳:把上一次返回的 next_cursor 原样传回,直到为空。

限流

429 不是错误,是“稍后再来”。看响应头里的 Retry-After,做指数退避:

bash
sleep_for=$(( attempt * attempt ))
[ "$attempt" -gt 5 ] && exit 1
sleep "$sleep_for"

并发数控制在 2–4,比一次开 50 个请求更容易跑完。

幂等

批量写入前先查是否已存在,或用业务唯一键做去重:

  • 创建前按唯一 ID 查询;
  • 更新用 PUT 而不是重复 POST;
  • 记录已处理的 ID,断点续跑。
时间字段最容易错

接口常用 UTC,报表按本地时间统计时会差 8 小时。请求与解析都显式指定时区,别依赖运行环境的默认值。

验证

跑完之后核对总数:接口返回的总条数、实际写入条数、跳过条数三者要对得上。对不上就先查分页,不要急着改业务逻辑。

小结

认证、分页、限流、幂等、时区,五处检查完,批量脚本才算可用。

说明:文中的地址、域名、主机名与账号均为脱敏示例;配置片段来自实际环境,但版本与网络条件不同,照搬前请先在测试环境验证。最后校对:2026-10-24。