3Min API
菜单路径: 仪表盘 > APIs > 端点详情 > Google Sheets

Google Sheets

概览

Google Sheets 集成会在每次 API 调用时自动向您 Google Drive 的电子表格追加一行。每月自动创建新的表格文件，新增字段时表头也会自动扩展。

无需编写代码，就能把销售、订单、咨询等数据集中到一个表格中查看,这是最便捷的方式。表格保存在您自己的 Drive 中,可以照常使用 Google Sheets 的共享、筛选、图表和数据透视表功能。

仅限所有者使用。协作者看不到 Google Sheets 卡片。

进入路径

  1. 顶部菜单 APIs → 点击目标端点名称进入端点详情
  2. 在页面中的 Google Sheets 卡片开始

Free 套餐也可使用,放心试用。

Drive 中会创建什么

启用集成后,系统会在您 Google 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
  • 文件夹名: 端点名称(特殊字符会自动整理)
  • 文件名: {环境}_{端点}_{YYYY-MM} (按 UTC 月份)
  • 新月份开始时,下一次调用时会自动创建新文件

权限范围

3Min API 仅向 Google 申请 drive.file 一个权限。该权限只能访问 3Min API 自己创建的文件,范围非常有限。您 Drive 中的其他资料(其他表格、文档、共享文件夹)都无法访问,请放心。

表格列结构

每张表格的第一行(表头)由两类列组成。

元数据列(关于请求的系统信息)

列 含义
record_id 标识单次调用的唯一 ID(与 3Min API 日志、归档关联)
created_at 调用到达的时间(UTC)
config_version 调用时使用的端点架构版本
operation create / read / update / delete
status 处理结果
collaboration_key 使用了哪个协作密钥

载荷列(请求中携带的业务数据)

载荷中的每个字段都会以 payload_ 前缀添加为单独的列。例如: payload_email、payload_amount、payload_address_city。前缀让载荷数据与元数据列清晰分离。

新字段到达时,表格右侧会自动添加新列。已有行的新列保持空白。

集成方法

步骤 1 — 从 Google Sheets 卡片开始集成

集成前的 Google Sheets 卡片

在端点详情页的 Google Sheets 卡片中点击 `开始集成` 按钮。

步骤 2 — Google 同意页面

Google 同意页面示例

进入 Google 页面后,确认 3Min API 申请的权限只有 drive.file 一个,然后点击同意。视账户而定,可能会出现按权限分别勾选的复选框,这种情况下需要 保持所有复选框都勾选 再同意,否则表格记录无法正常运行。

步骤 3 — 集成完成,确认首行记录

集成后的 Google Sheets 卡片

集成完成后,卡片会显示 已连接 徽章和电子表格文件名。

  • `打开表格` — 在新标签中打开 Drive 中的表格文件
  • `发送测试行` — 向表格记录一行示例,确认是否正常工作。无需开发工具或代码即可立即查看结果,是最快的验证方式
  • `断开连接` — 停止该端点的自动记录(Drive 中的现有文件保留)

之后每次该端点收到 API 调用,都会自动追加到表格的最后一行。

值得了解的事项

处理速度

  • 表格记录会 按顺序处理。API 调用本身会立即响应,但行通常在 几秒内 出现在表格中。
  • 调用突然集中时会进入队列依次处理,可能会比平时晚一些反映到表格中。
  • 出现暂时性限额超出(429)或临时故障时,3Min API 会 自动重试约 5 分钟。重试期间表格中的行顺序可能与调用顺序略有差异;若需要严格的顺序,请按 created_at 列排序查看。

失败时数据依然安全

自动重试后表格记录最终仍然失败时, 只有表格里的这一行缺失,原始数据会完整保留在日志和归档中。表格记录失败会通过您在系统通知中注册的 Discord / Slack / Telegram 渠道发送通知(不会发送邮件)。

需要重新授权的情况

以下情况下表格记录会停止,并发送 重新授权通知(google_reauth_required)。

  • 您在 Google 账户设置中解除了 3Min API 应用的连接
  • Google 让 token 过期(例如长期未使用)
  • 权限勾选被取消,导致 drive.file 缺失

收到通知后,请在 外部集成 设置中重新连接。重新连接后会继续使用现有的表格文件。

不同环境独立运行

沙盒环境和生产环境的 Google Sheets 集成 完全独立。同一个端点也可以按环境标签分别启用或解除集成,表格文件也按环境分别创建。

部署到生产环境后,沙盒的 Google Sheets 集成不会自动跟随。 请在生产环境标签的 Google Sheets 卡片中再次点击 `开始集成`。

断开集成

有两种方式。

单端点断开

在端点详情的 Google Sheets 卡片中点击 `断开连接`。仅停止该端点的表格自动记录,其他端点的 Google Sheets 集成不受影响。

全部断开(直接断开 Google 账户连接)

设置页面中的 Google 集成界面

顶部菜单 设置 → 外部集成 → Google Drive & Sheets → 页面底部 危险操作 中的 `断开所有连接`。所有端点的 Google Sheets 集成会一次性停止,3Min API 的 OAuth 认证也会被撤销。再次使用需要从头开始连接。

断开后的数据

两种方式都会 保留 Drive 中已有的表格文件。如不需要,请直接在 Drive 中删除。下次重新集成时会自动创建新文件,旧文件不会自动删除。

常见疑问

  • 部署到生产环境后表格里没有记录

    沙盒的 Google Sheets 集成不会自动迁移到生产环境。请在端点详情中切换到 生产环境标签,然后在 Google Sheets 卡片中单独点击 `开始集成`。系统会在已有的沙盒表格之外另外创建 production_* 文件。

  • 集成后却找不到表格文件

    请先查看 Drive 最上层的 3Min API 文件夹。当月的表格文件要等第一次调用到达后才会创建。可通过 `发送测试行` 立即创建。如果仍然看不到,请在外部集成设置中确认是否显示权限不足的提示(黄色徽章)。

  • 表头突然多出新列

    端点新增字段时,表格表头会自动扩展(已有行的新列保持空白),这是预期行为。请不要手动删除或重排表头,否则下一行写入时列映射可能错位。

  • 可以移动或重命名表格文件吗?

    可以,很安全。3Min API 通过文件 ID 进行追踪,即使把文件移到其他文件夹或重命名,也会继续向同一个文件追加行。但如果移到回收站或永久删除,下一次调用时会自动创建新文件,被删除的文件无法恢复。

  • 整个 3Min API 文件夹都被删了

    下一次调用到达时,会自动创建新文件夹和新表格。但已删除的旧表格无法恢复,因此建议提前从归档下载需要保留的数据。

  • 表格记录失败的通知太频繁

    表格记录失败通知是在 端点详情 > 通知 中注册 Discord/Slack/Telegram 频道后收到的消息。如果该通知比平时更频繁,请确认以下情况。

    3Min API 会一直自动重试,必要时也会向 Google 申请提高额度来扩大处理量。如果通知仍然频繁,意味着调用量超过了 Google 设定的表格写入上限(通常约为每用户每分钟 60 次)。该上限由 Google 政策决定,而非 3Min API,因此无法按个别用户进一步放宽。

    其实这是 业务发展势头良好的好信号。Google Sheets 适合轻量记录和快速可视化,但本身并不是为每分钟数十次以上持续流量而设计的。是时候考虑下一步了。

    • 把表格作为 概览/仪表盘 使用,原始数据通过日志和归档按日或按周下载保存
    • 评估是否到了引入自有数据库或后端的时机 — 即使到那一步,3Min API 仍可作为入口网关使用(通过 Webhook 同步转发到自有系统)
上一篇
端点详情
下一篇
协作密钥