如果您现有的应用基于 Google Sheets API v3，则可以迁移至 Google Sheets API v4。v4 版本基于 JSON，拥有更易于使用的接口，并且添加了大量无法在 v3 版本中实现的功能。
本页面提供了较旧的 Sheets API v3 命令与其 Sheets API v4 对等操作的映射。映射主要侧重于 spreadsheets.values 集合，此集合提供了单元格直接读取和写入功能。其他方面（例如添加工作表或更新工作表属性）则由 spreadsheets 集合处理。请注意，v4 API 的 JSON 结构与 v3 中使用的 XML 结构不向后兼容。
如需详细了解 Sheets v4 API 中可用资源，请参阅 API 参考文档。
符号和术语
v3 API 将特定电子表格中的工作表称为“worksheets”。 它与 v4 API 使用的术语“sheets”属于同义词。
API 经常需要您指定正在操作的电子表格的电子表格 ID。它们也经常需要正在操作的工作表的 ID。这些值显示在 API 端点网址、查询参数或请求正文中。在本页中，占位符 spreadsheetId 和 sheetId 分别指电子表格 ID 和工作表 ID。在使用本页面介绍的方法时，请在这些位置替换为实际 ID。
v3 API 也会向使用列表 Feed 检索的行分配 ID；在本页面中，此 ID 使用 rowId 占位符表示。
向请求授权
在您的应用运行时，它会要求用户授予特定权限；您在应用中指定的作用域确定它要求的权限。
v3 API
Sheets API v3 采用单个授权作用域：
https://spreadsheets.google.com/feeds
它是以下网址的别名：
https://www.googleapis.com/auth/spreadsheets
可以使用任何一种作用域格式。
v4 API
Sheets API v4 采用下列一个或多个作用域集：
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
如果您的应用不需要对用户的工作表或工作表属性进行编辑，请使用只读作用域。如果应用不需要一般性云端硬盘访问权限，请使用电子表格作用域，而非云端硬盘作用域。
公开范围
在旧版 API 中，术语可见性用于表示给定电子表格的可用性。
v3 API
Sheets API v3 直接在其端点中表示可见性。public 电子表格已被“发布到网络”，因此不需要授权就可以通过 API 获取，而 private 电子表格则需要进行身份验证。可见性在电子表格 ID 后的端点中指定：
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
v4 API
在新的 Sheets API v4 中，没有对可见性进行显式声明。API 调用使用电子表格 ID 发起。如果应用不具备访问指定电子表格的权限，则会返回错误。否则，调用将继续。
投影
Sheets API v3 使用术语投影指示给定 API 调用返回的数据集，可以是全部数据，也可以是 API 定义的固定子集。Sheets API v4 不使用投影；不过，它允许您对返回的数据进行更多控制。
v3 API
Sheets API v3 中只有两种可能的投影设置。full 投影会返回所有可用信息，而 basic 仅会（为工作表、列表和单元格 Feed）返回一个较小的固定数据子集。与可见性一样，投影也必须在 API 端点中指定（在可见性设置之后）：
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
basic 投影提供的较小的数据子集可以让代码更加高效，但是无法自定义。
v4 API
尽管 Sheets API v4 可以返回完整数据集，但它不会定义与 Sheets API v3 中的 basic 可见性设置相似的固定子集。电子表格集合中的函数通过使用 fields 查询参数限制了它们所返回的数据量。
例如，下面的查询仅会返回特定电子表格中所有工作表的标题：
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
创建电子表格
v3 API
Sheets API v3 未提供创建新电子表格的方式；不过，可以使用 Drive API Files.create 方法创建新的电子表格文件。这需要应用声明 https://www.googleapis.com/auth/drive 作用域。
v4 API
Drive API Files.create 方法也可与 Sheets API v4 搭配使用，不过需要应用提供 https://www.googleapis.com/auth/drive 作用域。
作为等效替代，Sheets API v4 提供了一种 spreadsheets.create 方法，此方法也可以根据需要添加工作表、设置电子表格和工作表属性，以及添加命名范围。例如，下面的请求会创建一个新的电子表格并将其命名为“NewTitle”：
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}为已通过身份验证的用户列出电子表格
v3 API
Sheets API v3 Feed 允许应用检索已通过身份验证的用户可以获取的所有电子表格的列表。电子表格 Feed 端点为：
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
v4 API
Sheets API v4 未提供这种特定的操作。我们建议您迁移应用，以便将 drive.file 作用域与 Google Picker 结合使用来选择电子表格。
如果需要列出电子表格，可以使用 mimeType 查询通过 Drive API Files.list 方法实现此操作：
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'如需使用 Drive API files.list 方法列出用户的所有电子表格，您需要使用受限作用域。
检索工作表元数据
Sheets API v3 提供了一个 Feed 来获取给定电子表格中包含的工作表元数据（行数据和单元格数据通过一个单独的 Feed 获取）。元数据包含工作表标题和大小等信息。
Sheets API v4 spreadsheets.get 方法提供了对此信息及其他多种信息的访问。
v3 API
工作表 Feed 可以从此 API 端点获取（使用相应的授权标头）：
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
此请求的响应结构类似于如下，其中每个工作表的数据包含在单独的 <entry> 中：
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
v4 API
可以使用 spreadsheets.get 方法获取工作表属性和其他元数据，远远多于使用 Sheets API v3 可以获取的数据。如果您仅希望读取工作表属性，请将 includeGridData 查询参数设为 false，以免包含电子表格单元格数据：
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Spreadsheet 响应包含一组 Sheet 对象；可以在这些对象的 SheetProperties 元素下找到工作表标题和大小信息。例如：
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}向电子表格添加工作表
两个版本的 API 都允许您向现有电子表格添加新工作表。
v3 API
Sheets API v3 可以通过发起以下（经过身份验证的）POST 请求向电子表格添加新的工作表。您可以指定新工作表的大小：
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
v4 API
您可以通过在 spreadsheets.batchUpdate 方法中发起 AddSheet 请求的方式添加新工作表。您可以在请求正文中为新工作表指定工作表属性；所有属性均为可选项。提供一个已被现有工作表使用的标题将引发错误。
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}更改工作表标题和大小
利用 Sheets API v3，您可以更新工作表标题和大小；Sheets API v4 也允许这种操作，不过还可用于更新其他工作表属性。请注意，减小工作表的大小可能导致将被裁剪单元格中的数据删除，并且不会出现警告。
v3 API
如需更改工作表的标题或大小，请先检索工作表 Feed，然后查找所需的工作表条目，其中包含 edit 网址。更新工作表的元数据，并以 PUT 请求正文的形式将其发送到 edit 网址。例如：
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
v4 API
如需更新大小、标题和其他工作表属性，请在 spreadsheets.batchUpdate 方法中发出 updateSheetProperties 请求。POST 请求正文应包含要更改的属性，fields 参数应明确列出这些属性（如果您希望更新所有属性，为简便起见，请使用 fields:"*" 将其全部列出）。例如，下面的请求将指定应为具有给定 ID 的工作表更新工作表标题和大小属性：
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"updateSheetProperties": {
"properties": {
"sheetId": sheetId,
"title": "Expenses",
"gridProperties": {
"rowCount": 45,
"columnCount": 15,
}
},
"fields": "title,gridProperties(rowCount,columnCount)"
}
}
],
}如需检索工作表的 sheetId，请使用电子表格 spreadsheets.get 方法。
删除工作表
这两个版本的 API 都可以从给定电子表格中移除工作表。
v3 API
如需删除工作表，请先检索工作表 Feed，然后在目标工作表条目的 edit 网址上发送 DELETE 请求。
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
v4 API
如需删除工作表，请在 spreadsheets.batchUpdate 方法中发出 DeleteSheet 请求。POST 请求正文仅应包含要删除的工作表的 sheetId。例如：
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}如需检索各个工作表的 sheetId，请使用电子表格 spreadsheets.get 方法。
检索行数据
列表行 Feed 是 Sheets API v3 用来获取电子表格单元格中数据的两种方法之一（另一种方法为单元格 Feed）。行 Feed 支持常用的电子表格操作（逐行读取、追加行、排序），不过它所作的一些假设使其不适合某些任务。具体而言，列表 Feed 假设空行为 Feed 终止，以及强制性标题存在于工作表的第一行中。
相比之下，Sheets API v4 不使用行特定的获取函数。此版本获取工作表单元格数据的方式为使用 A1 表示法 引用所需的特定范围。范围可以是单元格块、整行、整列或整个工作表。API 也可以获取不相连的单元格集。
v3 API
如需确定给定工作表列表 Feed 的网址，请检索工作表 Feed，然后在目标工作表条目中查找列表 Feed 网址。
如需检索基于列表的 Feed，请使用相应的授权标头向列表 Feed 网址发送 GET 请求。例如：
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
除了其他内容外，此请求的响应还包含与特定行对应的条目。各个单元格均通过（强制性）工作表标题行中提供的名称引用。例如，下面是一个单行条目：
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>10</gsx:hours>
<gsx:items>2</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
默认情况下，列表 Feed 中返回的行按行顺序返回。Sheets API v3 提供了可以更改该顺序的查询参数。
反向顺序：
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
按特定列排序：
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastnameSheets API v3 还可以通过结构化查询（由列标题引用）对特定行进行过滤：
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175v4 API
利用 Sheets API v4，您可以通过 spreadsheets.values.get 或 spreadsheets.values.batchGet 方法按范围检索行。例如，下面的请求将返回“Sheet1”中的所有行：
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
此请求的响应结构类似于如下：
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}如果检索整行、整列或整个工作表，尾部空单元格将不包含在响应中。
Sheets API v4 没有提供与 Sheets API v3 中的 row-order 查询参数对应的功能。颠倒顺序无关紧要；只需以倒序处理返回的 values 数组即可。按列排序不适用于读取，不过可以先在工作表请求中对数据进行排序（使用 SortRange），然后再读取数据。
Sheets API v4 目前没有提供直接对应于 Sheets API v3 结构化查询的功能。不过，您可以检索相关数据，并在应用中根据需要对其进行排序。
添加一行新数据
您可以使用任一 API 向工作表添加一行新数据。
v3 API
如需确定给定工作表列表 Feed 的网址，请检索工作表 Feed 并在目标工作表条目中查找发布网址。
如需添加一行数据，请使用相应的授权标头向发布网址发送 POST 请求。例如：
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
POST 请求的正文应包含要添加的行数据的条目，其中各个单元格通过列标题引用：
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
新行将追加到指定工作表的结尾。
v4 API
利用 Sheets API v4，您可以使用 spreadsheets.values.append 方法追加行。以下示例会将一行新数据写入电子表格的“Sheet1”工作表中最后一个表格下方。
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}此外，利用 Sheets API v4，您还可以在 spreadsheets.batchUpdate 中使用 AppendCells 请求追加具有特定属性和格式设置的单元格。
使用新数据编辑行
这两个 API 都允许使用新值更新行数据。
v3 API
如需修改一行数据，请检查列表 Feed 以定位要更新的行的条目。根据需要更新该条目的内容。确保所用条目中的 ID 值完全匹配现有条目的 ID。
更新条目后，请使用相应的授权标头，以请求正文的形式将包含该条目的 PUT 请求发送到该行条目中提供的 edit 网址。例如：
PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>20</gsx:hours>
<gsx:items>4</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
v4 API
利用 Sheets API v4，您可以使用想要编辑的行的 A1 表示法并发起 spreadsheets.values.update 请求以替换该行，通过这种方式对行进行编辑。指定的范围只需要引用行中的第一个单元格；API 将引导单元格根据请求提供的值更新。如果您指定一个包含多个单元格的范围，您提供的值必须适合该范围；否则，API 将返回错误。
下面的示例请求和请求正文会将数据添加到“Sheet1”的第四行：
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}您也可以通过 spreadsheet.values.batchUpdate 方法更新行数据；如果您要更新多个行或单元格，那么使用这种方法会更加高效。
此外，利用 Sheets API v4，您还可以在 spreadsheets.batchUpdate 中使用 UpdateCells 或 RepeatCell 请求，对单元格属性和单元格的格式设置进行编辑。
删除行
这两个版本的 API 都支持删除行。已删除的行将从电子表格中移除，原来在此行下方的行将向上移动一行。
v3 API
如需删除行，请先从列表 Feed 检索要删除的行，然后向行条目中提供的 edit 网址发送 DELETE 请求。此网址与用于更新行的网址相同。
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
如果希望确保不会删除自您检索以来已被另一个客户端更改的行，请包含一个 HTTP If-Match 标头，该标头包含原始行的 ETag 值。您可以通过检查条目元素的 gd:etag 属性确定原始行的 ETag 值。
如果您希望删除行，而不管其他人自您检索以来有没有更新过，请使用 If-Match: * 并且不要包含 ETag。（在这种情况下，您在删除行之前不需要对其进行检索。）
v4 API
Sheets API v4 通过在 spreadsheet.batchUpdate 方法调用中发起 DeleteDimension 请求的方式实现删除行的操作。此请求也可以用于移除列，开发者可以选择仅移除一行或者一列中的一部分。例如，下面的请求将移除具有给定 ID 的工作表的第 6 行（行索引从 0 开始，包括 startIndex，但不包括 endIndex）：
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}您可以使用 spreadsheet.get 方法检索工作表的 sheetId。
检索单元格数据
Sheets API v3 提供了一个单元格 Feed，用于对电子表格中存储的所有数据进行基本获取。对于读取操作，单元格 Feed 可以提供整个工作表内容或由一组查询参数定义的工作表单元格组成的范围，不过仅以单个块的形式提供；不相连的范围必须使用其他 GET 请求单独检索。
Sheets API v4 可以从工作表检索任意的单元格数据集（包括多个不相连的范围）。Sheets API v3 仅能将单元格内容返回为输入值（由用户通过键盘输入）和/或公式的输出（如果为数值）；Sheets API v4 可以完全获取值、公式、格式设置、超链接、数据验证和其他属性。
v3 API
如需确定给定工作表基于单元格的 Feed 的网址，请检查工作表 Feed，并在目标工作表条目中查找单元格 Feed 网址。
如需检索基于单元格的 Feed，请使用相应的授权标头向单元格 Feed 网址发送 GET 请求。例如：
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
单元格通过行号和列号引用。可以使用 max-row、min-row、max-col 和 min-col 查询参数提取一个特定范围。例如，下面的请求将检索第 4 (D) 列中从第 2 行开始的所有单元格：
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4Sheets API v3 可以返回已检索单元格的 inputValue，此值为用户键入 Google 表格界面中用来操作单元格的值。inputValue 可以是字面量值或公式。API 有时也会返回 numericValue；例如，如果公式的计算结果为数字时就会如此。例如，响应可能包含结构类似于如下的单元格条目：
<entry gd:etag='"ImB5CBYSRCp7"'>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
<updated>2006-11-17T18:27:32.543Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#cell"/>
<title type="text">D4</title>
<content type="text">5</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
<gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
numericValue="5.0">5</gs:cell>
</entry>
v4 API
分别为一个目标范围或多个目标范围调用 spreadsheets.values.get 或 spreadsheets.values.batchGet 方法，通过这种方式检索单元格数据。例如，下面的请求将返回“Sheet2”的 D 列中从第 2 行开始的单元格，采用以列为主的顺序并按输入原样返回公式（拖尾的空单元格将被忽略）：
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
此请求的响应结构类似于如下：
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}如果您想要检索多个范围的单元格数据，那么使用 spreadsheet.values.batchGet 会更加高效。如果您希望获取单元格属性（例如格式设置），则需要使用 spreadsheet.get 方法。
修改单元格
在 Sheets API v3 中，以请求正文的形式向带有已修改单元格条目的单元格 Feed 发出 PUT 命令可以编辑单元格内容。
相比之下，Sheets API v4 提供了 spreadsheets.values.update 和 spreadsheets.values.batchUpdate 方法来更改单元格内容。
v3 API
如需修改单个单元格的内容，请先在单元格 Feed 中查找该单元格的条目。条目包含一个 edit 网址。更新条目以反映您希望单元格具有的内容，然后以请求正文的形式向带有已更新单元格条目的 edit 网址发起 PUT 请求。例如，下面的请求会更新单元格 D2 (R2C4)，使其包含一个 SUM 公式：
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
v4 API
在 Sheets API v4 中，可以使用 spreadsheets.values.update 方法完成单个单元格编辑。此方法需要一个 ValueInputOption 查询参数，此参数指定将输入数据视为输入表格界面 (USER_ENTERED) 还是未解析并以原样 (RAW) 获取。例如，下面的请求将通过一个公式更新单元格 D2：
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}如果您要编辑多个单元格，请使用 spreadsheets.values.batchUpdate 方法在一个请求中发出所有编辑操作。
通过批处理请求编辑多个单元格
两个版本的 API 都提供了在一个（批处理）请求中对多个单元格的内容进行更改的方式。批处理请求引用的单元格不需要处于一个连续范围中。
如果批处理中的一个或多个单元格编辑失败，Sheets API v3 会允许其他编辑成功。不过，如果批处理更新中的任何一个失败，Sheets API v4 将返回错误，并且在该情况下不会应用任何更新。
v3 API
如需编辑多个单元格，请先检索工作表的单元格 Feed。条目包含批处理网址。向此网址发送一个 POST 请求，并包含说明您希望更新的单元格及新单元格内容的请求正文。POST 请求和请求正文的结构类似于如下：
POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
<entry>
<batch:id>request1</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
<gs:cell row="2" col="4" inputValue="newData"/>
</entry>
...
<entry>
<batch:id>request2</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
<gs:cell row="5" col="2" inputValue="moreInfo"/>
</entry>
</feed>
batch:id 字段应在批处理内对请求进行唯一标识。对于单元格编辑来说，batch:operation 字段应为 update。gs:cell 按行号和列号标识单元格，并提供要插入其中的新数据。id 包含指向要更新的单元格的完整网址。link 必须具有 href 属性，该属性包含单元格 ID 的完整路径。每个条目都需要所有这些字段。
v4 API
Sheets API v4 通过 spreadsheets.values.batchUpdate 方法对单元格值进行批量编辑。
发起 POST 请求并在请求正文中指定数据更改，通过这种方式可以编辑多个单元格。例如：
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
"valueInputOption": "USER_ENTERED"
"data": [
{"range": "D4",
"majorDimension": "ROWS",
"values": [["newData"]]
},
{"range": "B5",
"majorDimension": "ROWS",
"values": [["moreInfo"]]
}
]
}如果您将一个单元格指定为范围，则提供的所有值都将写入工作表，并将该单元格作为左上角坐标。如果改为指定一个包含多个单元格的范围，您提供的值必须精确匹配该范围；否则，API 将返回错误。