此页面由 Cloud Translation API 翻译。

从 Sheets API v3 迁移

如果您有基于 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 将特定电子表格中的工作表称为“工作表”。这与 v4 API 使用的“工作表”一词同义。

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

v3 API 还会为使用其 list 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

如果您的应用不需要修改用户的电子表格或电子表格属性，请使用只读范围。如果应用不需要常规的 Google 云端硬盘访问权限，请使用电子表格范围，而不是 Google 云端硬盘范围。

公开范围

在旧版 API 中，公开范围一词用于指代指定电子表格的可用性。

v3 API

Sheets API v3 直接在其端点中表达了可见性。public 电子表格已“发布到网络”，因此 API 可以未经授权访问该电子表格，而 private 电子表格则需要进行身份验证。公开范围在端点中指定，位于电子表格 ID 之后：

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

v4 API

在新的 Google 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 来选择电子表格。

在需要列出电子表格的情况下，可以使用 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 方法可用于获取工作表属性和其他元数据，远超使用 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 请求的正文发送到编辑网址。例如：

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: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"]]
}

检索整行、整列或整个工作表时，响应中不包含末尾的空单元格。

Google 表格 API v4 没有与 Google 表格 API v3 提供的行顺序查询参数等效的参数。反向排序非常简单；只需按相反顺序处理返回的 values 数组即可。读取操作不支持按列排序，但可以先使用 SortRange 请求对工作表中的数据进行排序，然后再读取数据。

Google 表格 API v4 目前没有与 Google 表格 API v3 结构化查询直接对应的功能。不过，您可以在应用中检索相关数据并根据需要对其进行排序。

添加新的数据行

您可以使用任一 API 向工作表中添加新的数据行。

v3 API

如需确定指定工作表的基于列表的 Feed 的网址，请检索工作表 Feed，然后在所需的工作表条目中找到帖子网址。

如需添加一行数据，请使用适当的授权标头向 POST 网址发送 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"]]
}

此外，您还可以使用 spreadsheets.batchUpdate 中的 AppendCells 请求，在工作表中附加具有特定属性和格式的单元格。

使用新数据修改行

这两个 API 都允许使用新值更新行数据。

v3 API

如需修改某行数据，请检查列表 Feed，找到要更新的行的条目。根据需要更新相应条目的内容。请确保您使用的条目中的 ID 值与现有条目的 ID 完全一致。

更新条目后，使用适当的授权标头，向相应行条目中提供的 edit 网址发送以该条目作为请求正文的 PUT 请求。例如：

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 方法更新行数据；如果您要进行多项行或单元格更新，使用此方法会更高效。

此外，您还可以使用 spreadsheets.batchUpdate 中的 UpdateCells 或 RepeatCell 请求，通过 Sheets API v4 修改单元格的属性和格式。

删除行

这两个 API 都支持删除行。删除的行会从电子表格中移除，其下方的行会向上移动一行。

v3 API

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

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

如果您想确保不会删除自您检索某行以来被其他客户端更改过的该行，请添加一个包含原始行 ETag 值的 HTTP If-Match 标头。您可以通过检查条目元素的 gd:etag 属性来确定原始行的 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
        }
      }
    }
  ],
}

可以使用 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=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”中从第 2 行开始的 D 列中的单元格，并按输入时的格式返回公式（省略末尾的空单元格）：

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 中找到相应单元格的条目。相应条目包含修改网址。更新条目以反映您希望单元格包含的内容，然后向修改网址发出 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 查询参数，用于指定输入数据是像在 Google 表格界面中输入的那样进行处理 (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 会返回错误。

从 Sheets API v3 迁移 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

符号和术语

向请求授权

v3 API

v4 API

公开范围

v3 API

v4 API

投影

v3 API

v4 API

创建电子表格

v3 API

v4 API

列出经过身份验证的用户的电子表格

v3 API

v4 API

检索工作表的元数据

v3 API

v4 API

向电子表格添加工作表

v3 API

v4 API

更改工作表的标题和大小

v3 API

v4 API

删除工作表

v3 API

v4 API

检索行数据

v3 API

v4 API

添加新的数据行

v3 API

v4 API

使用新数据修改行

v3 API

v4 API

删除行

v3 API

v4 API

检索单元格数据

v3 API

v4 API

修改单元格

v3 API

v4 API

通过批量请求修改多个单元格

v3 API

v4 API

从 Sheets API v3 迁移