FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • 要让脚本访问某个文件或文件夹,像共享给同事一样,把它共享给服务账号的邮箱即可,不需要管理员。
  • 写入时必须指定 valueInputOption:RAW 原样保留字符串,USER_ENTERED 会像在 Sheets 里手动输入一样解析公式和日期。
  • 把多行合并到一次请求里,遇到 429 错误用指数退避重试,JSON 密钥文件绝不能提交到代码库。
横向条形图:每行单独调用一次 append 需要 1,000 次写请求,远超每个项目每分钟 300 次、每个用户每分钟 60 次的配额;把 1,000 行合并到一次 append 中只需 1 次请求。
逐行调用 append 推送 1,000 行,要消耗 1,000 次写请求,是全项目每分钟 300 次上限的三倍多;批量处理后只需一次请求。来源:Google 公布的 Sheets API 默认配额;1,000 行为文中的示例数字。

到新客户那里的第一周,你需要的数据很少放在整洁的数据库里。更常见的情况是,它躺在一个名叫“订单 – 最终版 – 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 都碰不到它:

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>"

<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 安装官方库:

npm install googleapis

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

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。

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 也一样:一种方式得到字符串,另一种方式得到日期,运营团队的筛选和图表都能用。

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

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

第 5 步:配额是设计约束,不是偶发事件

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

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

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

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 整除。

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 配额内,用退避策略重试,密钥在仓库外管理”。这句话里的每个短语,都是一道你答得上来的面试题。

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

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力AI 组件在预发布正常,上了客户生产环境却一片空白问题多半出在 iframe 两侧的两份 CSP 白名单,先认清是哪一侧拒绝,能省下一周邮件往来。