从 Sheets API v3 迁移

如果您有基于 Google 表格 API v3 的应用,则可以迁移到 Google 表格 API v4。v4 版本基于 JSON,具有更易于使用的界面,并添加了 v3 版本中无法实现的大量功能。

本页面介绍了旧版的 Sheets API v3 命令与其在 Sheet API v4 中的同等操作之间的对应关系。映射主要侧重于 spreadsheets.values 集合,该集合提供了单元格直接读取和写入功能。其他方面(如添加工作表或更新工作表属性)则由 spreadsheets 集合处理。请注意,v4 API 的 JSON 结构不向后兼容 v3 中使用的 XML 结构。

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

表示法和术语

v3 API 将特定电子表格中的工作表称为“worksheets”。这与 v4 API 使用的术语“sheets”同义。

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

v3 API 还会为使用其列表 Feed 检索到的行分配 ID;在本页面中,此 ID 由 rowId 占位符表示。

向请求授权

当应用运行时,它会要求用户授予特定权限;您在应用中指定的范围决定了它请求的权限。

v3 API

Tables API v3 采用单一授权范围:

https://spreadsheets.google.com/feeds

这是

https://www.googleapis.com/auth/spreadsheets

可以使用任一范围格式。

v4 API

Tables 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

Tables API v3 直接在其端点中表示可见性。public 电子表格已“在网络上发布”,因此 API 可以在未经授权的情况下访问该电子表格,而 private 电子表格则需要进行身份验证。可见性在电子表格 ID 后面的端点中指定:

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

v4 API

在新的表格 API v4 中,没有对可见性进行显式声明。API 调用使用电子表格 ID 进行。如果应用无权访问指定的电子表格,则会返回错误。否则,调用会继续。

Projection

Tables API v3 使用术语“投影”来指代给定 API 调用返回的数据集 - 可以全部涵盖该集,也可以指该 API 中定义的固定子集。Tables API v4 不使用投影;相反,它可让您更好地控制返回哪些数据。

v3 API

Tables API v3 中只有两种可能的投影设置。full 投影会返回所有可用信息,而 basic 则会返回较小的固定数据子集(适用于工作表 Feed、列表 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

Tables API v3 未提供创建新电子表格的方式,您可以使用 Drive API Files.create 方法创建新的电子表格文件。这需要应用声明 https://www.googleapis.com/auth/drive 范围。

v4 API

Drive API Files.create 方法也可以与 Tables 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

Google 表格 API v3 Feed 可让应用检索经过身份验证的用户可访问的所有电子表格的列表。电子表格 Feed 端点为:

GET https://spreadsheets.google.com/feeds/spreadsheets/private/full

v4 API

Tables API v4 不提供这种特定的操作。我们建议您迁移应用,以便将 drive.file 范围与 Google 选择器结合使用,以便选择电子表格。

如需列出电子表格,可以使用 mimeType 查询,通过 Drive API Files.list 方法进行复制:

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

如果使用 Drive API files.list 方法列出用户的所有电子表格,需要设置受限范围。

检索工作表元数据

Tables 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 方法获取工作表属性和其他元数据,远比使用 Tables 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

Tables 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 中返回的行按行顺序返回。Tables 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.getspreadsheets.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"]]
}

如果检索整行、整列或整个工作表,尾随空单元格将不会包含在响应中。

Tables API v4 没有与 Sheets API v3 提供的行顺序查询参数相对应的参数。颠倒顺序无关紧要;只需以倒序处理返回的 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

在 Tables 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 完全匹配。

更新条目后,使用相应的授权标头向该行条目中提供的 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

借助表格 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 中的 UpdateCellsRepeatCell 请求修改单元格属性和单元格格式。

删除行

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

v3 API

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

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

如果您希望确保不会删除自您检索以来已被另一个客户端更改的行,请添加一个 HTTP If-Match 标头,该标头包含原始行的 Dialogflow 值。您可以通过检查条目元素的 gd:etag 属性来确定原始行的 ETag 值。

如果您希望删除行,而不管自您检索以来是否有其他人更新过该行,请使用 If-Match: * 并且不要包含 eSIM 卡。(这种情况下,您在删除行之前不需要对其进行检索。)

v4 API

使用 Google 表格 API v4 删除行的操作是通过使用 DeleteDimension 请求执行的 spreadsheet.batchUpdate 方法调用处理。此请求还可用于移除列,开发者可选择仅移除行或列的一部分。例如,以下代码会移除具有指定 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

检索单元格数据

Tables API v3 提供了一个单元格 Feed,用于对电子表格中存储的所有数据进行基本访问。对于读取访问权限,单元格 Feed 可以提供整个工作表内容或由一组查询参数定义的工作表单元格范围,但只能作为单个块提供,不相交的范围必须使用其他 GET 请求单独检索。

Tables API v4 可以从工作表中检索任意一组单元格数据(包括多个不相交的范围)。Tables 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-rowmin-rowmax-colmin-col 查询参数提取单个特定范围。例如,以下代码检索第 4 (D) 列从第 2 行开始的所有单元:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
             ?min-row=2&min-col=4&max-col=4

Tables 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.getspreadsheets.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.updatespreadsheets.values.batchUpdate 方法。

v3 API

如需修改单个单元格的内容,请先在单元格 Feed 中找到该单元格的条目。该条目包含一个 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

在 Tables 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 字段应为 updategs:cell 按行号和列号标识单元格,并提供要插入其中的新数据。id 包含要更新的单元格的完整网址。link 必须具有 href 属性,该属性包含单元格 ID 的完整路径。每个条目都需要填写所有这些字段。

v4 API

Tables 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 将返回错误。