# 第一天就读写客户的 Google Sheets，不必等 IT

> 把表格共享给服务账号的邮箱，一个 Node.js 脚本就能读订单、写报表、处理配额错误并上传到 Drive。

原文: https://fdetimes.net/zh/guides/google-sheets-drive-nodejs-service-account/

到新客户那里的第一周，你需要的数据很少放在整洁的数据库里。更常见的情况是，它躺在一个名叫“订单 – 最终版 – v3”之类的 Google Sheet 里，由运营团队每天早上手动更新。

如果第一天就能用代码读写这张表，别人还在等数据仓库权限时，你手里已经有一条能跑的数据管道了。

下面将一步步搭建一个 Node.js 脚本，使用官方 googleapis 库和服务账号。脚本能读取区域、覆盖单元格、追加行、处理配额错误，并为上传到 Drive 选对方式。每一步结束都有一项检查，通过后再进入下一步。

## 需要准备什么？

你需要 Node.js、一个可以创建服务账号的 Google Cloud 项目，以及一张测试用的 Google Sheet。用一张只有几行的模拟表即可，例如一个 `Orders` 工作表，包含订单号、数量、单价和日期几列。不要拿客户的真实数据练手。

下面的代码为便于阅读做了精简。代码使用 `import` 和顶层 `await`，因此文件必须以 ES 模块方式运行。运行前，请对照 googleapis 的 README 核对客户端的初始化方式。

## 第 1 步：创建服务账号，妥善保管密钥

服务账号是一种“机器人账号”，用于应用级的服务器到服务器认证，正适合定时运行的脚本。在项目里创建一个服务账号，下载 JSON 凭据文件。从此以后，这个文件就是打开所有共享给这个机器人的文档的钥匙。

Google 的 IAM 文档说得很直白：服务账号密钥如果管理不当，就是安全风险。持有密钥的人要对私钥负责，能用替代方案时应优先选择替代方案。googleapis 的 README 也提醒，要把凭据文件存放在安全的地方，绝不能放进源代码管理。

最稳妥的做法是把密钥完全放在仓库目录之外，这样任何 `git add` 都碰不到它：

```bash
mkdir -p ~/.secrets
mv ~/Downloads/key.json ~/.secrets/sa-demo.json
export SA_KEY_PATH=~/.secrets/sa-demo.json
# 运行前，把下面两个值替换为真实的 scope 字符串
export GOOGLE_SCOPES="<scope-sheets> <scope-drive>"
```

`` 和 `` 是占位符：不替换，脚本就无法运行。运行前，到 Sheets API 和 Drive API 文档里查 OAuth scope 列表，复制所需 scope 的准确字符串，用空格隔开。选能完成任务的最小 scope：只读脚本不需要写权限的 scope。

**检查：**运行 `echo $GOOGLE_SCOPES`，确认没有残留的 `<`；然后在仓库里运行 `git status`，确认列表中没有包含密钥的 JSON 文件。

## 第 2 步：把文件共享给机器人，不需要管理员

每个服务账号都有唯一的邮箱地址。在文档的共享设置里，可以把这个地址当作普通用户对待。打开 Google Sheet，点击“共享”，粘贴服务账号的邮箱，只读选“查看者”，需要写入则选“编辑者”。

在客户现场，这是整个方法里最有价值的一点。你不需要 IT 团队开通全域访问权限。表格的所有者把表格共享给机器人即可，并且随时可以收回权限。

**检查：**从 URL 中复制表格 ID（`/d/` 和 `/edit` 之间的部分），保存到环境变量 `SHEET_ID` 中。

## 第 3 步：读取区域

从 npm 安装官方库：

```bash
npm install googleapis
```

读取只需要两样东西：表格 ID 和用 A1 表示法写的区域。调用的是 `spreadsheets.values.get`。

```js
import { google } from 'googleapis';

const SCOPES = process.env.GOOGLE_SCOPES.split(' ');

const auth = new google.auth.GoogleAuth({
  keyFile: process.env.SA_KEY_PATH,
  scopes: SCOPES,
});
const sheets = google.sheets({ version: 'v4', auth });

const res = await sheets.spreadsheets.values.get({
  spreadsheetId: process.env.SHEET_ID,
  range: 'Orders!A1:D20',
});
console.log(res.data.values);
```

**检查：**返回结果应是一个由行组成的数组。如果遇到权限错误，几乎可以肯定是跳过了第 2 步，或者共享给了错误的邮箱。

## 第 4 步：覆盖还是追加，以及 Sheets 如何解读你的数据

写入需要三样东西：表格 ID、A1 区域和请求体中的数据。写入固定区域用 `values.update`；在表格末尾添加新行用 `values.append`。

```js
await sheets.spreadsheets.values.append({
  spreadsheetId: process.env.SHEET_ID,
  range: 'Orders!A:D',
  valueInputOption: 'USER_ENTERED',
  requestBody: { values: [['DH-1042', 3, 120000, '2026-10-21']] },
});
```

`valueInputOption` 参数是必填项，它决定了数据在用户眼中的样子。`RAW` 原样插入字符串。`USER_ENTERED` 会像有人在 Sheets 界面里手动输入一样解析输入，因此能识别公式和日期。

试一个例子。用 `RAW` 写入字符串 `=SUM(B2:B4)`，单元格显示的就是这串文字；用 `USER_ENTERED` 写入，单元格会变成公式并显示合计值。`2026-10-21` 也一样：一种方式得到字符串，另一种方式得到日期，运营团队的筛选和图表都能用。

**要点:** 对表格的使用者来说，存成字符串的日期就等于一个 bug。

一条值得记住的规则：给人在 Sheets 里看的数据用 `USER_ENTERED`；订单号、电话号码，以及任何可能被误认为数字或公式的内容，用 `RAW` 写入。

**检查：**打开表格，点一下日期单元格，看它是被格式化为日期，还是像文本一样左对齐。

## 第 5 步：配额是设计约束，不是偶发事件

Sheets API 的默认配额是：每个项目每分钟读请求 300 次、写请求 300 次，每个用户每分钟 60 次。超出就会收到 HTTP 429 错误。Google 建议用指数退避算法重试。

算一笔账。你要把 1,000 行推送到表格里，每行调用一次 `append`，就是 1,000 次写请求，超过全项目每分钟 300 次上限的三倍，更不用说低得多的每用户每分钟 60 次。把 1,000 行全部放进一次 `append` 的 `values` 数组，只需要一次请求。

即使做了批量处理，也要给每次调用套上重试函数：

```js
async function withBackoff(fn, maxTries = 5) {
  for (let i = 0; ; i++) {
    try { return await fn(); }
    catch (e) {
      if (e.code !== 429 || i >= maxTries - 1) throw e;
      const wait = 2 ** i * 1000 + Math.random() * 1000;
      await new Promise(r => setTimeout(r, wait));
    }
  }
}
```

这个函数做了简化：只判断 429 错误码，依次等待约 1、2、4、8 秒。额外加上的随机量可以避免多个进程在同一时刻重试。

## 第 6 步：按文件大小选择 Drive 上传方式

这一步不完整演示上传调用，而是帮你在动手之前选对上传方式。Drive API 有两种值得了解的方式。5 MB 及以下的文件可以用 multipart 上传，在同一个请求里同时发送元数据和内容。大于 5 MB 的文件，或者网络连接不稳定时，应使用可续传上传。

使用可续传上传时，除最后一块外，每个分块都必须是 256 KB 的整数倍，即 256 × 1024 = 262,144 字节。例如，以 8 MB（256 KB 的 32 倍）为分块上传一份 20 MB 的报告是合法的；5,000,000 字节的分块则不行，因为这个数不能被 262,144 整除。

```js
const KB256 = 256 * 1024;
function uploadPlan(sizeBytes, chunkBytes = 32 * KB256) {
  if (chunkBytes % KB256 !== 0) throw new Error('分块大小必须是 256 KB 的整数倍');
  return sizeBytes <= 5 * 1024 * 1024 ? 'multipart' : 'resumable';
}
```

上面的函数只负责规划。编写真正的上传调用时，根据它返回的上传方式，从 Drive API 上传指南和 googleapis README 中查到准确写法，再套上第 5 步的 `withBackoff`。

Drive 文件夹同样要像第 2 步那样共享给服务账号的邮箱。脚本只能写入已获授权的位置。

**检查：**分别用 3 MB 的文件、20 MB 的文件以及 `chunkBytes` 为 5,000,000 调用 `uploadPlan`，应依次得到 `multipart`、`resumable` 和一个错误。

## 最常见的错误

最常见的错误是把密钥文件提交进仓库，通常源于一次匆忙的 `git add .`。所以第 1 步才把密钥完全放在仓库之外。

其次是把表格共享给了自己的个人邮箱，而不是服务账号的邮箱，结果花半小时研究权限错误。还有一种是用 `RAW` 写入，然后听运营团队抱怨日期列“筛选不了”。

更隐蔽的一种是逐行调用 API 的循环。它在 20 行测试数据上运行顺畅，到了用真实数据演示时却因 429 错误中断。

## 这项技能在客户现场怎么用？

设想一家物流客户，希望有一个智能体每天早上汇总延迟订单。第一版并不需要数据仓库：智能体读取 `Orders` 工作表，处理后用 `USER_ENTERED` 把结果写入 `Reports` 工作表，再把 PDF 导出到经理已经共享出来的 Drive 文件夹。

用户在每天都会打开的工具里看到结果。这往往是赢得信任最快的方式。

把这项技能写进简历时，不要写“熟悉 Google API”这类空泛的话。要具体，例如：“用 Node.js 搭建数据管道，通过服务账号读写 Google Sheets，批量处理以控制在 API 配额内，用退避策略重试，密钥在仓库外管理”。这句话里的每个短语，都是一道你答得上来的面试题。

把这样的脚本当作系统的初稿，而不是终稿。如果它证明了自己的价值，客户自然会来找你，商量把它迁移到正式的基础设施上。

**本周动手试试:**

- 在测试项目里创建一个服务账号，把一张 Google Sheet 共享给它的邮箱，运行读取 A1:D20 的脚本。
- 把同一个字符串 =SUM(B2:B4) 写入两次，一次用 RAW，一次用 USER_ENTERED，比较得到的两个单元格。
- 给每个 API 调用套上针对 429 错误、带指数退避的重试函数，并把它加进你的项目模板。

## 信源

- [Basic reading / values guide - Google Sheets API](https://developers.google.com/workspace/sheets/api/guides/values)

- [Usage limits - Google Sheets API](https://developers.google.com/workspace/sheets/api/limits)

- [Create access credentials - Google Workspace](https://developers.google.com/workspace/guides/create-credentials)

- [Service accounts overview - IAM documentation](https://docs.cloud.google.com/iam/docs/service-account-overview)

- [googleapis/google-api-nodejs-client (README)](https://github.com/googleapis/google-api-nodejs-client)

- [Upload file data - Google Drive API](https://developers.google.com/workspace/drive/api/guides/manage-uploads)
