基本朗读

借助 Google Sheets API,您可以读取单元格、范围、范围集或单元格中的值 以及整个工作表本页中的示例展示了一些常见的读物 以及 spreadsheets.values 资源。您还可以使用 spreadsheets.get 方法,但 通常 spreadsheets.values.getspreadsheets.values.batchGet 更容易。

这些示例以 HTTP 请求的形式呈现, 中性。了解如何使用 Google Cloud API 客户端库,请参阅读取和写入写入单元格 值

在这些示例中,占位符 SPREADSHEET_ID 表示您在 将提供电子表格 ID, 可通过电子表格网址发现。要读取的范围为 在广告请求中使用 A1 表示法指定 网址。示例范围是 Sheet1!A1:D5。

源数据

对于这些示例,假设要读取的电子表格具有以下来源 数据。第一行中的字符串是 各个列。要查看如何从 电子表格,请参阅 A1 表示法

A B C D
1 费用 库存 发货日期
2 车轮 20.50 美元 4 2016 年 3 月 1 日
3 $15 2 2016 年 3 月 15 日
4 引擎 $100 1 2016 年 3 月 20 日
5 合计 135.5 美元 7 2016 年 3 月 20 日

读取单个范围

以下 spreadsheets.values.get 此代码示例展示了如何读取范围 Sheet1!A1:D5 中的值并返回 它们在响应中空白的拖尾行和列会被忽略。

请求协议如下所示。

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5

该响应包含 ValueRange 对象来描述范围值。通过 majorDimension 字段 表示数组是按行组织的值列表。

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "30/20/2016"],
    ["Totals", "$135.5", "7", "3/20/2016"]
  ],
}

读取按列分组的单个范围

以下 spreadsheets.values.get 此代码示例展示了如何读取范围 Sheet1!A1:D3 中的值并返回 但按列分组。空白的尾随行和列 。

请求协议如下所示。

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS

该响应包含 ValueRange 对象来描述范围值。通过 majorDimension 字段 表示数组是按列组织的值列表。

{
  "range": "Sheet1!A1:D3",
  "majorDimension": "COLUMNS",
  "values": [
    ["Item", "Wheel", "Door"],
    ["Cost", "$20.50", "$15"],
    ["Stocked", "4", "2"],
    ["Ship Date", "3/1/2016", "3/15/2016"]
  ],
}

使用呈现选项读取单个范围

以下 spreadsheets.values.get 此代码示例展示了如何读取范围 Sheet1!A1:D5 中的值并返回 但使用呈现选项来管理 。通过 ValueRenderOption设置 的 FORMULA 表示要返回公式,而不是 计算值,而 DateTimeRenderOption 设置为 SERIAL_NUMBER 表示以数字形式返回日期。 您也可以使用其他设置。空白的尾随行和列 。

请求协议如下所示。

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
            valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER

该响应包含 ValueRange 对象来描述范围值。通过 majorDimension 字段 表示数组是按行组织的值列表。

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "42430"],
    ["Door", "$15", "2", "42444"],
    ["Engine", "$100", "1", "42449"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

读取多个范围

以下 spreadsheets.values.batchGet 代码示例展示了如何读取范围 Sheet1!B:B 和 Sheet1!D:D 中的值, 它们会在响应中返回通过 ValueRenderOption设置 的 UNFORMATTED_VALUE 表示值已计算,但未设置格式 。空白的拖尾行和列会被忽略。

请求协议如下所示。

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

对此方法调用的响应包含一个带有电子表格 ID 的对象 以及 ValueRange 与每个请求范围对应的对象,按其先后顺序列出 请求。通过 majorDimension 字段 表示数组是按列组织的值列表。例如:

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!B1:B1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Cost",20.5,15,100,135.5]
      ]
    },
    {
      "range": "Sheet1!D1:D1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Ship Date",42430,42444,42449,42449]
      ]s
    }
  ]
}

在多个工作表中读取多个范围

以下 spreadsheets.values.batchGet 代码示例展示了如何从 Sheet1!A1:D5 工作表中读取范围中的值, Product!D1:D100 和 Sales!E4:F6 并在响应中返回。通过 ValueRenderOption设置 的 UNFORMATTED_VALUE 表示值已计算,但未设置格式 。空白的拖尾行和列会被忽略。

请求协议如下所示。

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

对此方法调用的响应包含一个带有电子表格 ID 的对象 以及 ValueRange 与每个请求范围对应的对象,按其先后顺序列出 请求。通过 majorDimension 字段 表示数组是按列组织的值列表。例如:

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!A1:D5",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    },
    {
      "range": "Products!D1:D100",
      "majorDimension": "COLUMNS",
      "values": [
        [...]
      ]
    },
    {
      "range": "Sales!E4:F6",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    }
  ]
}