基本閱讀

您可以使用 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"]
  ],
}

讀取依欄分組的單一範圍

下列程式碼範例說明如何從範圍 Sheet1!A1:D3 讀取值，並在回應中傳回這些值，但會依資料欄分組。spreadsheets.values.get系統會省略結尾的空白資料列和資料欄。

要求通訊協定會顯示在這裡。

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 範圍讀取值，並在回應中傳回這些值。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
    }
  ]
}

讀取多個工作表中的多個範圍

下列程式碼範例說明如何從工作表 Sheet1!A1:D5、Products!D1:D100 和 Sales!E4:F6 的範圍讀取值，並在回應中傳回這些值。spreadsheets.values.batchGetUNFORMATTED_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": [
        [...],
        [...]
      ]
    }
  ]
}