基本的な読み取り

Google Sheets API を使用すると、セル、範囲、範囲のセット、シート全体から値を読み取ることができます。このページの例では、一般的な読み取りオペレーションについて説明します。spreadsheets.valuesspreadsheets.get メソッドを使用してセル値を読み取ることもできますが、 通常は spreadsheets.values.get または spreadsheets.values.batchGet の方が簡単です。

これらの例は、言語に依存しない HTTP リクエストの形式で示されています。Google API クライアント ライブラリを使用してさまざまな言語で読み取りを実装する方法については、セル値の読み取りと書き込みをご覧ください。

以下の例では、プレースホルダ SPREADSHEET_ID は、 スプレッドシート ID を指定する場所を示しています。 スプレッドシート ID はスプレッドシートの URL から確認できます。読み取る範囲は A1 表記を使用してリクエスト URL で指定します。範囲の例は 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 から値を読み取り、レスポンスで 返す方法を示していますが、レンダリング オプションを使用して情報の 返され方を管理します。 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、 Products!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": [
        [...],
        [...]
      ]
    }
  ]
}