基本朗读

您可以使用 Google Sheets API 读取单元格、范围、范围集和整个工作表中的值。本页面的示例演示了使用 spreadsheets.values 资源的一些常见读取操作。您还可以使用 spreadsheets.get 方法读取单元格值，但通常 spreadsheets.values.get 或 spreadsheets.values.batchGet 更简单。

这些示例以 HTTP 请求的形式呈现，不涉及具体语言。如需了解如何使用 Google API 客户端库以不同语言实现读取操作，请参阅读取和写入单元格值。

在这些示例中，占位符 SPREADSHEET_ID 表示您应提供电子表格 ID 的位置，该 ID 可从电子表格网址中找到。要读取的范围在请求网址中使用 A1 表示法指定。一个范围示例是 Sheet1!A1:D5。

源数据

对于这些示例，假设要读取的电子表格在其第一个工作表（“Sheet1”）中包含以下源数据。第一行中的字符串是各个列的标签。如需查看如何从电子表格中的其他工作表中读取数据的示例，请参阅 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 中读取值并在响应中返回这些值，但使用呈现选项来管理返回这些信息的方式。FORMULA 的 ValueRenderOption 设置表示要返回公式而不是计算出的值，而 SERIAL_NUMBER 的 DateTimeRenderOption 设置表示要以数字形式返回日期。您也可以选择其他设置。系统会省略末尾的空行和空列。

此处显示的是请求协议。

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 中读取值，并在响应中返回这些值。UNFORMATTED_VALUE 的 ValueRenderOption 设置表示系统会计算值，但不会在响应中设置格式。系统会省略末尾的空行和空列。

此处显示的是请求协议。

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、Products!D1:D100 和 Sales!E4:F6 中的范围读取值，并在响应中返回这些值。UNFORMATTED_VALUE 的 ValueRenderOption 设置表示系统会计算值，但不会在响应中设置格式。系统会省略末尾的空行和空列。

此处显示的是请求协议。

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