此页面由 Cloud Translation API 翻译。

基本朗读

借助 Google Sheets API，您可以读取单元格、范围、范围集或单元格中的值以及整个工作表本页中的示例展示了一些常见的读物以及 spreadsheets.values 资源。您还可以使用 spreadsheets.get 方法，但通常 spreadsheets.values.get 或 spreadsheets.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

{
  "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": [
        [...],
        [...]
      ]
    }
  ]
}