如何将 Google 表格连接到你的应用
要把 Google 表格连接到你的应用，需要在 Google Cloud 项目中启用 Google Sheets API，创建一个服务账号，把表格共享给该服务账号的邮箱地址，并把它的密钥保存为服务器端机密。之后，你的服务器就可以用 spreadsheets.values.get 读取行，用 spreadsheets.values.append 添加行。如果用户需要连接他们自己的表格，则改用 OAuth；如果表格完全公开，只读取的话，一个简单的 API 密钥就够了。
本指南涵盖如何选择合适的方式、需要用到的调用、配额和注意事项，以及给 AI 应用搭建工具的提示词。Google 的相关细节均来自截至 2026 年 9 月的 Google 开发者文档。
为什么要连接表格
常见原因包括：
- **保留团队的工作流程。**员工继续在 Sheets 中编辑价目表或排班表，应用负责展示。
- **在人们已经查看的地方收集数据。**新注册用户、订单或表单回复以行的形式出现。
- **报表。**把应用数据导出到表格，供习惯使用表格的人查看。
- **过渡方案。**从表格起步，之后再迁移到正式数据库。参阅如何把电子表格变成应用。
选择应用如何向 Google 进行身份验证
Google 的凭据指南描述了三种类型：
| 凭据 | 可以访问的内容 | 最适合 |
|---|---|---|
| API 密钥 | 仅限公开可用的数据，例如设为“知道链接的任何人可查看”的文件 | 读取公开表格 |
| 服务账号 | 归你的应用所有的数据，或明确共享给该服务账号邮箱的特定文件 | 你的应用读写你自己的表格 |
| OAuth 客户端 ID | 用户在同意后，可以访问其本人的文件 | 让每位用户连接他们自己的表格 |
对大多数应用来说，服务账号是正确的选择：只需一套由你掌控的凭据，并且只能访问你明确共享给它的表格。
使用服务账号的分步操作
- 创建或选择一个 Google Cloud 项目，并启用 Google Sheets API。
- 创建服务账号，并为其创建密钥。密钥是一个 JSON 文件，请像对待密码一样保管它。
- 把表格共享给服务账号的邮箱地址：只读则选查看者，需要写入则选编辑者。Google 的指南说明，这要通过普通的共享界面完成。
- 在服务器上把密钥保存为机密，例如
GOOGLE_SERVICE_ACCOUNT_JSON，并把表格 ID（表格 URL 中的那串长字符）保存为SHEET_ID。 - 在服务器上调用 API，使用 Google 为你所用语言提供的客户端库。
- 缓存读取结果：如果许多访客看到的是同一份数据，就不要每次都请求，以免触及配额。
你会用到的调用
以下来自 Google 关于读写数值的指南：
| 方法 | 作用 |
|---|---|
spreadsheets.values.get | 读取一个范围，例如 Leads!A1:E |
spreadsheets.values.batchGet | 一次请求读取多个范围 |
spreadsheets.values.update | 写入指定范围 |
spreadsheets.values.append | 在表格已有数据之后追加行 |
范围使用 A1 表示法。Google 指出，不带工作表名称的范围（如 A1:B2）会应用于第一个工作表，因此请明确写出标签页名称，以免有人调整标签页顺序时出现意外。
RAW 与 USER_ENTERED
写入时需要指定 valueInputOption：
- RAW 会原样存储你发送的内容，作为文本保存。
=1+2会被存为文本=1+2。 - USER_ENTERED 会把输入当作在 Sheets 中手动键入一样处理：日期会变成日期，
=1+2会变成公式。
如果你写入的是用户在应用中输入的文本，请使用 RAW。使用 USER_ENTERED 的话，有人提交的公式可能会在同事打开表格时运行。
配额与错误
截至 2026 年 9 月，Google 的 Sheets API 限额页面列出了以下限制：
| 限制 | 读取请求 | 写入请求 |
|---|---|---|
| 每个项目每分钟 | 300 | 300 |
| 每个用户每个项目每分钟 | 60 | 60 |
只要在每分钟的配额内，就没有每日上限。超出后会返回 429: Too many requests，Google 建议使用截断指数退避：每次失败后等待更长时间，并加入随机延迟，直到达到上限。单个请求如果耗时超过 180 秒，会超时。
实际操作中：不要在每次页面访问时都调用 API。把表格数据缓存一分钟或更久，用 batchGet 合并读取，并在可能的情况下合并写入。
方案与取舍
| 方案 | 优点 | 缺点 |
|---|---|---|
| 表格作为实时数据源 | 员工使用熟悉的工具编辑；无需构建管理界面 | 受配额限制，没有逐行权限，重命名一列就可能导致应用出错 |
| 把表格同步到数据库 | 读取快且可靠；Sheets 故障时应用仍能运行 | 需要同步任务，并约定以哪一方为准 |
| 先用数据库，再导出到表格 | 应用掌控数据；表格只作为报表 | 在表格中的编辑不会回流到应用 |
| 中间加一层自动化工具 | 简单流程无需写代码 | 又多一项订阅；更难调试 |
对于用户众多或数据敏感的场景，数据库是更好的权威数据源。参阅什么是数据库。
给 AI 搭建工具的提示词
读取表格：
在菜单页面上展示我们 Google 表格中“Menu”标签页的内容。在服务器端使用 Google Sheets API，服务账号的 JSON 密钥保存在机密 GOOGLE_SERVICE_ACCOUNT_JSON 中，表格 ID 保存在 SHEET_ID 中。读取范围 Menu!A2:D（名称、描述、价格、分类）。将结果缓存 5 分钟。如果 API 调用失败，则显示最后一次缓存的版本。切勿把密钥发送到浏览器。
写入行：
当有人提交联系表单时，把它保存到我们的数据库中，同时使用 spreadsheets.values.append 并以 valueInputOption RAW 向“Leads”标签页追加一行（日期、姓名、邮箱、留言）。如果 Google 返回 429，则使用指数退避重试；如果仍然失败，就把线索保留在数据库中，稍后再重试。
常见错误
- 忘记把表格共享给服务账号的邮箱。这样即使密钥没问题，API 也会返回权限错误。
- **把密钥放在前端或代码仓库中。**JSON 密钥可以访问所有共享给它的表格。参阅如何妥善保管 API 密钥。
- 对用户输入使用 USER_ENTERED，这会允许公式注入。
- 每次请求都调用 API，结果在第一次流量高峰时就触及每分钟配额。
- **依赖列的位置。**有人插入一列后，应用就读错了数据。应该读取表头行并按名称映射，或锁定表头。
- 把表格共享得比需要的范围更广。“知道链接的任何人”会使其变成公开的。
- **把表格当作多用户数据库使用。**并发写入和权限缺失会导致数据丢失或泄露。
检查清单
- 已启用 Sheets API，并已创建服务账号
- 表格已共享给服务账号邮箱，且权限设为所需的最低级别
- 密钥和表格 ID 已保存为服务器端机密
- 所有调用都在服务器端进行
- 范围中使用了标签页名称
- 用户提供的文本使用 RAW
- 读取结果已缓存；429 已通过退避处理
- Sheets 不可用时，应用能够优雅降级
- 已确定由哪一方作为权威数据源
Mythex 中的 Google 表格
Mythex 有两种与表格协作的方式。连接器会把你的 Google 账户连接到 Mythex，使智能体在你构建时可以使用它，例如读取表格来搭建仪表盘。文档说明，该凭据由 Mythex 的连接服务保管，绝不会进入你的代码（参阅连接器，并批准 Google 要求的每一项权限）。如果要让已发布的应用自行读写表格，最可靠的方式就是本指南中的做法：把服务账号密钥保存为项目机密，并在服务器上调用 Sheets API，具体参阅集成任何 API。如果你的数据已经超出了表格的承载能力，可以让智能体把数据迁移到项目数据库，并在其上构建仪表盘。
常见问题
我的应用如何读取私有的 Google 表格？
常用方法是使用 Google Cloud 服务账号：启用 Sheets API，创建服务账号及其密钥，然后把表格共享给该服务账号的邮箱地址，权限设为查看者或编辑者。你的服务器使用以密钥形式保存的机密信息调用 Sheets API。
我能用 Google API 密钥访问表格吗？
只能用于公开数据。Google 的凭据指南说明，API 密钥仅用于匿名访问公开可用的数据，例如对任何拥有链接的人共享的文件。私有表格需要服务账号或 OAuth。
Google Sheets API 有哪些限制？
截至 2026 年 9 月，Google 列出的限制为：每个项目每分钟 300 次读取和 300 次写入请求，每个用户每个项目每分钟各 60 次，没有每日上限。超出限制会返回 429 错误；Google 建议使用截断指数退避重试。
我应该把 Google 表格用作应用的数据库吗？
适合小型、低流量、并且人们也会直接在表格里编辑数据的应用。如果用户很多、写入频繁、记录之间存在关联，或需要按用户设置权限，那么真正的数据库更可靠，你仍然可以把数据导出到表格。