此页面由 Cloud Translation API 翻译。

从 Sheets API v3 迁移

如果您有基于 Google Sheets API v3 的现有应用，您可以迁移到 Google Sheets API v4。v4 版本基于 JSON，更易于使用并且增加了大量我们不可能实现的功能，。

此页面介绍了较旧的 Sheets API v3 命令及其 Sheets API v4 中等效的操作。映射主要侧重于 spreadsheets.values 这一集合，提供直接的单元格读写功能。其他方面（例如添加工作表或更新工作表属性）则由电子表格集合。请注意，v4 API 的 JSON 结构不向后兼容 v3 中使用的 XML 结构。

如需详细了解 Sheets v4 API 中的可用资源，请参阅 API 参考文档。

表示法和术语

v3 API 将特定电子表格中的工作表称为“工作表”。它等同于“表格”与 v4 API 使用的相同

API 通常需要您指定电子表格 ID 您正在使用的电子表格中它们通常还需要工作表。这些值要么作为 API 端点的一部分显示，网址、查询参数或请求正文的一部分。在本页中，占位符 spreadsheetId 和 sheetId 分别指电子表格 ID 和工作表 ID。使用方法时请替换为这些位置的实际 ID。

v3 API 还会为使用其属性检索到的行分配 ID。列表 Feed；在这个页面中用 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 使用术语“投影”来指代数据集（全部或某个固定子集）定义。Sheets API v4 不使用投影；相反，它可以更好地控制返回的数据。

v3 版 API

在 Sheets API v3 中，只有两种可能的投影设置。full projection 会返回所有可用信息，而 basic 会返回较小的固定数据子集（适用于工作表、列表 Feed 和单元格 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 选择器。

如果需要列出电子表格，则可以复制通过 Drive API Files.list 方法使用 mimeType 查询：

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

可以从此 API 端点访问工作表 Feed（使用相应的授权标头）：

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 方法可用于获取工作表属性和其他元数据，。如果您仅想要读取工作表属性，请设置 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

您可以通过添加 AddSheet （在 spreadsheets.batchUpdate 中）方法。作为请求正文的一部分，您可以指定以下操作的工作表属性：新工作表；所有属性都是可选的提供标题。

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 请求的正文发送附加到修改网址。例如：

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

要更新大小、标题和其他工作表属性， updateSheetProperties 请求的 spreadsheets.batchUpdate 方法。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

要删除工作表，请将 DeleteSheet 请求的 spreadsheets.batchUpdate 方法。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:lastname

利用 Sheets API v3，您还可以使用结构化查询（通过列标题引用）：

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?sq=age>25%20and%20height<175

v4 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 没有与行顺序查询等效的功能。颠倒顺序无关紧要；简单以反向顺序处理返回的 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 请求的正文应包含要接收的行数据的条目 add（通过列标题引用各个单元格）：

<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，您还可以在单元格中附加特定使用 AppendCells 请求数量 spreadsheets.batchUpdate.

修改包含新数据的行

这两个 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 修改单元格属性和使用 UpdateCells 或 RepeatCell 请求数量 spreadsheets.batchUpdate.

删除行

两个 API 都支持删除行。已删除的行会从而其下方的行会上移一行。

v3 版 API

要删除行，请先从列表 Feed，然后向该行的条目中提供的 edit 网址发送 DELETE 请求。此网址与用于更新行的网址相同。

DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version

如果要确保不要删除已更改的行由其他客户端自您检索后发送，添加 HTTP If-Match 标头包含原始行的 ETag 值。您可以确定原始行的 ETag 值，方法是检查条目元素的 gd:etag 属性。

如果您想删除行，而不管其他人是否已更新之后，请使用 If-Match: * 并且不要包含 ETag。（在这种情况下，在删除行之前无需对其进行检索。）

v4 API

使用 Sheets API v4 删除行的操作由 spreadsheet.batchUpdate 处理。方法调用，使用 DeleteDimension 请求。此请求也可用于移除列，开发者也可以并选择仅移除行或列的部分内容。例如，以下转换将移除具有指定 ID 的工作表中的第 6 行（行索引从零开始，包括 startIndex，但不包含 endIndex）：

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": sheetId,
          "dimension": "ROWS",
          "startIndex": 5,
          "endIndex": 6
        }
      }
    }
  ],
}

工作表的 sheetId 可以使用 spreadsheet.get方法。

检索单元格数据

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=4

Sheets 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 中，您可以通过发出 PUT 命令来修改单元格的内容，将修改后的单元格条目作为请求正文的单元格 Feed。

相比之下，Sheets API v4 可以提供 spreadsheets.values.update 和 spreadsheets.values.batchUpdate 更改单元格内容的方法。

v3 版 API

要编辑单个单元格的内容，请先在。条目包含 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 会返回错误。