Google Sheets API 概览
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
Google Sheets API 是一个 RESTful 接口,可让您读取和修改电子表格的数据。通过 Sheets API,您可以:
- 创建电子表格
- 读取和写入电子表格单元格值
- 更新电子表格格式
- 管理“关联工作表”
以下是 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
是指 Sheet1 中前两行和前两列的所有单元格。
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
资源表示受保护的范围。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-29。
[null,null,["最后更新时间 (UTC):2025-08-29。"],[],[],null,["# Google Sheets API Overview\n\nThe Google Sheets API is a RESTful interface that lets you read and modify a\nspreadsheet's data. The Sheets API lets you:\n\n- Create spreadsheets\n- Read and write spreadsheet cell values\n- Update spreadsheet formatting\n- Manage Connected Sheets\n\nThe following is a list of common terms used in the Sheets API:\n\n*Spreadsheet*\n\n: The primary object in Google Sheets. It can contain multiple `Sheets`, each\n with structured information contained in `Cells`. The\n [`spreadsheets`](/workspace/sheets/api/reference/rest/v4/spreadsheets)\n resource represents a spreadsheet. It contains a unique `spreadsheetId`\n value.\n\n *Spreadsheet ID*\n : The unique identifier for a spreadsheet. It's a particular string\n containing letters, numbers, and some special characters that reference a\n spreadsheet and it can be derived from the spreadsheet's URL. Spreadsheet\n IDs are stable, even if the spreadsheet name changes. \n\n https://docs.google.com/spreadsheets/d/\u003cvar translate=\"no\"\u003eSPREADSHEET_ID\u003c/var\u003e/edit?gid=\u003cvar translate=\"no\"\u003eSHEET_ID\u003c/var\u003e#gid=\u003cvar translate=\"no\"\u003eSHEET_ID\u003c/var\u003e\n\n*Sheet*\n\n: A page or tab within a spreadsheet. The\n [`Sheets`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets) resource\n represents a sheet. It contains a unique numeric `sheetId` value and sheet\n `title` as part of the\n [`SheetProperties`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#sheetproperties)\n object.\n\n *Sheet ID*\n : The unique identifier for a specific sheet within a spreadsheet. It's a\n particular integer containing numbers that reference a sheet and it can be\n derived from the spreadsheet's URL. Sheet IDs are stable, even if the sheet\n name changes. For an example, see [Spreadsheet ID](#spreadsheet-id).\n\n*Cell*\n\n: An individual field of text or data within a sheet. Cells are arranged in rows\n and columns, and can be grouped as a range of cells. The\n [`Cells`](/workspace/sheets/api/reference/rest/v4/spreadsheets/cells)\n resource represents each cell, but it doesn't have a unique ID value.\n Instead, row and column coordinates identify the cells.\n\n *A1 notation*\n : A syntax used to define a cell or range of cells with a string that\n contains the sheet name plus the starting and ending cell coordinates using\n column letters and row numbers. This method is the most common and useful\n when referencing an absolute range of cells.\n - `Sheet1!A1:B2` refers to all the cells in the first two rows and columns of Sheet1.\n - `Sheet1!A:A` refers to all the cells in the first column of Sheet1.\n - `Sheet1!1:2` refers to all the cells in the first two rows of Sheet1.\n - `Sheet1!A5:A` refers to all the cells of the first column of Sheet 1, from row 5 onward.\n - `A1:B2` refers to all the cells in the first two rows and columns of the first visible sheet.\n - `Sheet1` refers to all the cells in Sheet1.\n - `'Jon's_Data'!A1:D5` refers to all the cells in the first five rows and four columns of a sheet named \"Jon's_Data.\"\n - `'My Custom Sheet'!A:A` refers to all the cells in the first column of a sheet named \"My Custom Sheet.\"\n - `'My Custom Sheet'` refers to all the cells in \"My Custom Sheet\".\n\n Single quotes are required for sheet names with spaces or special characters.\n\n **Tip** : Where possible, use distinct names for objects in your spreadsheets. For example, A1 (without quotes) refers to cell A1 in the first visible sheet. `'A1'` refers to a sheet with the name A1. Similarly, Sheet1 refers to a sheet with the name Sheet1. However, if there's a named range titled \"Sheet1\", then Sheet1 refers to the named range and `'Sheet1'` refers to the sheet.\n\n *R1C1 notation*\n : A syntax used to define a cell or range of cells with a string that\n contains the sheet name plus the starting and ending cell coordinates using\n row numbers and column numbers. This method is less common than A1 notation,\n but can be useful when referencing a range of cells relative to a given\n cell's position.\n - `Sheet1!R1C1:R2C2` refers to the first two cells in the top two rows of Sheet1.\n - `R1C1:R2C2` refers to the first two cells in the top two rows of the first visible sheet.\n - `Sheet1!R[3]C[1]` refers to the cell that is three rows below and one column to the right of the current cell.\n\n *Named range*\n : A defined cell or range of cells with a custom name to simplify references\n throughout an application. A\n [`FilterView`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#filterview)\n resource represents a named range.\n\n *Protected range*\n : A defined cell or range of cells that cannot be modified. A\n [`ProtectedRange`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#protectedrange)\n resource represents a protected range.\n\nRelated topics\n--------------\n\n- To learn about developing with Google Workspace APIs, including handling\n authentication and authorization, refer to [Develop on\n Google Workspace](/workspace/guides/get-started).\n\n- To learn how to configure and run a Sheets API app, try the\n [JavaScript quickstart](/workspace/sheets/api/quickstart/js)."]]