業務システム

Google Sheets APIの使い方:サービスアカウント認証とPythonでの読み書き・batchUpdate

Google Sheets APIの使い方:サービスアカウント認証とPythonでの読み書き・batchUpdate

Google Sheets API(v4)は、Googleスプレッドシートのセル値・シート構成・書式を、外部のプログラムからHTTPで読み書きするためのAPIです。この記事では、Google Cloudでの有効化、サービスアカウントの作成とスプレッドシートの共有、Pythonでの読み取り(get・batchGet)と書き込み(append・batchUpdate)を、コピーして動かせるコードで順に示します。後半では、毎分300リクエストのクォータに当たったときの429の再試行、鍵ファイルの扱い、GAS(Google Apps Script)との使い分けまで、実装者が本番前に決めておく事項を整理します。

まとめ:Google Sheets APIをPythonから動かす手順と設計判断の要点

手順は4段階です。Google CloudでSheets APIを有効化し、サービスアカウントを作り、そのメールアドレスへ対象のスプレッドシートを共有し、Pythonのクライアントライブラリから呼び出します。共有を忘れると、認証は通っても403が返ります。

読み書きは「値のAPI(spreadsheets.values)」で足りる場面がほとんどです。シートの追加や書式の変更が要るときだけ、構造のAPI(spreadsheets.batchUpdate)を使います。どちらも複数の操作を1リクエストにまとめられるので、まとめるほどクォータに余裕が出ます。

上限はプロジェクトあたり毎分300リクエスト、同じユーザー(サービスアカウント)からは毎分60リクエストです。超えると429が返るため、指数バックオフの再試行を最初から組み込みます。

スプレッドシートの中だけで完結する集計や通知はGASで十分です。社内の基幹システムや外部サービスとつなぐ処理、6分を超える処理、サーバー側のジョブから定期的に書き込む処理はAPIを選びます。毎分60回を超える書き込みが常時続くなら、スプレッドシートを保存先にする設計自体を見直す段階です。

Google Sheets API v4でできることと値APIと構造APIの2系統の違い

Sheets API v4のエンドポイントは https://sheets.googleapis.com/v4/spreadsheets 配下にあり、操作対象はスプレッドシートIDで指定します。IDはブラウザで開いたURLの /d/ と /edit の間の文字列です。

セルの値の読み書きとシート追加・書式設定に使う構造変更APIの使い分け

APIは大きく2系統に分かれます。公式の「セルの値の読み書き」ガイドが扱うのは spreadsheets.values 系で、セルの中身だけを読み書きします。もう一方の spreadsheets.batchUpdate は、シートの追加・削除、列幅、書式、条件付き書式、保護範囲など、スプレッドシートの構造を変える操作をまとめて送るAPIです。

メソッド 用途 1回で扱える範囲
values.get 1範囲の読み取り 1範囲
values.batchGet 複数範囲の読み取り 複数範囲
values.update 1範囲の上書き 1範囲
values.batchUpdate 複数範囲の上書き 複数範囲
values.append 表の末尾へ行を追加 1範囲
spreadsheets.batchUpdate シート追加・書式など構造変更 複数の変更要求

名前が似ている values.batchUpdate と spreadsheets.batchUpdate は別物です。前者は値だけ、後者は構造の変更を送ります。値の書き込みに後者の updateCells を使うこともできますが、記述が長くなるので、値だけなら前者で済ませます。

無料で使える範囲と毎分300リクエストのクォータ超過で返る429の扱い

公式の使用量の上限ページ(2026年11月時点)によると、読み取り・書き込みはそれぞれプロジェクトあたり毎分300リクエスト、プロジェクト内のユーザーごとに毎分60リクエストです。1日あたりの回数の上限はありません。1リクエストの処理が180秒を超えるとタイムアウトになり、ペイロードは2MBまでが推奨値です。

料金は、標準的な利用であれば追加費用がかかりません。ただし同ページには、クォータを超えたリクエストを2026年後半からGoogle Cloudの請求アカウントへ課金する予定と書かれています。超過を前提にした設計は、無料のつもりでいても費用が出る構成になりえます。

上限を超えたリクエストには429(Too many requests)が返り、1分たつと枠が戻ります。ここで効くのは、1回のリクエストに複数範囲をまとめるbatch系メソッドです。100セルを1セルずつ書けば100リクエストですが、values.batchUpdateなら1リクエストで済みます。

検証環境の準備:APIの有効化とサービスアカウント作成・共有設定

ここではサーバーやバッチから人の操作なしで動かす前提で、サービスアカウントを使います。公式のPythonクイックスタートは、ブラウザでログインして許可するOAuthクライアント(ユーザー認証)の例です。手元で個人のスプレッドシートを触るだけならそちらが簡単ですが、定期ジョブには向きません。

Cloudコンソールでの設定手順とPythonライブラリのインストール

Google Cloudコンソールでの作業は次の順です。

  1. プロジェクトを選び、「APIとサービス」から Google Sheets API を有効にする
  2. 「IAMと管理」→「サービスアカウント」でアカウントを作る(プロジェクトのロールは付けなくてよい)
  3. 実行環境がGoogle Cloudの外なら、鍵(JSON)を発行するか、Workload Identity連携を設定する
  4. 発行したサービスアカウントのメールアドレス(client_email)を控える

手順2でプロジェクトのロールが不要なのは、スプレッドシートへの権限をGoogleドライブの共有で与えるためです。サービスアカウントの仕組みはGoogle CloudのIAMドキュメントにまとまっています。Python側は次の2つを入れます。2026年11月21日時点のPyPIでは google-api-python-client が2.202系、google-auth が2.63系です。

# 仮想環境を作ってから入れる
python -m venv .venv
source .venv/bin/activate
pip install google-api-python-client google-auth

Windowsでは2行目を .venv\Scripts\activate に読み替えてください。

サービスアカウントのメールへのシート共有手順と読み取り時の閲覧者権限

サービスアカウントは、それ自体がGoogleドライブを持つ別のユーザーとして扱われます。人が作ったスプレッドシートを読むには、ブラウザでそのファイルを開き、「共有」に xxxx@プロジェクトID.iam.gserviceaccount.com 形式のメールアドレスを入れて、閲覧者か編集者を付けます。

この共有を忘れると、認証は成功しているのにAPIからは403(The caller does not have permission)か404が返ります。読み取りだけのジョブなら閲覧者に留めておくと、コードに誤りがあっても表を書き換えられないため、表を壊す事故を防止できる設定です。共有ドライブに置いたファイルなら、共有ドライブのメンバーにサービスアカウントを加える方法もあります。容量を持たないサービスアカウントを共有ドライブで使う方法と、ファイルのアップロード・検索のコードはGoogle Drive APIの使い方で解説しています。

スコープの選び方:spreadsheetsとdrive.fileの権限差

公式のスコープ一覧では、spreadsheets はすべてのスプレッドシートの閲覧・編集・作成・削除、spreadsheets.readonly は閲覧のみで、どちらも「機密(Sensitive)」に分類されます。drive.file はアプリが作成・選択したファイルだけを扱えて「非機密」で、Googleはこちらを推奨しています。drive は「制限付き(Restricted)」です。

サービスアカウントで共有済みのファイルを扱うなら、読むだけのジョブは spreadsheets.readonly、書くジョブは spreadsheets を指定します。不特定の利用者に公開するアプリでユーザー認証を使う場合は、機密スコープだとOAuth同意画面の審査が要るため、drive.file で足りる設計を先に検討します。スコープはファイル単位で効き、シート単位では絞れません。特定のセル範囲を守るには保護範囲(ProtectedRange)を使います。GAS側で同じスコープがどう扱われるかはGASのOAuthスコープと管理者統制の解説で整理しています。

Pythonでスプレッドシートを読む:get・batchGetと値の取り出し方

以下のコードは、鍵ファイル sa.json を同じディレクトリに置き、環境変数 SHEET_ID にスプレッドシートIDを入れて動かす前提です。

values.getで範囲を読むコードとA1表記・シート名の注意

import os
from google.oauth2 import service_account
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/spreadsheets"]
SHEET_ID = os.environ["SHEET_ID"]

creds = service_account.Credentials.from_service_account_file("sa.json", scopes=SCOPES)
service = build("sheets", "v4", credentials=creds, cache_discovery=False)
values_api = service.spreadsheets().values()

# シート名に空白や記号があるときはシングルクォートで囲む
res = values_api.get(
    spreadsheetId=SHEET_ID,
    range="'売上 2026'!A1:D100",
    valueRenderOption="UNFORMATTED_VALUE",
).execute()

for row in res.get("values", []):
    print(row)

戻り値の values は行の配列です。末尾の空セルと空行は返らないため、行ごとに要素数が変わります。列番号で値を取り出すコードでは、短い行を埋めてから使ってください。

valueRenderOption の既定は FORMATTED_VALUE で、表示形式を通した文字列(「1,200」「¥1,200」など)が返ります。計算に使う数値が欲しいときは UNFORMATTED_VALUE、数式そのものを見たいときは FORMULA を指定してください。日付は UNFORMATTED_VALUE だとシリアル値(1899年12月30日起点の日数)で返る点にも注意が要ります。

batchGetで複数範囲をまとめて読みリクエスト数を減らす方法

res = values_api.batchGet(
    spreadsheetId=SHEET_ID,
    ranges=["マスタ!A2:C", "設定!B1:B5"],
    valueRenderOption="UNFORMATTED_VALUE",
).execute()

master, config = (r.get("values", []) for r in res["valueRanges"])

A2:C のように終端の行を省くと、その列の最終行まで読みます。複数シートを読む処理を範囲ごとのgetで書くと、範囲の数だけクォータを消費します。batchGetにまとめれば1リクエストで、毎分60回の枠を圧迫しません。

Pythonで書き込む:update・append・batchUpdateの使い分け

書き込み系はすべて valueInputOption の指定が必須です。この指定を間違えると、日付が文字列のまま入る、数式が動かないといった不具合になります。

appendで行を追加するコードとvalueInputOptionの選び方

body = {"values": [["2026-11-21", "東京支店", 128000, "=C2*1.1"]]}

res = values_api.append(
    spreadsheetId=SHEET_ID,
    range="売上!A1",
    valueInputOption="USER_ENTERED",
    insertDataOption="INSERT_ROWS",
    body=body,
).execute()
print(res["updates"]["updatedRange"])

values.appendのリファレンスのとおり、appendは指定範囲から表を探し、その最終行の次に書き込みます。USER_ENTERED は画面で手入力したときと同じ解釈で、「2026-11-21」は日付に、「=C2*1.1」は数式として扱われる設定です。RAW なら入力をそのまま文字列で入れるので、利用者が入力した文字列をそのまま保存したい場合に使える設定です。外部から受け取った値に「=」で始まる文字列が混ざる可能性があるなら、意図しない数式を実行させないためにRAWを選びます。

insertDataOption の既定は OVERWRITE で、表の下にある既存データを上書きします。下に別の表やメモがあるシートでは INSERT_ROWS を指定して、行を挿入させてください。

values.batchUpdateで複数範囲を1リクエストで書き換える例

body = {
    "valueInputOption": "RAW",
    "data": [
        {"range": "集計!B2", "values": [[42]]},
        {"range": "集計!B3:B4", "values": [["完了"], ["2026-11-21 09:00"]]},
    ],
}
values_api.batchUpdate(spreadsheetId=SHEET_ID, body=body).execute()

updateと違い、valueInputOption はクエリではなくリクエスト本文に入れます。範囲が離れていても、同じスプレッドシート内なら1回で書き込み可能です。集計結果を複数セルへ書き戻すバッチ処理は、ほぼこの形で書けます。

spreadsheets.batchUpdateでシート追加と書式設定を行う例

requests = [
    {"addSheet": {"properties": {"title": "2026-11", "index": 0}}},
    {
        "repeatCell": {
            "range": {"sheetId": 0, "startRowIndex": 0, "endRowIndex": 1},
            "cell": {"userEnteredFormat": {"textFormat": {"bold": True}}},
            "fields": "userEnteredFormat.textFormat.bold",
        }
    },
]
res = service.spreadsheets().batchUpdate(
    spreadsheetId=SHEET_ID, body={"requests": requests}
).execute()
new_sheet_id = res["replies"][0]["addSheet"]["properties"]["sheetId"]

構造の変更では、シートを名前ではなく数値の sheetId で指定します。既存シートのIDは spreadsheets().get(fields="sheets.properties") で取れます。fields は変更するフィールドだけを列挙するマスクで、公式のbatchUpdateガイドにあるとおり、指定しないフィールドは変わりません。同ガイドには、まとめた要求のうち1件が失敗すると他も反映されないことも書かれています。シート追加と初期データ投入を1回にまとめれば、途中で止まった半端なシートが残りません。

本番運用で詰まる箇所:429のリトライ・鍵管理・同時書き込み

手元で動いたコードが本番で止まる原因は、クォータ、認証情報の置き場所、複数ジョブの同時書き込みの3つにほぼ集約されます。

429を受けたときに指数バックオフで再試行するPythonラッパーの実装例

公式は、待ち時間を min(2^n + ランダムなミリ秒, 上限) で延ばす指数バックオフを推奨しています。上限は32秒か64秒が目安です。

import random
import time
from googleapiclient.errors import HttpError

def call_with_backoff(request, max_retries=6, max_wait=64):
    for n in range(max_retries):
        try:
            return request.execute()
        except HttpError as e:
            if e.resp.status not in (429, 500, 503) or n == max_retries - 1:
                raise
            time.sleep(min(2 ** n + random.random(), max_wait))

rows = call_with_backoff(values_api.get(spreadsheetId=SHEET_ID, range="売上!A:D"))

google-api-python-clientの execute(num_retries=5) にも再試行の機能はありますが、待ち時間の上限や対象のステータスを自分で決めたいときは上のように包みます。429の設計全般はAPIレート制限と429設計の解説、外部APIを呼ぶ処理の認証・エラー処理の組み方はAPI連携の実装手順とリトライの解説で扱っています。

サービスアカウントの鍵JSONを置かない実行環境の構成とキー作成の制限

鍵JSONは、漏れれば共有されたすべてのスプレッドシートを読み書きされる認証情報です。リポジトリに入れない、実行環境のシークレット管理に置く、使わなくなった鍵を削除する、の3点は最低限守ります。

Cloud Run・Cloud Functions・GCEなどGoogle Cloud上で動かすなら、鍵は不要です。実行環境にサービスアカウントを紐づけ、コードでは google.auth.default(scopes=SCOPES) で認証情報を取ります。AWSやGitHub Actionsから呼ぶ場合も、Workload Identity連携を設定すればサービスアカウントの鍵を発行せずに呼び出しが可能です。組織のポリシーで鍵の作成が禁止されている(iam.disableServiceAccountKeyCreation)と鍵の発行ボタン自体が失敗するので、その場合は最初からこの構成を選ぶことになります。

同時書き込みにも注意が要ります。Sheets APIには行のロックやトランザクションがなく、2つのジョブが同時にappendすると、行の順序は保証されません。同じセルをupdateで書き換える処理が並べば、後勝ちになります。書き込み元は1ジョブに絞るか、キューで直列化します。

GASとGoogle Sheets APIの使い分けと採用しない場面の判断基準

同じ「スプレッドシートを自動で書き換える」処理でも、GASとAPIでは向く条件がはっきり分かれます。GASの基本はGAS(Google Apps Script)の入門と制限の数値にまとめています。

GASで処理できる条件と実行時間の目安(シート内完結・6分以内・1日90分以内)

Apps Scriptの割り当てでは、1回の実行は6分まで、トリガーによる実行の合計は無料アカウントで1日90分、Google Workspaceで1日6時間です(2026年11月時点)。この範囲で、データがスプレッドシートとGoogleのサービスの中で完結しているなら、GASを選びます。サーバーも鍵も要らず、ファイルの持ち主の権限で動くので、共有設定の手間もありません。

フォームの回答を整形する、毎朝の集計をメールで送る、シートの更新をSlackに流すといった処理がこれに当たります。受信したメールをスプレッドシートや業務システムに取り込む処理は、Gmail APIでの受信・ラベル操作とPub/Sub通知の実装で扱っています。Slack連携の具体例はSlackワークフローとスプレッドシートの連携手順にあります。

APIを選ぶ条件とスプレッドシートをDB代わりにしない線引き

次のどれかに当たるなら、Sheets APIを使います。

  • 社内の基幹システムやDB、外部SaaSのデータを、自社のサーバーやバッチから書き込む
  • 1回の処理が6分を超える、またはトリガーの合計時間を超える
  • 処理をGitで管理し、テストやCIに載せたい
  • PythonやGoの既存ライブラリ、社内の共通処理を使いたい

一方、どちらも採用しないほうがよい場面があります。書き込みが常に毎分60回を超える、数万行を超える表を頻繁に検索する、複数の処理が同じ行を同時に更新する、といった要件です。これはスプレッドシートを業務データベースとして使っている状態で、APIの工夫では解決しません。データの正本はRDBやkintone等に移し、スプレッドシートは閲覧・集計用の出力先にする構成が現実的です。外部システムとスプレッドシートの連携、あるいは保存先の移行を外部に任せたい場合は、API開発・システム連携の相談窓口で、連携方式とデータの正本の置き場所から一緒に検討できます。

Google Sheets APIの認証・クォータ・料金についてよくある質問

実装を始めた人から出やすい質問を、公式ドキュメントの記載をもとにまとめます。

Google Sheets APIは無料で使えますか?

標準的な利用は追加費用なしで使えます。必要なのはGoogle Cloudのプロジェクトだけで、APIの有効化に請求先アカウントは要りません。ただし公式の上限ページには、毎分のクォータを超えたリクエストを2026年後半から課金対象にする予定と書かれています。429を前提にした再試行と、batch系メソッドでの呼び出し回数の削減は、費用面でも意味を持つようになります。

サービスアカウントで403エラーが出るのはなぜですか?

多くは、対象のスプレッドシートがサービスアカウントのメールアドレスに共有されていないことが原因です。サービスアカウントは別のユーザーなので、作成者が編集できるファイルでも、共有しなければ見えません。共有済みなら、Sheets APIがそのプロジェクトで有効になっているか、スコープが readonly のまま書き込もうとしていないかを確かめてください。

gspreadと公式クライアントライブラリはどちらを使うべきですか?

gspread(2026年11月時点で6.2系)はSheets APIを包んだサードパーティのライブラリで、ワークシートや行を操作する書き方が短くなります。読み書き中心の小さなスクリプトならgspreadで十分です。書式やシート構造の変更が多い、他のGoogle API(DriveやBigQuery)と認証を共通化したい、という場合は公式の google-api-python-client を選ぶと、リファレンスと1対1で対応するので迷いません。

1回に書き込めるデータ量の上限はありますか?

リクエストサイズの厳密な上限は定められていません。公式は処理速度のためにペイロードを2MBまでにすることを推奨しており、1リクエストの処理が180秒を超えるとタイムアウトになります。数万行を一度に書く処理は、数千行ずつに分けて送り、各回をbatch系メソッドでまとめると安定します。

APIキーだけでスプレッドシートを読めますか?

「リンクを知っている全員」に公開したスプレッドシートなら、APIキーで読み取りはできます。非公開のファイルの読み取りや、書き込みはできません。社内データを扱う場合は、公開設定に頼らず、サービスアカウントかユーザー認証(OAuth)で読み書きする構成にしてください。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2025.12.19 コラム アンダーマイニング効果とは?具体例と報酬でやる気が下がる条件、エンハンシング効果との違い
  2. 2026.11.20 テックブログ MAI Code 2とは?Flashとの違い・料金・GitHub Copilotでの使い方【2026年11月】
  3. 2026.11.18 テックブログ 楽天証券の不正アクセス:最大約447万口座の対象確認と、テスト環境に本番データを置かない実装
  4. 2026.11.20 テックブログ 六花亭の不正アクセス:決済画面の改ざんでカード情報約8,000件、対象期間と改ざん検知の手順【11月20日時点】
  5. 2026.11.09 テックブログ teket不正アクセス:ログインできない理由と再開見通し、入場・退会・偽メールの確認【11月16日時点】

RELATED POSTS 関連記事

目次