API

【Python】.spreadsheets().values().appendとは？使い方や引数の意味を詳しく解説！

【Python】.spreadsheets().values().appendとは？使い方や引数の意味を詳しく解説！

Google SheetsをPythonから操作したいときに便利なのが google-api-python-client ライブラリです。

その中でも .spreadsheets().values().append() は、スプレッドシートにデータを追記（append）するための基本的なメソッドです。

この記事では .append() の基本的な使い方から、引数の意味、活用シーン、注意点までをわかりやすく丁寧に解説します。

.spreadsheets().values().append() とは？

.spreadsheets().values().append() は、Google Sheets の特定のシートの末尾にデータを追加するためのメソッドです。

既存のデータを上書きせず、空いている次の行に追記する処理が可能になります。

Google Sheets APIの values.append エンドポイントをPythonで扱いやすくした形で、フォーム送信やログ記録など、追記処理に非常に便利です。

基本的な使い方

まずは、スプレッドシートに1行のデータを追記する基本的なコードを見てみましょう。

このコードでやっていることは：

  1. credentials.json によるサービスアカウント認証

    •  Google Cloud Console で作成したサービスアカウントの鍵ファイル（JSON形式）を使って、Google Sheets API にアクセスするための認証情報（Credentials オブジェクト）を生成しています。
    • これにより、Pythonプログラムが認証されたユーザーとしてGoogle Sheetsにアクセスできるようになります。

  1. build() で Sheets API クライアントを作成

    • googleapiclient.discovery.build("sheets", "v4", credentials=creds) を使って、Google Sheets API バージョン4 のクライアントオブジェクトを生成しています。
    • これによって、.spreadsheets().values() などのメソッドをPythonから直接呼び出せるようになります。

  1. append() を使って "シート1" の末尾に1行データを追加

    •  指定されたスプレッドシートIDと範囲（ここでは "シート1!A1"）をもとに、データをスプレッドシートの末尾に追加しています。
    • このとき、既存のデータは保持され、新しい行が自動的に挿入されます。

具体例：複数行を一気に追加

このように、リストを複数行分渡すことで、一括で複数行をスプレッドシートに追加できます。

.spreadsheets().values().append()の主な引数と意味

.spreadsheets().values().append() メソッドを使用する際には、いくつかの重要な引数を指定する必要があります。

基本的に以下の5つを押さえておけば十分です。

引数 説明
spreadsheetId 対象のスプレッドシートID（URLの /d/ と /edit の間にある文字列）
range データを追加する対象範囲（シート名と開始セル）例: "シート1!A1"
valueInputOption 数式として扱うか、そのままの値として扱うかを決める
insertDataOption 追加データの挿入方法。新しい行として追加するか、既存の範囲に上書きするかを指定
body 実際に追加したいデータ（2次元リスト）を {"values": [[...]]} の形式で渡す

valueInputOption の種類

この引数は、データを追加する際にどのように解釈させるかを決めます。

たとえば、日付や数式をそのまま反映したい場合は "USER_ENTERED" を使うのが一般的です。

値 意味
RAW 入力をそのまま値として扱う（数式も文字列になる）=SUM(A1:A5) も単なる文字列になる
USER_ENTERED 入力をユーザー入力として解釈（=SUM(A1:A5) などの数式もOK）数式や日付も自動で処理される。

通常は USER_ENTERED を使えば、日付・数式・数値の自動解釈ができるため便利です。

insertDataOption の種類

この引数は、追加するデータが既存データとどう重なるかを指定します。

追記したい場合は "INSERT_ROWS" を使うのが基本です。

値 意味
INSERT_ROWS 既存のデータを下にずらして、新しい行として追記する。もっとも一般的な追記方法
OVERWRITE 指定した範囲内の既存データを上書きする。追記ではなく更新や書き換えに使う

通常は "INSERT_ROWS" を使えば安全に末尾へ追加できます。

誤って既存データを消さないよう注意しましょう。

.spreadsheets().values().append()活用シーン

.spreadsheets().values().append() は以下のような用途で活躍します。

  • Webフォームや問い合わせ情報の記録
  • ログ情報や分析データの蓄積
  • アプリや業務ツールからの出力保存
  • 毎日のレポート・日次データの追加

追加先を意識せず「とにかく下に追記」できるため、シンプルな構造のスプレッドシートに最適です。

注意点：既存の空白行があると意図しない位置に追加されることも

スプレッドシート上に途中で空白の行があると、.spreadsheets().values().append()  はその直後に追加されることがあります。

「最終行の下に追加したい」場合は、できるだけ上から詰めた構成にしておくのが理想です。

また、範囲（range）は "A1" のような固定セルでも、.append() では自動的に次の空き行を探して追記される仕組みになっています。

そのため、基本的に "A1" 固定で問題ありません。

まとめ

今回は .spreadsheets().values().append() の使い方について詳しく紹介しました。

  • .append() は Google Sheets に追記（下に追加）するためのメソッド
  • spreadsheetId, range, valueInputOption, body が基本引数
  • "A1" のような範囲を指定しても、空いている次の行に自動で追加される
  • valueInputOption="USER_ENTERED" で日付や数式の自動解釈が可能
  • insertDataOption="INSERT_ROWS" で追記モードに
  • フォーム送信、ログ記録、業務データ追加など多用途で使える

Google Sheets をPythonで操作する際の定番メソッドなので、ぜひ使いこなしておきましょう。

おすすめの記事