• #google-apps-script
  • #python
  • #gogcli
  • #clasp
  • #google-sheets
開発未分類メモ

Google Apps Script + Sheets の業務ロジックを Python + CSV に移行する

結論

Google Apps Script（GAS）と Google Sheets で構築された業務ロジックは、以下の組み合わせでローカルに引き出して解析・移行できる。

  • シートのデータ・数式 → gogcli（Google Workspace CLI）で取得
  • GAS のコード → clasp で取得
  • 両方を Claude Code に読ませて解析し、Python + CSV に変換

移行後も Google Sheets を共有インターフェースとして維持できるため、他のメンバーは従来通りシートを見るだけでよい。

背景：GAS + Sheets の中身をどう把握するか

業務で使っている Google Sheets に GAS がくっついている場合、全体像の把握に手間がかかる。シートの構成、数式、GAS のロジックを個別に確認する必要があるからだ。

Claude Code からこれを一括で解析できないか検証した。

事前準備

gogcli

gogcli のセットアップと OAuth 認証が済んでいること。Sheets API のスコープ（spreadsheets / drive）が認証済みトークンに含まれている必要がある。

gog auth login

clasp

GAS のコードを取得する場合は、GCP コンソールで Apps Script API を有効にしておく。

GCP で Apps Script API を有効化した画面

npm install -g @google/clasp
clasp login

gogcli で Sheets にアクセスする

シート構成の取得

gog --json sheets metadata <spreadsheetId>

シート名、行数・列数、フィルター設定などが JSON で返る。

セルのデータ取得

--render オプションで取得形式を切り替えられる。

--render の値内容用途
FORMATTED_VALUE（デフォルト）表示値（書式適用済み）目視確認
UNFORMATTED_VALUE生の値（数値は数値型）データ処理
FORMULA数式（数式がないセルは値）ロジック解析
# 表示値（デフォルト）
gog --json sheets get <spreadsheetId> "シート名!A1:F10"

# 生の値
gog --json sheets get <spreadsheetId> "シート名!A1:F10" --render=UNFORMATTED_VALUE

# 数式
gog --json sheets get <spreadsheetId> "シート名!A1:F10" --render=FORMULA

移行時は、ロジック解析に FORMULA、検証（期待値の照合）に FORMATTED_VALUE または UNFORMATTED_VALUE を使い分ける。

実際の出力例

{
  "range": "'計算チェック'!A1:F5",
  "values": [
    [],
    ["", "Check", "=C8-C11", "←ゼロでOK"]
  ]
}

gogcli で取得できるもの・できないもの

情報コマンド取得可否
シート構成・シート名一覧gog sheets metadata可
セルの値（表示値・生値）gog sheets get可
セルの数式gog sheets get --render=FORMULA可
書式・条件付き書式—不可（Sheets API の spreadsheets.get で取得可能だが gogcli 未対応）
データ検証・保護範囲—不可
グラフ・ピボット—不可
Apps Script コード—不可

業務ロジックの移行では、データと数式が取れれば十分なことが多い。書式やグラフは移行対象から外すか、別途 Sheets API を直接叩いて対応する。

GAS のコードは clasp で取得する

gogcli には Apps Script API 用のコマンドがない。GAS のコードを取得するには clasp（Command Line Apps Script Projects）を使う。

clasp clone <scriptId>

scriptId はスプレッドシートの 拡張機能 > Apps Script を開いたときの URL から取得できる。

clone すると以下のファイルがローカルにダウンロードされる。

ファイル内容
*.gs / *.jsGAS のソースコード
appsscript.jsonマニフェスト（依存サービス・スコープ・タイムゾーン）
.clasp.jsonclasp の設定（scriptId）

GAS 移行時のチェックリスト

clasp clone で取得できるコード以外にも、移行時に確認すべき項目がある。

  • スクリプトプロパティ: PropertiesService で保存された設定値（API キーなど）
  • トリガー設定: onEdit、時間ベーストリガーなど
  • ライブラリ依存: 外部ライブラリを Library として参照しているか
  • 高度なサービス: appsscript.json の dependencies.enabledAdvancedServices を確認
  • UI 連携: カスタムメニュー（onOpen）、サイドバー、ダイアログ

解析・移行のワークフロー

┌─────────────────────────────────────────────────┐
│  Google 側                                       │
│                                                  │
│  Spreadsheet ──── Apps Script (.gs)              │
│     │                    │                       │
└─────┼────────────────────┼───────────────────────┘
      │                    │
      │ gog sheets         │ clasp clone
      │                    │
┌─────┼────────────────────┼───────────────────────┐
│  ローカル                                         │
│     │                    │                       │
│     ▼                    ▼                       │
│  シート構成/データ/数式   .gs + appsscript.json   │
│     │                    │                       │
│     └────────┬───────────┘                       │
│              │                                   │
│              ▼                                   │
│     Claude Code で解析                            │
│              │                                   │
│              ▼                                   │
│     Python スクリプト + CSV 出力                  │
└─────────────────────────────────────────────────┘

手順

  1. clasp clone で GAS のコード + マニフェストをローカルに取得
  2. gog sheets metadata でシート構成を把握
  3. gog sheets get --render=FORMULA で数式を含むデータを取得
  4. gog sheets get で表示値も取得（検証用）
  5. Claude Code に全ファイルを読ませて GAS の処理内容を解析
  6. Python に変換 し、入出力を CSV にする
  7. 検証: Python の出力と元の表示値を比較して一致を確認

移行後の運用：Sheets を共有インターフェースとして残す

Python に移行した後も、結果の共有には Google Sheets を使える。

# CSV の内容を Sheets に書き戻す
gog sheets update <spreadsheetId> "出力シート!A1" val1 val2 val3

# 行を追記する
gog sheets append <spreadsheetId> "出力シート!A1" val1 val2 val3

つまり以下の構成になる。

  • 実装: Python（ローカルまたはサーバーで実行）
  • 入力: CSV or API
  • 出力: CSV（ローカル保存）+ Google Sheets（共有用にプッシュ）
  • 共有: 他のメンバーは従来通り Sheets を開くだけ

移行で失われる GAS 固有の機能

GAS から Python に移行すると、以下の機能は別の仕組みで再実装する必要がある。

GAS の機能Python での代替
onEdit トリガー（セル編集時に自動実行）Sheets API の watch / polling、または運用で代替
時間ベーストリガー（定期実行）cron / タスクスケジューラ
カスタムメニュー・サイドバー対応なし（Sheets UI に依存するため移行不可）
カスタム関数（=MYFUNCTION()）シート上で使えなくなる。Python で計算して値を書き戻す
SpreadsheetApp による書式設定Sheets API の batchUpdate で対応可能

まとめ

  • gogcli でシートのデータ・数式・構成を取得できる（書式やグラフは対象外）
  • GAS のコードは clasp でローカルに取得する
  • 両方をローカルに落とせば Claude Code で全体を解析できる
  • Python + CSV に移行しても、gogcli で Sheets に書き戻せば共有インターフェースは維持できる
  • GAS 固有の機能（onEdit、カスタム関数など）は別途再実装が必要