このページは Cloud Translation API によって翻訳されました。

基本的な表現

Google Sheets API を使用すると、値や数式をセル、範囲、範囲のセット、シート全体に書き込むことができます。このページの例は、Sheets API の spreadsheets.values リソースを使用して一般的な書き込みオペレーションを実行する方法を示しています。

なお、spreadsheet.batchUpdate メソッドを使用してセル値を書き込むこともできます。これは、spreadsheets.values リソースが影響しないセルの書式設定やその他のプロパティを同時に更新する場合に役立ちます。たとえば、セルの数式とセルの書式設定の両方を上書きしながら、セル範囲をあるシートから別のシートにコピーする場合は、spreadsheet.batchUpdate で UpdateCellsRequest メソッドを使用します。

ただし、単純な値の書き込みでは、spreadsheets.values.update メソッドまたは spreadsheets.values.batchUpdate メソッドを使用する方が簡単です。

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

これらの例では、プレースホルダ SPREADSHEET_ID は、スプレッドシートの URL から確認できるスプレッドシート ID を指定する場所を示しています。書き込む範囲は A1 表記を使用して指定します。範囲の例は Sheet1!A1:D5 です。

単一の範囲の書き込み

次の spreadsheets.values.update コードサンプルは、新しい空のスプレッドシートから、範囲に値を書き込成する方法を示しています。ValueInputOption クエリパラメータは必須であり、書き込まれた値を解析するかどうか（文字列を日付に変換するかどうかなど）を決定します。

リクエストの本文は、書き込む範囲の値を記述する ValueRange オブジェクトです。majorDimension フィールドは、配列が行で構成された値のリストであることを示します。対象範囲の既存の値は上書きされます。

リクエストプロトコルを以下に示します。

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "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", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

レスポンスは、次のような UpdateValuesResponse オブジェクトで構成されます。

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

結果のシートは次のようになります。

	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 日

範囲への選択的な書き込み

値を範囲に書き込むときに、対応する配列要素を null に設定すると、既存のいくつかのセルを変更しないように指定できます。空の文字列（""）をセルに書き込むことで、セルをクリアすることもできます。

上記の例で生成された同じデータを含むシートで、次の spreadsheets.values.update コードサンプルは、値を範囲 B1:D4 に書き込み、選択的にいくつかのセルを変更せずに、他のセルをクリアする方法を示しています。ValueInputOption クエリパラメータは必須であり、書き込む値を解析するかどうか（たとえば、文字列を日付に変換するかどうか）を指定します。

リクエストの本文は、書き込む範囲値を記述する ValueRange オブジェクトです。majorDimension フィールドは、配列が列で構成された値のリストであることを示します。

リクエストプロトコルを以下に示します。

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

この values フィールドには、範囲内の各列に加えられた変更が一覧表示されます。最初の配列は、B1 を変更せずに保持し（配列要素 null があるため）、B4 をクリアする（空の文字列にする）ことを示しています。B2 と B3 の値が更新されます。3 番目の配列は列 D に対して同じオペレーションを実行します。2 番目の空の配列は、列 C を変更しないことを示します。

レスポンスは、次のような UpdateValuesResponse オブジェクトで構成されます。

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

結果のシートは次のようになります。

	A	B	C	D
1	項目	費用	在庫あり	発送日
2	ホイール	$1.00	4	2016 年 4 月 1 日
3	ドア	$2	2	2016 年 4 月 15 日
4	エンジン		1
5	合計	$3.00	7	2016 年 4 月 15 日

"合計" 行はこのリクエストによって直接変更されませんが、変更されたセルに依存する数式が合計行のセルに含まれているため、合計行が変更されることに注意してください。

複数の範囲への書き込み

空のシートで、次の spreadsheets.values.batchUpdate コードサンプルは、値を Sheet1!A1:A4 と Sheet1!B1:D2 の範囲に書き込む方法を示しています。対象範囲の既存の値は上書きされます。リクエスト本文は、入力データを解釈する方法を示す ValueInputOption オブジェクトと、書き込まれる各範囲に対応する ValueRange オブジェクトの配列で構成されます。majorDimension フィールドは、含まれている配列を列または行の配列として解釈するかどうかを指定します。

リクエストプロトコルを以下に示します。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

レスポンスは、更新されたセルの統計をリストしたオブジェクトと、更新された各範囲に対応する UpdateValuesResponse オブジェクトの配列で構成されます。例:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

結果のシートは次のようになります。

	A	B	C	D
1	項目	費用	在庫あり	発送日
2	ホイール	$20.50	4	2016 年 3 月 1 日
3	ドア
4	エンジン
5

解析なしの値の書き込み

空のシートで、次の spreadsheets.values.update コードサンプルは、値を Sheet1!A1:E1 の範囲に書き込む方法を示しています。ただし、RAW ValueInputOption クエリパラメータを使用して、書き込まれた文字列が数式、ブール値、数値として解析されないようにします。文字列として表示され、シート内のテキストの配置は中央揃えになります。

リクエスト本文は、書き込む範囲値を記述する ValueRange オブジェクトです。majorDimension フィールドは、配列が行で構成された値のリストであることを示します。ターゲット範囲内の既存の値は上書きされます。

リクエストプロトコルは次のようになります。

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

レスポンスは、次のような UpdateValuesResponse オブジェクトで構成されます。

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

結果のシートは次のようになります。

	A	B	C	D	E
1	データ	123.45	TRUE	=MAX(D2:D4)	10
2

「TRUE」は中央に揃えられ、ブール値です。一方、「123.45」は数値であるため右に揃えられ、「10」は文字列であるため左に揃えられています。数式は解析されず、文字列として表示されます。

値を追加する

以下の表のようなシートで操作を開始します。

	A	B	C	D
1	項目	費用	在庫あり	発送日
2	ホイール	$20.50	4	2016 年 3 月 1 日
3

次の spreadsheets.values.append コードサンプルは、行 3 から 2 つの新しい値の行を追加する方法を示しています。ValueInputOption クエリパラメータは必須であり、書き込む値を解析するかどうか（たとえば、文字列を日付に変換するかどうか）を指定します。

リクエストの本文は、書き込む範囲の値を記述する ValueRange オブジェクトです。majorDimension フィールドは、配列が行で構成された値のリストであることを示します。

リクエストプロトコルは次のようになります。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

レスポンスは、次のような AppendValuesResponse オブジェクトで構成されます。

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

結果のシートは次のようになります。

	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