Google Sheets API 概览

能抽出 5 分钟时间吗？
烦请填写简短的在线调查问卷，帮助我们改进 Google Workspace 文档。

Google Sheets API 是一个 RESTful 接口，可让您读取和修改电子表格的数据。通过 Sheets API，您可以：

  • 创建电子表格
  • 读取和写入电子表格单元格值
  • 更新电子表格格式
  • 管理“关联工作表”

以下是 Google Sheets API 中使用的常见术语列表：

电子表格

Google 表格中的主要对象。它可以包含多个 Sheets，每个 Sheets 都具有包含在 Cells 中的结构化信息。spreadsheets 资源表示电子表格。它包含唯一的 spreadsheetId 值。

电子表格 ID
电子表格的唯一标识符。它是一个包含字母、数字和一些特殊字符的特定字符串，用于引用电子表格，并且可以从电子表格的网址中派生出来。即使电子表格名称发生更改，电子表格 ID 也不会发生变化。
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit?gid=SHEET_ID#gid=SHEET_ID
工作表

电子表格中的页面或标签页。Sheets 资源表示工作表。它包含唯一的数值 sheetId 值和工作表 title，作为 SheetProperties 对象的一部分。

工作表 ID
电子表格中特定工作表的唯一标识符。它是一个特定的整数，包含引用工作表的数字，可以从电子表格的网址中派生出来。即使工作表名称发生变化，工作表 ID 也保持不变。如需查看示例，请参阅电子表格 ID。
单元格

工作表中的单个文本字段或数据字段。单元格按行和列排列，可以组合成一个单元格范围。Cells 资源表示每个单元格，但它没有唯一的 ID 值。而是使用行和列坐标来标识单元格。

A1 表示法
一种用于定义单元格或单元格范围的语法，使用包含工作表名称以及起始和结束单元格坐标（使用列字母和行号）的字符串。在引用绝对单元格范围时，此方法最常用且最实用。
  • Sheet1!A1:B2 是指工作表 1 中前两行和前两列的所有单元格。
  • Sheet1!A:A 指的是 Sheet1 中第一列的所有单元格。
  • Sheet1!1:2 是指工作表 1 中前两行的所有单元格。
  • Sheet1!A5:A 指的是工作表 1 中第一列从第 5 行开始的所有单元格。
  • A1:B2 是指第一个可见工作表的前两行和前两列中的所有单元格。
  • Sheet1 是指工作表 1 中的所有单元格。
  • 'Jon's_Data'!A1:D5 指的是名为“Jon's_Data”的工作表的前五行和前四列中的所有单元格。
  • 'My Custom Sheet'!A:A 是指名为“My Custom Sheet”的工作表中第一列的所有单元格。
  • 'My Custom Sheet' 指的是“我的自定义工作表”中的所有单元格。

对于包含空格或特殊字符的工作表名称，必须使用英文单引号。

提示：尽可能为电子表格中的对象使用不同的名称。例如，A1（不带引号）是指第一个可见工作表中的 A1 单元格。'A1' 是指名称为 A1 的工作表。同样，Sheet1 是指名称为 Sheet1 的工作表。不过，如果存在名为“Sheet1”的命名范围，则 Sheet1 指的是该命名范围，而 'Sheet1' 指的是工作表。

R1C1 表示法
一种用于通过包含工作表名称以及使用行号和列号的起始和结束单元格坐标的字符串来定义单元格或单元格范围的语法。这种方法不如 A1 标记法常见，但在引用相对于给定单元格位置的单元格范围时非常有用。
  • Sheet1!R1C1:R2C2 是指工作表 1 中前两行的前两个单元格。
  • R1C1:R2C2 是指第一个可见工作表的前两行中的前两个单元格。
  • Sheet1!R[3]C[1] 指的是当前单元格下方三行、右侧一列的单元格。
命名范围
具有自定义名称的已定义单元格或单元格范围，用于简化整个应用中的引用。FilterView 资源表示一个命名范围。
受保护的范围
无法修改的指定单元格或单元格范围。ProtectedRange 资源表示受保护的范围。