Google Sheets

Google Sheets 是一个办公协同插件，以插件能力的形式出现在指令树「扩展能力」中。安装或内置加载后，可把插件里的节点拖到工作流画布使用。

插件标识：rpa-plugin-google-sheets
插件分类：办公协同插件
节点数量：9 个

先选使用方式

方式	怎么用	适合人群
可视化编排（推荐）	在「扩展能力」中找到 Google Sheets，拖入需要的节点并填写参数	大多数用户，适合按表单配置插件能力
代码编排（执行指令 XML）	通过「执行指令（XML）」调用节点的 type 与参数	需要动态拼装、循环调用或批量处理的用户

什么时候用？

• Google Sheets 业务节点 + 凭据连接：9 个原子节点覆盖元信息查询 / 范围读写 / 末行追加 / 内容清空 / 批量读写。OAuth2 refresh_token 鉴权，进程级 access_token 缓存避免重复换 token；A1 表示法支持 sheetName+a1 自动拼装。
• 需要在自动化流程中复用该插件提供的读取、写入、同步或处理能力。

使用前确认

• 需要先配置连接：google-sheets。
• 办公协同类能力需要确认文件、表格、空间或数据库的访问权限。
• 建议先运行连通性、查询或只读节点，确认权限和参数正确后再执行写入类节点。

连接配置

连接类型	名称	说明
google-sheets	google-sheets	Google OAuth2 Refresh Token 凭据（用于业务节点 + HTTP 节点鉴权）

节点总览

节点名称	节点标识	说明
连通性测试	GoogleSheetsPing	用 OAuth2 refresh_token 换一次 access_token 验证凭据可用；若填了 spreadsheetId 还会额外读一次该表元信息验证表级权限
获取 Spreadsheet 元信息	GetGoogleSpreadsheetMeta	获取整个 spreadsheet 的元信息（标题 + 所有 sheet 的属性）
列出所有 Sheet（tab）	ListGoogleSpreadsheetSheets	列出 spreadsheet 下所有 sheet（tab）的属性
读取 Range	GetGoogleSheetRange	按 A1 表示法读取一个 range 的数据。注意：末尾空行/空列会被裁剪
覆盖写 Range	SetGoogleSheetRange	覆盖写一个 range（不是 patch）。USER_ENTERED 模式下 ’=’ 开头会被当公式解析
追加行	AppendGoogleSheetRow	在 range 内的最后一行非空之后追加新行。推荐 range 用 ‘Sheet1!A:Z’ 或 ‘Sheet1’
清空 Range	ClearGoogleSheetRange	清空 range 的 values（保留格式 / 数据校验等单元格属性）；如需删除行列结构请走 batchUpdate 注意：清空后单元格 values 不可通过本节点恢复，请确认 range 无误。
批量读 Ranges	BatchGetGoogleSheetRanges	一次往返读多个 range，省时省 quota
批量写 Ranges	BatchUpdateGoogleSheetValues	一次往返写多个 range，强一致（要么全部成功要么全部失败）

节点参数与输出

连通性测试

• 节点标识： GoogleSheetsPing
• 节点说明： 用 OAuth2 refresh_token 换一次 access_token 验证凭据可用；若填了 spreadsheetId 还会额外读一次该表元信息验证表级权限
• XML 示例：

<GoogleSheetsPing connectionId="" outKey="pingResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL（可选）	url	string	否	-	可选：填了会额外做表级权限校验；不填只测 OAuth2 凭据
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
输出变量名	outKey	output	否	pingResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
pingResult	object	{ ok:true, data:{ connected:true, tokenType, expiresInSec, scope?, title? } }

获取 Spreadsheet 元信息

• 节点标识： GetGoogleSpreadsheetMeta
• 节点说明： 获取整个 spreadsheet 的元信息（标题 + 所有 sheet 的属性）
• XML 示例：

<GetGoogleSpreadsheetMeta connectionId="" url="" outKey="spreadsheet" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL	url	string	否	-	粘贴 docs.google.com/spreadsheets/d/{id}/edit 链接，或与 spreadsheetId 二选一
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
包含 cell 数据	includeGridData	boolean	否	-	false（默认，推荐）：只返回结构；true：返回每个 sheet 内所有 cell 数据（体积大，慎用）
输出变量名	outKey	output	否	spreadsheet
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
spreadsheet	object	{ ok:true, data:{ spreadsheetId, title, url, sheets:[{ sheetId, title, index, sheetType, rowCount, columnCount }], raw } }

列出所有 Sheet（tab）

• 节点标识： ListGoogleSpreadsheetSheets
• 节点说明： 列出 spreadsheet 下所有 sheet（tab）的属性
• XML 示例：

<ListGoogleSpreadsheetSheets connectionId="" url="" outKey="sheets" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL	url	string	否	-
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
输出变量名	outKey	output	否	sheets
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
sheets	object	{ ok:true, data:{ sheets:[{ sheetId, title, index, sheetType, rowCount, columnCount }], total } }

读取 Range

• 节点标识： GetGoogleSheetRange
• 节点说明： 按 A1 表示法读取一个 range 的数据。注意：末尾空行/空列会被裁剪
• XML 示例：

<GetGoogleSheetRange connectionId="" url="" range="Sheet1!A1:C10" outKey="rangeData" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL	url	string	否	-
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
Range（A1 表示法）	range	string	是	-	例：Sheet1!A1:C10 / ‘My Sheet’!A:A / Sheet1 (整个 sheet)。也可用 sheetName + a1 单独传
Sheet 名（可选）	sheetName	string	否	-	可选：与 a1 配合自动拼成 ‘SheetName’!a1，避免手动转义
A1 部分（可选）	a1	string	否	-	可选：与 sheetName 配合，例如 sheetName=Sheet1 + a1=A1:C10
value 渲染	valueRenderOption	select	否	FORMATTED_VALUE
日期时间渲染	dateTimeRenderOption	select	否	FORMATTED_STRING
主维度	majorDimension	select	否	ROWS
输出变量名	outKey	output	否	rangeData
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
rangeData	object	{ ok:true, data:{ range, values:[[..]], majorDimension, rowCount, colCount } }

覆盖写 Range

• 节点标识： SetGoogleSheetRange
• 节点说明： 覆盖写一个 range（不是 patch）。USER_ENTERED 模式下 ’=’ 开头会被当公式解析
• XML 示例：

<SetGoogleSheetRange connectionId="" url="" range="Sheet1!A1:B2" values="[[1,2],[3,4]]" outKey="updateResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL	url	string	否	-
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
Range	range	string	是	-	Sheet1!A1:B2
Sheet 名（可选）	sheetName	string	否	-
A1 部分（可选）	a1	string	否	-
二维数组 values（JSON）	values	textarea	是	[]	[[1, 2], [“hello”, “world”]]
输入模式	valueInputOption	select	否	USER_ENTERED
主维度	majorDimension	select	否	ROWS
输出变量名	outKey	output	否	updateResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
updateResult	object	{ ok:true, data:{ updatedRange, updatedRows, updatedColumns, updatedCells } }

追加行

• 节点标识： AppendGoogleSheetRow
• 节点说明： 在 range 内的最后一行非空之后追加新行。推荐 range 用 ‘Sheet1!A:Z’ 或 ‘Sheet1’
• XML 示例：

<AppendGoogleSheetRow connectionId="" url="" range="Sheet1!A:Z" values="[]" outKey="appendResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL	url	string	否	-
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
Range	range	string	是	-	推荐传一个覆盖整张表的宽 range（如 Sheet1!A:Z 或 Sheet1）。Google 会自动找到该 range 内最后一行非空，然后在它下面追加
Sheet 名（可选）	sheetName	string	否	-
A1 部分（可选）	a1	string	否	-
二维数组 values（JSON）	values	textarea	是	[]	[[“张三”, “待办”, “2024-01-15”]]
输入模式	valueInputOption	select	否	USER_ENTERED
插入策略	insertDataOption	select	否	INSERT_ROWS	INSERT_ROWS：插入会推下后续行；OVERWRITE：直接覆盖现有数据
输出变量名	outKey	output	否	appendResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
appendResult	object	{ ok:true, data:{ updatedRange, updatedRows, updatedColumns, updatedCells, tableRange? } }

清空 Range

• 节点标识： ClearGoogleSheetRange
• 节点说明： 清空 range 的 values（保留格式 / 数据校验等单元格属性）；如需删除行列结构请走 batchUpdate 注意：清空后单元格 values 不可通过本节点恢复，请确认 range 无误。
• XML 示例：

<ClearGoogleSheetRange connectionId="" url="" range="Sheet1!A2:Z" outKey="clearResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL	url	string	否	-
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
Range	range	string	是	-	Sheet1!A2:Z
Sheet 名（可选）	sheetName	string	否	-
A1 部分（可选）	a1	string	否	-
输出变量名	outKey	output	否	clearResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
clearResult	object	{ ok:true, data:{ clearedRange } }

批量读 Ranges

• 节点标识： BatchGetGoogleSheetRanges
• 节点说明： 一次往返读多个 range，省时省 quota
• XML 示例：

<BatchGetGoogleSheetRanges connectionId="" url="" ranges="[]" outKey="batchData" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL	url	string	否	-
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
Ranges（JSON 数组或逗号分隔）	ranges	textarea	是	[]	[“Sheet1!A1:B10”, “Sheet2!A1:Z1”]
value 渲染	valueRenderOption	select	否	FORMATTED_VALUE
日期时间渲染	dateTimeRenderOption	select	否	FORMATTED_STRING
主维度	majorDimension	select	否	ROWS
输出变量名	outKey	output	否	batchData
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
batchData	object	{ ok:true, data:{ valueRanges:[{ range, majorDimension, values }], total } }

批量写 Ranges

• 节点标识： BatchUpdateGoogleSheetValues
• 节点说明： 一次往返写多个 range，强一致（要么全部成功要么全部失败）
• XML 示例：

<BatchUpdateGoogleSheetValues connectionId="" url="" updates="[]" outKey="batchUpdateResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Google Sheets 连接	connectionId	connection	是	-
Spreadsheet URL	url	string	否	-
spreadsheetId（替代 URL）	spreadsheetId	string	否	-
更新项数组（JSON）	updates	textarea	是	[]	每项 { range:string, values:二维数组, majorDimension?:‘ROWS’|‘COLUMNS’ }
输入模式	valueInputOption	select	否	USER_ENTERED
输出变量名	outKey	output	否	batchUpdateResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
batchUpdateResult	object	{ ok:true, data:{ totalUpdatedRows, totalUpdatedColumns, totalUpdatedCells, totalUpdatedSheets, responses:[{ updatedRange, updatedRows, updatedColumns, updatedCells }] } }

成功标准

• 节点运行状态为成功。
• 输出变量中包含预期字段，且可被下游节点引用。
• 对外部系统有写入动作的节点，目标系统中的数据状态与配置一致。

失败排查

现象 / 报错	可能原因	处理建议
找不到插件分组	插件未安装、未加载或当前端不是桌面客户端	在「扩展能力」中刷新/重新扫描插件，必要时重启客户端。
连接或鉴权失败	连接配置缺失、令牌过期或权限不足	重新配置连接，确认账号具备对应资源权限。
查询结果为空	筛选条件过窄、目标资源为空或页面状态不正确	放宽条件，检查资源 ID、日期范围和页面登录态。
写入类操作失败	参数格式不符合平台要求或目标资源不可写	先用少量测试数据验证，再检查必填字段、ID 和权限。

相关说明

• 插件能力由桌面端扩展能力机制加载，和普通后端指令树不是同一数据源。
• 插件页按插件维度整理；每个节点的帮助入口会跳到所属插件页，页面内可查节点标识、参数和输出。