团队常用 Google 表格来存储和共享数据。但当您反复更新同一个表格时,手动复制粘贴会非常耗时。
使用 Google Sheets API,您可以在自己的应用和脚本中自动更新和管理表格。数据可自动拉取与推送,无需手工操作即可保持报告最新。
本指南将一步步带您完成设置、读取、写入、格式化以及自动化常见表格任务。
开始使用 Google Sheets API
要开始使用 Google Sheets API,您需要一个 Google Cloud 项目,以及用于对应用进行身份验证的方式。下面先从整体上了解如何设置。
创建 Google Cloud 项目
所有 Google API 都在 Google Cloud 项目中运行。该项目保存您的凭据、API 设置和用量限制。
创建首个项目的方法如下:
前往 Google Cloud Console 。
点击顶部的 选择项目(Select a project) 。
会出现一个选择项目(Select a project) 弹窗。在此点击 新建项目(New Project) 。
在下一窗口中输入项目名称。
点击 创建(Create) 。
在 Google Console 中创建新项目。图片来源:作者。
项目就绪后,启用所需的 API:
打开您的项目。
点击左上角的三横线。
前往 API 和服务(APIs & Services) > 已启用的 API 和服务(Enabled APIs & services) 。
点击+ 启用 API 和服务(Enable APIs & services) 。
前往 Enable APIs & Services 启用 API。图片来源:作者。
此时将出现 API 库(API Library) 窗口。在搜索栏中搜索 Google Sheets API 并点击。
点击 启用(Enable) 。
启用 Google Sheets API。图片来源:作者。
如果您的应用需要创建、移动或管理表格文件,也请启用 Google Drive API:
搜索 Google Drive API 。
点击 启用(Enable) 。
身份验证与授权
Google Sheets API 支持三种主要的身份验证方式。使用哪一种取决于您的应用工作方式。
OAuth 2.0
适用于真实用户登录并使用其个人表格的场景。用户可以授权访问,您的应用只能执行其允许的操作。
假设您正在构建一款网页应用,允许用户连接其 Google 账号,让您的应用读取或更新其个人表格。这种情况下请选择 OAuth 2.0。
操作步骤如下:
在 Google 控制台中,依次前往 导航菜单(Navigation Menu) (左上角三横线) > API 和服务(API & Services) > OAuth 同意屏幕(OAuth consent screen)
前往 OAuth 同意屏幕。图片来源:作者。
现在填写以下信息:
在应用名称(App name) 字段中填写需要同意的应用名称
填写支持邮箱,便于用户咨询,然后点击 下一步(Next)
选择 外部(External) 受众类型并点击 下一步(Next)
填写联系信息(电子邮件地址),以便 Google 通知您项目变更。然后点击 下一步(Next)
勾选同意其政策的复选框并点击 继续(Continue)
点击 保存(Save) 。您会看到一条消息:已创建 OAuth 配置!(OAuth configuration created!)
现在,为了对终端用户进行身份验证并访问其 Google 表格数据,创建 OAuth 2.0 客户端凭据。客户端 ID 可将您的应用程序唯一标识给 Google 的 OAuth 服务器。
操作步骤如下:
点击 导航菜单(Navigation Menu) > API 和服务(APIs & Services) > 凭据(Credentials) 。
在 凭据(Credentials) 页面,点击 + 创建凭据(+ Create credentials) 并选择 OAuth 客户端 ID(OAuth client ID) 。
前往 OAuth 客户端 ID。图片来源:作者。
在 应用类型(Application type) 下拉菜单中选择 Web 应用(Web Application) 。
输入 OAuth 2.0 客户端的名称,便于在控制台中识别。
在授权重定向 URI(Authorized redirect URIs) 下点击 添加 URI(Add URI)
输入 Google 发送授权响应的重定向 URL。此地址必须与您应用中配置的重定向 URI 完全一致(例如 OAuth 回调端点)。
点击 创建(Create)
复制并保存 客户端 ID(Client ID) 和 客户端密钥(Client Secret) 。
API 密钥
API 密钥标识的是您的项目,而非用户。它们仅适用于公共表格,无法编辑私人文件。
因此,只有在您想从公共 Google 表格读取数据用于网站展示,或用于测试简单脚本时,才应使用这种方式。
生成 API 密钥的方法如下:
前往 导航菜单(Navigation Menu) > API 和服务(APIs & Services) > 凭据(Credentials) 。
前往 API Keys。图片来源:作者。
点击 + 创建凭据(+ Create credentials) ,然后选择 API 密钥(API key) 。
向下滚动,勾选 限制密钥(Restrict key) ,然后从下拉菜单中选择允许该 API 密钥使用的 API。
点击 创建(Create) 。
复制并保存生成的密钥。
保存生成的 API 密钥。图片来源:作者。
服务账号
服务账号让您的应用无需用户登录即可独立运行。您将特定表格共享给服务账号邮箱,并控制其可执行的操作。
如果您要运行计划任务,每晚更新报告,或将数据库数据同步到共享的 Google 表格,服务账号是最佳选择。
下面来看如何创建和配置:
创建并配置服务账号
具体步骤如下:
点击我们之前启用的 Google Sheets API 。
在左上角点击 创建凭据(Create credentials) 按钮。
在 Google Sheets API 中创建凭据。图片来源:作者。
在创建凭据(Create Credentials) 窗口中,确保在选择 API(Select an API) 字段选中 Google Sheets API 。接着选择要访问的数据类型。由于您使用服务账号,请选择 应用数据(Application data) 并点击 下一步(Next) 。
填写凭据。图片来源:作者。
此时会出现新的创建服务账号(Create service account) 窗口:
添加服务账号名称、服务账号 ID 和服务账号描述。
点击 创建并继续(Create and continue) 。
将弹出提示:已创建服务账号(Service account created) 。
在 Google Sheets API 中创建服务账号。图片来源:作者。
服务账号不使用登录或同意屏幕。它通过存储在 JSON 密钥文件中的私钥进行身份验证。该密钥文件使应用服务器能够向 Google 证明其身份并自动请求访问令牌。
现在生成密钥文件:
打开该服务账号。(您也可以在 IAM 与管理(IAM & Admin) > 服务账号(Service Account) 下找到它)
转到 密钥(Keys) 选项卡。
点击 添加密钥(Add key) > 创建新密钥(Create new key) 。
选择 JSON 并点击 创建(Create) 。
文件将开始下载。
为 Google Sheets API 生成 JSON 密钥文件。图片来源:作者。
将表格共享给服务账号
服务账号并不会自动获得对您表格的访问权限。您必须将每个文件共享给该服务账号邮箱。
具体方法:
打开我们下载的文件,查找 client_email 。或者在 服务账号(Service Account) 菜单下点击我们创建的服务账号,查找 邮箱(Email) 。二者是同一个邮箱。
复制该邮箱。
从 JSON 密钥文件中复制客户端邮箱。图片来源:作者。
打开该 Google 表格。
点击右上角的 共享(Share) 选项。
将刚才复制的邮箱粘贴到共享输入框中。
选择 查看者(Viewer) (允许读取与写入数据)或 编辑者(Editor) (仅允许读取) 访问权限。
点击 发送(Send) 以共享访问权限。
通过 Google 表格共享服务账号访问权限。图片来源:作者。
安装客户端库
Google 提供了官方客户端库,简化与 Sheets API 的交互。它们会为您处理身份验证、请求格式化与重试。实际上,这比手写原始 HTTP 请求更简单、更安全。
以下是常见的 多语言安装示例 :
Python
pip install google- api- python- client google- auth google- auth- oauthlib技术支持
Node.js
npm install googleapis技术支持
Java (使用 Maven 添加客户端库)
<dependency>
<groupId>com.google.apis</groupId>
<artifactId>google-api-services-sheets</artifactId>
</dependency>技术支持
注意 :随着项目增长,使用客户端库能节省搭建时间并减少错误。
核心数据操作
Google Sheets API 主要用于读取、写入、更新与格式化表格数据。我们来逐一了解:
从表格读取数据
要从 Google 表格读取数据,您需要两项信息:表格的 Spreadsheet ID,以及要访问的单元格范围。
Spreadsheet ID 来自 Google 表格的 URL。它是 /d/ 与 /edit 之间的那串长字符。API 通过它确定要读取哪一个表格。
例如,如果我的表格 URL 为:https://docs.google.com/spreadsheets/d/1s4-xSl1ztvdXmCUISe14XZWduQoJ4Ignz_HrgqsExPI/edit?gid=0#gid=0
则 Spreadsheet ID 为:1s4-xSl1ztvdXmCUISe14XZWduQoJ4Ignz_HrgqsExPI
Spreadsheet ID。图片来源:作者。
范围使用 A1 标记法书写,通过列字母与行数字描述单元格。例如:
A1 读取单个单元格
A1:C10 读取一块单元格区域
Sheet1!A:A 读取整列
Sheet1!1:1 读取整行
为获取值,API 提供两种主要方法:
读取数据不会更改表格本身。它仅返回值,供您的应用在其他地方使用。可用于为仪表板拉取数据、导出数据进行分析,以及生成自动化报告。
向表格写入数据
写入数据与读取类似。您同样需要 Spreadsheet ID 和范围,但这次还需发送要写入的值。
Google Sheets API 为此提供两种主要方法:
值输入选项
写入数据时,您还需选择 Google 表格如何处理发送的值,这由 ValueInputOption 控制。
例如,如果您发送 =SUM(1,2):
使用 RAW,它会作为纯文本存储
使用 USER_ENTERED,它会作为公式求值
覆盖与追加
在 update 与 append 之间选择,取决于您的表格结构。
在以下情况下使用 update:
在以下情况下使用 append:
批量操作
批量操作允许您在单个 API 请求中分组多个更改。这可减少应用发起的调用次数,有助于保持在用量限制之内。
Google Sheets API 中有两种常见的批量模式。
对于值的读取与写入,可使用:
对于结构与格式更改,使用 spreadsheets.batchUpdate 。这是最有用的批量方法,支持在一次请求中执行多种操作。
借助 spreadsheets.batchUpdate,您可以组合如下更改:
创建或删除工作表
重命名电子表格或选项卡
冻结表头行
更改列宽
应用格式
一次更新多个范围
例如,与其分别发送请求来重命名电子表格并创建新选项卡,不如在一次 batchUpdate 调用中完成二者。这更快,也更便于在工作流增多时管理。
您可以使用批量操作来搭建报告、应用统一格式,或在整个表格中执行大规模更新。
更新与删除数据
更新数据是指替换特定单元格或范围中的值。通常用于刷新数据、更新 KPI,或覆盖表格中固定的输出区域。
要更新现有值,请使用 spreadsheets.values.update。您需要指定目标范围并发送新值,该范围内的现有数据会被替换。
清除 vs. 删除
清除数据与删除数据并不相同:
清除数据会移除单元格内的值,但保留表格、布局和格式。需要在不影响结构的情况下清空范围,请使用 spreadsheets.values.clear 。
示例:在将新数据写入同一单元格前,先清除旧的报告区块。
删除数据是指移除整个工作表选项卡。使用 spreadsheets.batchUpdate 搭配 deleteSheet 请求完成。删除工作表会永久移除其数据与结构。
由于删除操作不可逆,应谨慎使用,仅在确定数据不再需要时执行。
高级功能
除了读写数据,Google Sheets API 还能控制表格的外观与行为,从而大规模自动化格式与视觉规则。
格式与条件格式
您可以通过 API 以编程方式应用单元格格式,而无需在表格界面中手动操作。包括文本样式、颜色、数字格式与布局更改。
所有格式更改都以 JSON 请求的形式,通过 spreadsheets.batchUpdate 发送。每个请求描述要更改的内容以及应用位置。
常见的格式任务包括:
将表头行加粗
为货币或百分比应用数字格式
调整列宽
为特定范围设置背景色
例如,您可以将请求定位到工作表的第一行,并设置为加粗且带浅色背景。请求使用从 0 开始的索引,其中行 0 表示第一行。
条件格式
条件格式可根据单元格的值自动应用样式。如果您希望表格自动高亮关键信息而无需人工审阅,条件格式很有帮助。
使用 API 时,条件格式规则以 JSON 定义,并通过 spreadsheets.batchUpdate 应用。
您可以用于:
将负值标红
标记高于或低于阈值的数值
自动为满足特定条件的行设置样式
例如,您可以定义一条规则,自动高亮某列中任何小于 0 的值。应用后,随着数据变化,格式会自动更新。
数据透视表与数据汇总
Google Sheets API 能通过代码创建与更新数据透视表。数据透视表在不改变原始数据的情况下汇总大型数据集,有助于报告与分析。
您只需通过 JSON 请求定义数据透视表,然后使用 spreadsheets.batchUpdate 应用。这些请求描述数据应如何分组、汇总与展示。
通过 API,您可以:
选择哪些列用作行标签
选择汇总方法,如求和、计数或平均
控制数据透视表出现的位置
在新增数据时刷新或修改数据透视表
例如,按关键词分组并自动计算总点击与展示次数。底层数据变化后,数据透视表会自动更新。
Connected Sheets 与 BigQuery 集成
Connected Sheets 让 Google 表格可直接连接 BigQuery 。BigQuery 处理海量数据,Sheets 负责分析与报告。
无需将数百万行复制到表格中,Connected Sheets 会在 BigQuery 上运行查询并展示结果。即便面对超大数据集,表格依然快速流畅。
连接需在 Google 表格内创建。设置连接本身不使用 Sheets API。
工作方式如下:
数据保存在 BigQuery 表中
您将 Google 表格连接到该表
表格运行查询并显示结果
无需导出文件即可刷新数据
连接完成后,您可以直接在表格中构建数据透视表、应用公式并创建报告。
身份验证与权限
Connected Sheets 的访问通过 Google Cloud 身份与访问管理 控制。
将表格连接到 BigQuery 的账号必须具备:
BigQuery Data Viewer 权限
BigQuery Job User 权限
对该 Google 表格的访问权限
身份验证将通过 Google 表格界面自动完成。
不过需注意一些限制。虽然 Sheets API 可以从 Connected Sheets 读取数据、应用格式或构建数据透视表,但它无法修改底层 BigQuery 查询,也不能向由 BigQuery 支持的范围写入数据。
因此,Connected Sheets 更适合分析与报告,而非插入或编辑原始数据。
使用零代码集成工具
并非所有工作流都需要自定义代码。多种零/低代码工具可直接连接 Google Sheets API,并为您处理技术细节。最受欢迎的三种包括:
这些工具提供可视化界面,便于选择数据源、设置计划、并将结果发送到 Google 表格。它们在后台处理身份验证、API 请求与错误处理。
对于需要可靠数据管道但不想写代码的市场与分析人员而言,这些工具非常合适。它们还能缩短常见报告与仪表板场景的搭建时间。
定价与 API 限制
对大多数项目而言,您可以免费使用 Google Sheets API。关键在于了解用量限制的工作方式。
API 定价概览
Google 并不会按请求或按表格操作计费,而是通过配额进行控制。
只要您的项目保持在这些限制内,就可以免费使用 API。若超出限制,请求会被暂时阻止,直至用量下降或配额提高。
用量限制与配额
Google Sheets API 设有限制 以保持性能稳定并防止滥用。这些限制通常按项目计算,有时也按用户计算。
大多数项目会遇到两种主要限制:
1. 每分钟请求数: 该限制控制项目在短时间内可发送的 API 调用次数。一次性发送过多小请求可能触发临时错误。
默认情况下,Google Sheets API 允许:
读取请求
写入请求
每个项目每分钟 300 次请求
每个项目每分钟 300 次请求
每个用户每分钟 60 次请求
每个用户每分钟 60 次请求
2. 每日请求数: 对于读写数据,项目每日请求次数没有固定上限。您可以在整天(24 小时周期)持续使用 API。
限制主要针对每分钟发送的请求数,而非全天总量。
为保持在限制内并避免问题:
将多个更新批量合并到一个请求中
避免为细微更改反复读取
缓存数据,避免重复拉取
在 Google Cloud Console 监控用量并及早调整
性能优化与配额管理
在自动化 Google 表格时,性能问题通常源于过快地发送过多请求。因此,理解配额机制非常重要。
理解 API 配额与速率限制
Google 通过配额限制您的项目在一定时间内可发送的请求数。有的限制按项目生效,有的则按用户生效。
这些限制会直接影响自动化工作流。如果脚本请求过多过快,API 会开始返回错误,工作流也会中断。常见于:
逐行更新
反复读取大范围数据
未做批量处理而高频运行
监控用量有助于您及早发现问题。在 Google Cloud Console 中,您可以查看项目距离限制的接近程度,并识别活动的突然攀升。方法如下:
打开您的项目。
前往API 和服务(APIs & Services) > 已启用的 API 和服务(Enabled API Services)
点击Google Sheets API 。
打开配额与系统限制(Quotas & System Limits) 。
如果发现突然的峰值,通常意味着请求模式效率不高。
配额与系统限制。图片来源:作者。
实现指数退避
即便是编写良好的脚本也可能遇到临时 API 错误。最常见且容易识别的包括:
429 错误表示在短时间内发送了过多请求
5xx 错误表示 API 发生临时服务器问题
这类错误通常会自行恢复。立刻重试可能会使问题更糟。
指数退避是安全重试请求的标准做法。脚本不会立即重试,而是先等待;每次失败后的等待时间都会增加。
一个简单的退避模式如下:
发送请求
如果收到 429 或 5xx 错误,等待 1 秒
重试
若再次失败,依次等待 2 秒、4 秒、8 秒
在达到最大等待时间或最大重试次数后停止
这种方式能降低对 API 的压力,并提高重试成功率。
指数退避实战
以下是一个使用指数退避来重试请求的简单 Python 示例:
import time
from googleapiclient. errors import HttpError
def run_with_backoff ( callable_request, max_retries= 5 ) :
delay = 1
for attempt in range ( max_retries) :
try :
return callable_request( )
except HttpError as e:
status = getattr ( e. resp, "status" , None )
if status in [ 429 , 500 , 502 , 503 , 504 ] :
time. sleep( delay)
delay = min ( delay * 2 , 32 )
continue
raise
raise RuntimeError( "Request failed after retries." ) 技术支持
随后,您可以用这个辅助函数包装任意 API 调用:
result = run_with_backoff(
lambda : service. spreadsheets( ) . values( ) . get(
spreadsheetId= spreadsheet_id,
range = "Report!A1:E100"
) . execute( )
) 技术支持
这能避免在问题只是暂时性时让脚本立刻失败,从而让工作流更稳定地运行。
优化策略
当您减少请求数量并控制负载大小时,性能会更好。多数变慢源于脚本在单次调用中做了过多工作。
以下做法最能有效避免变慢:
批量请求
使用 spreadsheets.values.batchGet、spreadsheets.values.batchUpdate 和 spreadsheets.batchreadsheets.batchUpdate 等批量方法,将多项操作合并为一个请求。这能带来最大的性能收益。
缓存
反复读取相同数据既浪费时间也浪费配额。获取一次表格元数据或工作表 ID,然后在脚本运行期间重复使用。
分页
部分 API 响应会分页返回。请逐页处理,而非一次性加载全部。在处理大数据集时,这可避免超时与内存问题。
Gzip 压缩
大多数 Google 客户端库和 HTTP 客户端都自动支持 gzip 压缩。当响应很大(如读取宽范围或获取表格元数据)时,压缩能减小体积。
部分响应
在可用时,仅请求所需字段,而非完整资源。更小的响应更快、带宽占用更少。
最小化负载
避免逐个单元格写入,尽量成块写入。若格式无变化则不必更新,避免不必要的数据重发。
一个简单的经验法则:如果脚本在循环行时于循环内发起 API 调用,它就无法扩展。请进行批量处理,减少请求次数并尽量减小负载。
错误处理与故障排查
使用任意 API 都会遇到错误。下面来看看如何快速定位问题并保持自动化的可靠性。
常见的身份验证问题
在起步阶段,身份验证问题是最常见的错误来源。多数来自配置问题,而非代码缺陷。
常见问题包括:
权限被拒错误 :未将表格共享给服务账号邮箱,或用户未授予所需的 OAuth 作用域
凭据无效或文件未找到 :JSON 密钥文件路径错误或文件名不匹配
API 未启用错误 :Google Sheets API 未在与凭据相同的 Google Cloud 项目中启用
OAuth 问题常见于作用域与操作不匹配。例如,只读作用域无法执行写入。
服务账号问题通常源于未共享文件。服务账号无法看到任何表格,除非将该表格明确共享给其邮箱。
数据格式与请求错误
当发送的数据与 API 期望不匹配时,通常会发生请求错误。错误信息往往具有描述性,但起初可能仍令人困惑。
常见原因包括:
排查时务必阅读完整错误响应,因为 Google API 往往会指明具体哪个字段未通过校验。
服务可用性与性能挑战
与其他云服务一样,Google Sheets API 在高负载或短暂中断期间,偶尔会返回 503 Service Unavailable 等服务器错误。
这些错误通常是暂时的。但请勿立刻重试,因为这可能会加剧问题。
更有效地处理可靠性问题:
仅对 429 与 5xx 等瞬时错误进行重试
在重试之间使用指数退避
批量请求以减少流量
监控配额使用,避免打到上限
稳健的集成应假设部分请求可能失败。通过合理的重试、批量处理与监控,脚本即可自动恢复并持续运行,无需人工干预。
最佳实践与安全
Google Sheets API 易于上手,但长期可靠性取决于我们如何设计与保障其安全。
开发工具与资源
Google 提供官方工具与资源,帮助更安全、更高效地开发:
客户端库与 SDK 的使用
Google 维护了 Sheets API 的官方客户端库。它们会处理身份验证、重试与请求格式化。使用受支持的库能减少错误并节省时间,也比自写 HTTP 代码更能适应 API 更新。
支持的语言包括 Python、 JavaScript(Node.js)、 Java 与 Go。
各库遵循相同的核心 API 结构,但也提供部分语言专属的辅助工具。由于上手更简单、社区支持更强,Python 与 Node.js 常被用于自动化。
客户端库也能与其他 Google API 无缝集成,这在工作流涉及 Drive、BigQuery 或 Gmail 时尤为有用。
凭据管理与安全
凭据控制着对您数据的访问,请按以下最佳实践妥善处理:
切勿将密钥文件提交到版本控制
将密钥存放在公共仓库之外
在生产环境使用环境变量或机密管理服务
仅授予所需的最小权限
优先使用窄权限角色而非宽泛角色
将服务账号访问限制在特定任务
留意异常峰值或不明的访问模式
定期轮换密钥,若密钥泄露请立即吊销并更换
结语
最好的下一步,是先将您已经手动执行的一项小任务实现自动化。选一个您可控的表格,读取一个范围,然后向其中写入或追加数据。成功后,为它设定计划任务,让它自行运行。
这正是 Google Sheets API 发挥价值的起点。
您无需立刻搭建复杂系统。让一条流程稳定可靠,就足以节省时间,并让后续构建更轻松。若您希望在自动化的同时精进技能, 欢迎查看我们的 Google Sheets 基础 学习路径,或 Introduction to Google Sheets 与 Intermediate Google Sheets 课程,助您在每条自动化流程中获得更高价值。
团队常用 Google 表格来存储和共享数据。但当您反复更新同一个表格时,手动复制粘贴会非常耗时。
使用 Google Sheets API,您可以在自己的应用和脚本中自动更新和管理表格。数据可自动拉取与推送,无需手工操作即可保持报告最新。
本指南将一步步带您完成设置、读取、写入、格式化以及自动化常见表格任务。
开始使用 Google Sheets API
要开始使用 Google Sheets API,您需要一个 Google Cloud 项目,以及用于对应用进行身份验证的方式。下面先从整体上了解如何设置。
创建 Google Cloud 项目
所有 Google API 都在 Google Cloud 项目中运行。该项目保存您的凭据、API 设置和用量限制。
创建首个项目的方法如下:
在 Google Console 中创建新项目。图片来源:作者。
项目就绪后,启用所需的 API:
前往 Enable APIs & Services 启用 API。图片来源:作者。
启用 Google Sheets API。图片来源:作者。
如果您的应用需要创建、移动或管理表格文件,也请启用 Google Drive API:
身份验证与授权
Google Sheets API 支持三种主要的身份验证方式。使用哪一种取决于您的应用工作方式。
OAuth 2.0
适用于真实用户登录并使用其个人表格的场景。用户可以授权访问,您的应用只能执行其允许的操作。
假设您正在构建一款网页应用,允许用户连接其 Google 账号,让您的应用读取或更新其个人表格。这种情况下请选择 OAuth 2.0。
操作步骤如下:
前往 OAuth 同意屏幕。图片来源:作者。
现在,为了对终端用户进行身份验证并访问其 Google 表格数据,创建 OAuth 2.0 客户端凭据。客户端 ID 可将您的应用程序唯一标识给 Google 的 OAuth 服务器。
操作步骤如下:
前往 OAuth 客户端 ID。图片来源:作者。
API 密钥
API 密钥标识的是您的项目,而非用户。它们仅适用于公共表格,无法编辑私人文件。
因此,只有在您想从公共 Google 表格读取数据用于网站展示,或用于测试简单脚本时,才应使用这种方式。
生成 API 密钥的方法如下:
前往 API Keys。图片来源:作者。
保存生成的 API 密钥。图片来源:作者。
服务账号
服务账号让您的应用无需用户登录即可独立运行。您将特定表格共享给服务账号邮箱,并控制其可执行的操作。
如果您要运行计划任务,每晚更新报告,或将数据库数据同步到共享的 Google 表格,服务账号是最佳选择。
下面来看如何创建和配置:
创建并配置服务账号
具体步骤如下:
在 Google Sheets API 中创建凭据。图片来源:作者。
填写凭据。图片来源:作者。
将弹出提示:已创建服务账号(Service account created)。
在 Google Sheets API 中创建服务账号。图片来源:作者。
服务账号不使用登录或同意屏幕。它通过存储在 JSON 密钥文件中的私钥进行身份验证。该密钥文件使应用服务器能够向 Google 证明其身份并自动请求访问令牌。
现在生成密钥文件:
文件将开始下载。
为 Google Sheets API 生成 JSON 密钥文件。图片来源:作者。
将表格共享给服务账号
服务账号并不会自动获得对您表格的访问权限。您必须将每个文件共享给该服务账号邮箱。
具体方法:
从 JSON 密钥文件中复制客户端邮箱。图片来源:作者。
通过 Google 表格共享服务账号访问权限。图片来源:作者。
安装客户端库
Google 提供了官方客户端库,简化与 Sheets API 的交互。它们会为您处理身份验证、请求格式化与重试。实际上,这比手写原始 HTTP 请求更简单、更安全。
以下是常见的 多语言安装示例:
Python
Node.js
Java(使用 Maven 添加客户端库)
注意:随着项目增长,使用客户端库能节省搭建时间并减少错误。
核心数据操作
Google Sheets API 主要用于读取、写入、更新与格式化表格数据。我们来逐一了解:
从表格读取数据
要从 Google 表格读取数据,您需要两项信息:表格的 Spreadsheet ID,以及要访问的单元格范围。
Spreadsheet ID 来自 Google 表格的 URL。它是
/d/与/edit之间的那串长字符。API 通过它确定要读取哪一个表格。例如,如果我的表格 URL 为:
https://docs.google.com/spreadsheets/d/1s4-xSl1ztvdXmCUISe14XZWduQoJ4Ignz_HrgqsExPI/edit?gid=0#gid=0则 Spreadsheet ID 为:
1s4-xSl1ztvdXmCUISe14XZWduQoJ4Ignz_HrgqsExPISpreadsheet ID。图片来源:作者。
范围使用 A1 标记法书写,通过列字母与行数字描述单元格。例如:
A1读取单个单元格A1:C10读取一块单元格区域Sheet1!A:A读取整列Sheet1!1:1读取整行为获取值,API 提供两种主要方法:
spreadsheets.values.get从单个范围读取数据。当您明确知道需要哪个表或区域时使用。spreadsheets.values.batchGet在一次请求中读取多个范围。当您想同时从多个位置读取数据时使用,例如一个表中的汇总和另一个表中的明细。读取数据不会更改表格本身。它仅返回值,供您的应用在其他地方使用。可用于为仪表板拉取数据、导出数据进行分析,以及生成自动化报告。
向表格写入数据
写入数据与读取类似。您同样需要 Spreadsheet ID 和范围,但这次还需发送要写入的值。
Google Sheets API 为此提供两种主要方法:
spreadsheets.values.update:当您要将数据写入特定范围并覆盖现有内容时使用。例如,如果要用新列名替换表格的表头行,update是正确选择。您发送的值将替换该范围内的现有单元格。spreadsheets.values.append:当您希望在不影响现有数据的情况下添加新行时使用。适用于数据持续增长的场景,如记录每日指标、添加新记录或存储表单响应。API 会自动在最后一个非空行之后插入新值。值输入选项
写入数据时,您还需选择 Google 表格如何处理发送的值,这由
ValueInputOption控制。RAW按原样存储值USER_ENTERED将值视为在表格中手动输入例如,如果您发送
=SUM(1,2):使用
RAW,它会作为纯文本存储使用
USER_ENTERED,它会作为公式求值覆盖与追加
在
update与append之间选择,取决于您的表格结构。在以下情况下使用 update:
在以下情况下使用 append:
批量操作
批量操作允许您在单个 API 请求中分组多个更改。这可减少应用发起的调用次数,有助于保持在用量限制之内。
Google Sheets API 中有两种常见的批量模式。
对于值的读取与写入,可使用:
spreadsheets.values.batchGet一次读取多个范围spreadsheets.values.batchUpdate在一次请求中写入多个范围对于结构与格式更改,使用
spreadsheets.batchUpdate。这是最有用的批量方法,支持在一次请求中执行多种操作。借助
spreadsheets.batchUpdate,您可以组合如下更改:例如,与其分别发送请求来重命名电子表格并创建新选项卡,不如在一次
batchUpdate调用中完成二者。这更快,也更便于在工作流增多时管理。您可以使用批量操作来搭建报告、应用统一格式,或在整个表格中执行大规模更新。
更新与删除数据
更新数据是指替换特定单元格或范围中的值。通常用于刷新数据、更新 KPI,或覆盖表格中固定的输出区域。
要更新现有值,请使用
spreadsheets.values.update。您需要指定目标范围并发送新值,该范围内的现有数据会被替换。清除 vs. 删除
清除数据与删除数据并不相同:
清除数据会移除单元格内的值,但保留表格、布局和格式。需要在不影响结构的情况下清空范围,请使用
spreadsheets.values.clear。示例:在将新数据写入同一单元格前,先清除旧的报告区块。
删除数据是指移除整个工作表选项卡。使用
spreadsheets.batchUpdate搭配deleteSheet请求完成。删除工作表会永久移除其数据与结构。由于删除操作不可逆,应谨慎使用,仅在确定数据不再需要时执行。
高级功能
除了读写数据,Google Sheets API 还能控制表格的外观与行为,从而大规模自动化格式与视觉规则。
格式与条件格式
您可以通过 API 以编程方式应用单元格格式,而无需在表格界面中手动操作。包括文本样式、颜色、数字格式与布局更改。
所有格式更改都以 JSON 请求的形式,通过
spreadsheets.batchUpdate发送。每个请求描述要更改的内容以及应用位置。常见的格式任务包括:
例如,您可以将请求定位到工作表的第一行,并设置为加粗且带浅色背景。请求使用从 0 开始的索引,其中行
0表示第一行。条件格式
条件格式可根据单元格的值自动应用样式。如果您希望表格自动高亮关键信息而无需人工审阅,条件格式很有帮助。
使用 API 时,条件格式规则以 JSON 定义,并通过
spreadsheets.batchUpdate应用。您可以用于:
例如,您可以定义一条规则,自动高亮某列中任何小于
0的值。应用后,随着数据变化,格式会自动更新。数据透视表与数据汇总
Google Sheets API 能通过代码创建与更新数据透视表。数据透视表在不改变原始数据的情况下汇总大型数据集,有助于报告与分析。
您只需通过 JSON 请求定义数据透视表,然后使用
spreadsheets.batchUpdate应用。这些请求描述数据应如何分组、汇总与展示。通过 API,您可以:
例如,按关键词分组并自动计算总点击与展示次数。底层数据变化后,数据透视表会自动更新。
Connected Sheets 与 BigQuery 集成
Connected Sheets 让 Google 表格可直接连接 BigQuery。BigQuery 处理海量数据,Sheets 负责分析与报告。
无需将数百万行复制到表格中,Connected Sheets 会在 BigQuery 上运行查询并展示结果。即便面对超大数据集,表格依然快速流畅。
连接需在 Google 表格内创建。设置连接本身不使用 Sheets API。
工作方式如下:
连接完成后,您可以直接在表格中构建数据透视表、应用公式并创建报告。
身份验证与权限
Connected Sheets 的访问通过 Google Cloud 身份与访问管理控制。
将表格连接到 BigQuery 的账号必须具备:
身份验证将通过 Google 表格界面自动完成。
不过需注意一些限制。虽然 Sheets API 可以从 Connected Sheets 读取数据、应用格式或构建数据透视表,但它无法修改底层 BigQuery 查询,也不能向由 BigQuery 支持的范围写入数据。
因此,Connected Sheets 更适合分析与报告,而非插入或编辑原始数据。
使用零代码集成工具
并非所有工作流都需要自定义代码。多种零/低代码工具可直接连接 Google Sheets API,并为您处理技术细节。最受欢迎的三种包括:
这些工具提供可视化界面,便于选择数据源、设置计划、并将结果发送到 Google 表格。它们在后台处理身份验证、API 请求与错误处理。
对于需要可靠数据管道但不想写代码的市场与分析人员而言,这些工具非常合适。它们还能缩短常见报告与仪表板场景的搭建时间。
定价与 API 限制
对大多数项目而言,您可以免费使用 Google Sheets API。关键在于了解用量限制的工作方式。
API 定价概览
Google 并不会按请求或按表格操作计费,而是通过配额进行控制。
只要您的项目保持在这些限制内,就可以免费使用 API。若超出限制,请求会被暂时阻止,直至用量下降或配额提高。
用量限制与配额
Google Sheets API 设有限制以保持性能稳定并防止滥用。这些限制通常按项目计算,有时也按用户计算。
大多数项目会遇到两种主要限制:
1. 每分钟请求数:该限制控制项目在短时间内可发送的 API 调用次数。一次性发送过多小请求可能触发临时错误。
默认情况下,Google Sheets API 允许:
读取请求
写入请求
每个项目每分钟 300 次请求
每个项目每分钟 300 次请求
每个用户每分钟 60 次请求
每个用户每分钟 60 次请求
2. 每日请求数:对于读写数据,项目每日请求次数没有固定上限。您可以在整天(24 小时周期)持续使用 API。
限制主要针对每分钟发送的请求数,而非全天总量。
为保持在限制内并避免问题:
性能优化与配额管理
在自动化 Google 表格时,性能问题通常源于过快地发送过多请求。因此,理解配额机制非常重要。
理解 API 配额与速率限制
Google 通过配额限制您的项目在一定时间内可发送的请求数。有的限制按项目生效,有的则按用户生效。
这些限制会直接影响自动化工作流。如果脚本请求过多过快,API 会开始返回错误,工作流也会中断。常见于:
监控用量有助于您及早发现问题。在 Google Cloud Console 中,您可以查看项目距离限制的接近程度,并识别活动的突然攀升。方法如下:
如果发现突然的峰值,通常意味着请求模式效率不高。
配额与系统限制。图片来源:作者。
实现指数退避
即便是编写良好的脚本也可能遇到临时 API 错误。最常见且容易识别的包括:
这类错误通常会自行恢复。立刻重试可能会使问题更糟。
指数退避是安全重试请求的标准做法。脚本不会立即重试,而是先等待;每次失败后的等待时间都会增加。
一个简单的退避模式如下:
这种方式能降低对 API 的压力,并提高重试成功率。
指数退避实战
以下是一个使用指数退避来重试请求的简单 Python 示例:
随后,您可以用这个辅助函数包装任意 API 调用:
这能避免在问题只是暂时性时让脚本立刻失败,从而让工作流更稳定地运行。
优化策略
当您减少请求数量并控制负载大小时,性能会更好。多数变慢源于脚本在单次调用中做了过多工作。
以下做法最能有效避免变慢:
批量请求
使用
spreadsheets.values.batchGet、spreadsheets.values.batchUpdate和spreadsheets.batchreadsheets.batchUpdate等批量方法,将多项操作合并为一个请求。这能带来最大的性能收益。缓存
反复读取相同数据既浪费时间也浪费配额。获取一次表格元数据或工作表 ID,然后在脚本运行期间重复使用。
分页
部分 API 响应会分页返回。请逐页处理,而非一次性加载全部。在处理大数据集时,这可避免超时与内存问题。
Gzip 压缩
大多数 Google 客户端库和 HTTP 客户端都自动支持 gzip 压缩。当响应很大(如读取宽范围或获取表格元数据)时,压缩能减小体积。
部分响应
在可用时,仅请求所需字段,而非完整资源。更小的响应更快、带宽占用更少。
最小化负载
避免逐个单元格写入,尽量成块写入。若格式无变化则不必更新,避免不必要的数据重发。
一个简单的经验法则:如果脚本在循环行时于循环内发起 API 调用,它就无法扩展。请进行批量处理,减少请求次数并尽量减小负载。
错误处理与故障排查
使用任意 API 都会遇到错误。下面来看看如何快速定位问题并保持自动化的可靠性。
常见的身份验证问题
在起步阶段,身份验证问题是最常见的错误来源。多数来自配置问题,而非代码缺陷。
常见问题包括:
OAuth 问题常见于作用域与操作不匹配。例如,只读作用域无法执行写入。
服务账号问题通常源于未共享文件。服务账号无法看到任何表格,除非将该表格明确共享给其邮箱。
数据格式与请求错误
当发送的数据与 API 期望不匹配时,通常会发生请求错误。错误信息往往具有描述性,但起初可能仍令人困惑。
常见原因包括:
A1 标记无效:工作表名称拼写错误或范围不存在
数据结构不正确:即使只写入单行,也必须以二维数组形式发送值
类型不匹配:数字、日期与公式会因
valueInputOption不同而有不同表现排查时务必阅读完整错误响应,因为 Google API 往往会指明具体哪个字段未通过校验。
服务可用性与性能挑战
与其他云服务一样,Google Sheets API 在高负载或短暂中断期间,偶尔会返回503 Service Unavailable等服务器错误。
这些错误通常是暂时的。但请勿立刻重试,因为这可能会加剧问题。
更有效地处理可靠性问题:
稳健的集成应假设部分请求可能失败。通过合理的重试、批量处理与监控,脚本即可自动恢复并持续运行,无需人工干预。
最佳实践与安全
Google Sheets API 易于上手,但长期可靠性取决于我们如何设计与保障其安全。
开发工具与资源
Google 提供官方工具与资源,帮助更安全、更高效地开发:
客户端库与 SDK 的使用
Google 维护了 Sheets API 的官方客户端库。它们会处理身份验证、重试与请求格式化。使用受支持的库能减少错误并节省时间,也比自写 HTTP 代码更能适应 API 更新。
支持的语言包括Python、JavaScript(Node.js)、Java 与 Go。
各库遵循相同的核心 API 结构,但也提供部分语言专属的辅助工具。由于上手更简单、社区支持更强,Python 与 Node.js 常被用于自动化。
客户端库也能与其他 Google API 无缝集成,这在工作流涉及 Drive、BigQuery 或 Gmail 时尤为有用。
凭据管理与安全
凭据控制着对您数据的访问,请按以下最佳实践妥善处理:
切勿将密钥文件提交到版本控制
将密钥存放在公共仓库之外
在生产环境使用环境变量或机密管理服务
仅授予所需的最小权限
优先使用窄权限角色而非宽泛角色
将服务账号访问限制在特定任务
留意异常峰值或不明的访问模式
定期轮换密钥,若密钥泄露请立即吊销并更换
结语
最好的下一步,是先将您已经手动执行的一项小任务实现自动化。选一个您可控的表格,读取一个范围,然后向其中写入或追加数据。成功后,为它设定计划任务,让它自行运行。
这正是 Google Sheets API 发挥价值的起点。
您无需立刻搭建复杂系统。让一条流程稳定可靠,就足以节省时间,并让后续构建更轻松。若您希望在自动化的同时精进技能,欢迎查看我们的 Google Sheets 基础学习路径,或 Introduction to Google Sheets 与 Intermediate Google Sheets 课程,助您在每条自动化流程中获得更高价值。