把 API 数据自动写入 Google Sheets 的最短路径

大家好,我是负责 3Min API 开发的 yeonghyeon。

这篇文章的起点是运营者们反复提出的一个请求:"订单进来后,直接一行一行地堆到 Google 表格里就行了。"这种请求出现了不止一两次。把额外的自动化工具串起来其实早就有方案,但多接一个工具本身就是负担。所以我们 把 Google Drive 与表格集成直接做进了 3Min API。 谷歌账号连接一次就完成了,之后每次 API 调用都会自动在你自己的表格里新增一行。

这篇文章是写给第一次接触这项功能的朋友的导览。我们会按顺序梳理 为什么需要这项功能、不在中间套自动化工具的方式有什么不同、以及 今天 5 分钟内能做到哪一步。无需任何前置知识。

"就让数据堆进表格里"这个请求背后真正的问题

想把数据汇集到表格里的理由几乎都一样。一眼看清营收、亲手做筛选和排序、原样交给会计或营销同事。表格最贴合这种用途,也没必要再搬到别处。换句话说,表格本身就是终点 — 中间所有步骤都是多余。

但是要把"通过 API 收到的数据"和"我自己的表格"连起来,实际上没那么容易。常见路径是这样的:

1. 先用 3Min API 之类的服务收数据,
2. 再注册 Zapier、Make、n8n 之类的自动化工具,
3. 用 Webhook 把数据流向那个工具,
4. 那个工具再往 Google Sheets 追加一行。

顺利的时候没问题。但从运营角度看会带来三种负担。

• 工具成本 — 每个自动化工具都有月度订阅费,调用量增多还得升级到更贵的套餐。
• 学习成本 — 要连节点、做触发器、再配一次认证。仅仅是"追加一行订单"而已,步骤却多到夸张。
• 丢失风险 — 自动化工具维护中或超过调用上限时,这段时间进来的数据可能会被悄悄丢弃。表格里少了一行,也无从查到丢的是哪一条。

最后这一条尤其关键。在生意里丢数据不是普通的不便,而是 账本上多了一个洞。把生意建立在"自动化工具一直健康"这个假设上是站不住的。

所以我们选了直接的答案 — 把表格集成放进产品里

解决方向很直白:不让别的工具卡在 3Min API 和 Google Drive 之间。谷歌账号连接一次,在同意页授权一个权限即可。之后每次 API 调用都会自动在你自己 Drive 里的表格中新增一行。无需自动化工具,无需额外订阅,无需触发器配置。

外部调用 → 先在 3Min API 中安全保存 → 自动写入 Google Sheets。中间没有自动化工具。

这样做之后会有什么变化:

• 一个工具搞定。 所有设置都在 3Min API 内部完成。
• 数据始终先安全保存。 表格写入新行之前,调用本身就已经记录到 3Min API 的日志和归档。表格写入只是锦上添花,不是命脉。
• 失败也不丢原始数据。 一时超过额度时会自动重试。即便重试到底也没成功,也只是表格少一行,数据本身不会消失。
• 权限尽量收窄。 向谷歌请求的权限只有 drive.file 一项。3Min API 只能访问自己创建的表格,你 Drive 里的其他资料一律碰不到。

一句话总结:如果表格就是终点,通向它的路径越短越好。

连接后 Drive 里会出现什么

实际连接后 Drive 里会形成什么样的结构,直接看一眼最快。Drive 顶层会自动生成一个名为 3Min API 的文件夹,内部按下面的方式整理:

3Min API/
├── user-signup/                              ← 按端点划分的文件夹
│   ├── sandbox_user-signup_2026-04           ← 按月份的表格 (沙盒)
│   ├── sandbox_user-signup_2026-05
│   └── production_user-signup_2026-05        ← 按月份的表格 (生产)
└── order-create/
    └── production_order-create_2026-05

规则很简单:每个端点一个文件夹,文件夹下按环境(沙盒/生产)和月份各一张表格。新月份开始时,首次调用会自动新建表格,所以也不用担心一张表过载。把表格搬到别的文件夹或者改名也安全。3Min API 通过文件 ID 跟踪表格,即便位置和名称变了,也会继续往同一个文件里添加行。

每张表的第一行,也就是表头,由两类列组成:

• 元数据列 — record_id、created_at、config_version、operation、status、collaboration_key。系统自动填充。用来追踪每一行对应的是哪一次调用。
• 负载列 — 你定义的字段(邮箱、金额、地址……)会带着 payload_ 前缀,一字段一列展开。前缀是有意为之,避免业务数据与元数据混在一起。

之后给端点加新字段时,表头会自动向右扩展。旧行里新列的位置保持空白,从下一次调用开始才会被填上值。只要不在表格里直接删表头或调换顺序,映射会一直自然对应。

沙盒和生产相互独立

3Min API 的所有端点都把 沙盒(开发/测试用)和 生产(正式服务用)完全分开。Google Sheets 集成同样遵循这一分离。同一个端点,可以按环境标签分别开关集成,表格文件也按环境分别生成。

因此你会经常遇到一项保护措施。即便沙盒里把表格集成都连好了,把端点部署到生产之后,生产的表格集成不会自动跟上。需要在生产环境标签的 Google Sheets 卡片上再次点击 开始集成,正式记录才会启动。我们故意多问一遍。把测试数据和真实营收数据混在同一张表里,会是相当棘手的事故。

5 分钟体验 — 一直到第一次表格记录

说理论不如直接看一次效果来得快。按下面的顺序走就行。一行代码也不用写,工具也只需要 3Min API 一个。

1. 注册账号并创建第一个端点

注册后,系统会自动引导一个简短的 入门流程,带你创建第一个端点。Free 套餐也能用 Google Sheets 集成。请按你正在运营的业务,先做一个端点试试。什么都行。一开始建议选 订单接收、咨询登记、预约申请 这种"一件事一行"的简单形态。两三个字段就足够。完整步骤整理在 端点创建手册 中。

如果想先把"端点是什么"这件事再放慢一点理解,推荐先读 API 是什么? 写给非开发者的入门指南。只要把握"在固定地址、按固定形态收发消息的窗口"这种感觉,后面的内容自然能跟上。

2. 在 Google Sheets 卡片上开始集成

打开端点详情页,会看到一张 Google Sheets 卡片。点击卡片里的 开始集成 按钮,会跳转到谷歌的同意页。

同意页上 3Min API 请求的权限只有 drive.file 一项。这是只能访问自己创建的表格的窄权限。如果谷歌一并显示了多个权限的勾选框,请 保持全部勾选 后再同意,否则表格记录无法正常工作。

3. 用测试发送做确认

集成完成后,卡片上会显示 已连接 标识和表格文件名。这时点一次 测试发送 按钮。一行示例数据就会写入表格,你可以亲眼看到一次实际调用是怎样落进表格的。无需任何开发工具,这是看到结果最快的方法。

从现在起,这个端点每收到一次 API 调用,表格末尾就会自动追加一行。到这里就全部完成。

需要知道的几件事

Google Sheets 本身有写入额度

表格写入受 谷歌按用户设定的写入额度限制,而不是 3Min API 设定的额度。通常是每分钟约 60 次,同一个谷歌账号下连接的所有端点共用这个额度。整个表格自动记录功能都是在这个额度上运行的。

日常流量下基本不会感知到这个上限。但随着时间推移,如果调用量稳步增长、开始频繁触及上限,这其实是 生意势头不错的好信号。由于谷歌政策很难按用户单独放宽额度,这时建议把表格作为汇总/仪表盘用途,原始数据通过 日志 和 归档 按日或按周下载保存,或者 开始考虑引入自有数据库。即便走到这一步,3Min API 仍可作为入口网关使用,迁移负担很小。

可以通过系统通知掌握状态

为了在表格写入失败或需要重新认证时立刻察觉,可以为每个端点登记 Discord/Slack/Telegram 通知频道。在 端点详情 的系统通知设置里把频道连接好,表格写入失败 与 需要 Google 重新认证 这两类事件就会直接推送到该频道。这是不必每次打开仪表盘也能确认表格是否在正常填充的最轻量方法。

这段时间里 3Min API 自动处理了什么

会触发通知的事件其实并不常发生。这中间的空隙,3Min API 用下面三种方式补上了:

• 自动重试 — 一时的额度超出(429)或临时故障会在大约 5 分钟内自动重试,把多数情况吸收掉。我们也在持续向谷歌申请提高额度,以扩大处理量。
• 原始数据始终安全 — 即使自动重试到最后仍然失败,也只是表格里少一行,原始调用本身仍保存在 日志 与 归档 中。表格写入失败不等于数据丢失。
• 按调用顺序逐行处理 — 表格记录按调用顺序逐行处理,通常 几秒内 就会出现在表格里。在调用集中时段,行可能比平时晚一点反映,排序也可能与调用顺序略有出入。需要严格的顺序时,请按 created_at 列排序查看。

今天能做的一件事

不必一上来就组装宏大的自动化方案。我们建议的,只有这一件事。

创建一个端点 → 打开 Google Sheets 集成 → 测试发送一次。

走到这一步,你的 Drive 里就会出现一条自动堆叠业务数据的小型管线。在它之上,可以再加新字段、把 API key 交给合作方、用营收列画图表。比起一次设计好所有自动化,我们更建议先 用最短的路径,看一次"一行数据落进表格" 这一幕。

更详细的设置和异常处理整理在 Google Sheets 集成手册 里。如果想多了解一下我们为什么做这件事,我们为什么做了 3Min API 写下了背后的故事。