google-sheets

Google Sheets

スプレッドシートの管理、データ操作、数式処理のために Google Sheets を利用します。

インストール

依存関係：pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

セットアップの確認

インストール後、スキルが正しく設定されていることを確認します。

$SKILL_DIR/scripts/google-sheets.py check

次の項目を確認します。

• Python の依存関係（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml）
• 認証設定
• Google Sheets API への接続

不足している項目がある場合、確認コマンドでセットアップ手順が表示されます。

認証

Google Sheets は認証に OAuth 2.0 を使用します。セットアップの詳しい手順については、次を参照してください。

1. GCP プロジェクトのセットアップガイド - プロジェクトを作成し、Sheets API を有効にします
2. Google OAuth のセットアップガイド - 認証情報を設定します

クイックスタート

1. ~/.config/agent-skills/google.yaml を作成します。

   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   

2. $SKILL_DIR/scripts/google-sheets.py check を実行して OAuth フローを開始し、セットアップを確認します。

スコープまたは認証エラーが発生した場合は、OAuth のトラブルシューティングガイドを参照してください。

コマンド

各コマンドの読み取り／書き込みの分類については、permissions.md を参照してください。

check

設定と接続を確認します。

$SKILL_DIR/scripts/google-sheets.py check

次の項目を検証します。

• Python の依存関係がインストールされている
• 認証が設定されている
• Google Sheets API に接続できる
• 書き込みアクセスを確認するため、テスト用スプレッドシートを作成する

auth setup

カスタム OAuth フロー用の OAuth 2.0 クライアント認証情報を保存します。

$SKILL_DIR/scripts/google-sheets.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

認証情報は ~/.config/agent-skills/google-sheets.yaml に保存されます。

オプション：

• --client-id - OAuth 2.0 クライアント ID（必須）
• --client-secret - OAuth 2.0 クライアントシークレット（必須）

auth reset

保存されている OAuth トークンを消去します。次に認証が必要なコマンドを実行すると、自動的に再認証が開始されます。

$SKILL_DIR/scripts/google-sheets.py auth reset

スコープまたは認証エラーが発生した場合に使用します。

auth status

API 呼び出しを行わずに、現在の OAuth トークン情報を表示します。

$SKILL_DIR/scripts/google-sheets.py auth status

トークンが保存されているか、許可されたスコープ、リフレッシュトークンの有無、トークンの有効期限、クライアント ID が表示されます。

spreadsheets create

新しい Google Sheets スプレッドシートを作成します。

$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "My Spreadsheet"

オプション：

• --title - スプレッドシートのタイトル（必須）
• --sheets - シート名をカンマ区切りで指定（任意）

例：

# Create with default Sheet1
$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "Sales Data"

# Create with custom sheets
$SKILL_DIR/scripts/google-sheets.py spreadsheets create \
  --title "Q1 Report" \
  --sheets "Summary,January,February,March"

# Output:
# ✓ Spreadsheet created successfully
# Title: Q1 Report
# Spreadsheet ID: 1abc...xyz
# Sheets: 4 (Summary, January, February, March)
# URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit

spreadsheets get

スプレッドシートのメタデータと構造を取得します。

$SKILL_DIR/scripts/google-sheets.py spreadsheets get SPREADSHEET_ID

引数：

• spreadsheet_id - Google Sheets スプレッドシートの ID

例：

$SKILL_DIR/scripts/google-sheets.py spreadsheets get 1abc...xyz

# Output:
# Title: Sales Data
# Spreadsheet ID: 1abc...xyz
# Sheets: 2 (Sheet1, Summary)
# URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit

values read

範囲内のセルの値を読み取ります。

$SKILL_DIR/scripts/google-sheets.py values read SPREADSHEET_ID --range "Sheet1!A1:D5"

引数：

• spreadsheet_id - Google Sheets スプレッドシートの ID

オプション：

• --range - A1 表記の範囲（必須。例："Sheet1!A1:D5"）
• --format - 値の形式：FORMATTED_VALUE（デフォルト）、UNFORMATTED_VALUE、または FORMULA

例：

# Read a range
$SKILL_DIR/scripts/google-sheets.py values read 1abc...xyz --range "Sheet1!A1:C3"

# Output (formatted as table):
# Name      | Age | City
# Alice     | 30  | NYC
# Bob       | 25  | LA

# Read formulas
$SKILL_DIR/scripts/google-sheets.py values read 1abc...xyz \
  --range "Sheet1!D1:D10" \
  --format FORMULA

A1 表記の詳細については、references/range-notation.md を参照してください。

values write

範囲に値を書き込みます。

$SKILL_DIR/scripts/google-sheets.py values write SPREADSHEET_ID \
  --range "Sheet1!A1" \
  --values '[[\"Name\",\"Age\"],[\"Alice\",30]]'

引数：

• spreadsheet_id - Google Sheets スプレッドシートの ID

オプション：

• --range - A1 表記で指定する開始範囲（必須）
• --values - JSON の 2 次元配列で指定する値（必須）

例：

# Write data starting at A1
$SKILL_DIR/scripts/google-sheets.py values write 1abc...xyz \
  --range "Sheet1!A1" \
  --values '[[\"Product\",\"Price\",\"Quantity\"],[\"Widget\",9.99,100]]'

# Write a single row
$SKILL_DIR/scripts/google-sheets.py values write 1abc...xyz \
  --range "Sheet1!A5" \
  --values '[[\"Total\",999,50]]'

# Output:
# ✓ Values written successfully
#   Updated cells: 6
#   Updated range: Sheet1!A1:C2

注： 値はユーザーが入力する場合と同じように入力されます。数式は = で始まります。

values append

シートの末尾に行を追加します。

$SKILL_DIR/scripts/google-sheets.py values append SPREADSHEET_ID \
  --range "Sheet1" \
  --values '[[\"New\",\"Row\",\"Data\"]]'

引数：

• spreadsheet_id - Google Sheets スプレッドシートの ID

オプション：

• --range - シート名または範囲（必須）
• --values - JSON の 2 次元配列で指定する値（必須）

例：

# Append a single row
$SKILL_DIR/scripts/google-sheets.py values append 1abc...xyz \
  --range "Sheet1" \
  --values '[[\"Charlie\",35,\"Chicago\"]]'

# Append multiple rows
$SKILL_DIR/scripts/google-sheets.py values append 1abc...xyz \
  --range "Sheet1" \
  --values '[[\"David\",28,\"Boston\"],[\"Eve\",32,\"Seattle\"]]'

# Output:
# ✓ Values appended successfully
#   Updated cells: 3
#   Updated range: Sheet1!A4:C4

値のクリア

範囲内の値をクリアします。

$SKILL_DIR/scripts/google-sheets.py values clear SPREADSHEET_ID --range "Sheet1!A1:D10"

引数：

• spreadsheet_id - Google Sheets のスプレッドシート ID

オプション：

• --range - A1 表記の範囲（必須）

例：

# Clear a range
$SKILL_DIR/scripts/google-sheets.py values clear 1abc...xyz --range "Sheet1!A1:Z100"

# Output:
# ✓ Values cleared successfully
#   Cleared range: Sheet1!A1:Z100

警告： 値のみがクリアされます。書式や、保護されたセルの数式はクリアされません。

シートの作成

スプレッドシートに新しいシートを追加します。

$SKILL_DIR/scripts/google-sheets.py sheets create SPREADSHEET_ID --title "New Sheet"

引数：

• spreadsheet_id - Google Sheets のスプレッドシート ID

オプション：

• --title - シートのタイトル（必須）

例：

$SKILL_DIR/scripts/google-sheets.py sheets create 1abc...xyz --title "Q2 Data"

# Output:
# ✓ Sheet created successfully
#   Title: Q2 Data
#   Sheet ID: 123456789

シートの削除

スプレッドシートからシートを削除します。

$SKILL_DIR/scripts/google-sheets.py sheets delete SPREADSHEET_ID --sheet-id 123456789

引数：

• spreadsheet_id - Google Sheets のスプレッドシート ID

オプション：

• --sheet-id - シート ID（必須。タイトルではありません！）

例：

# Get sheet IDs first
$SKILL_DIR/scripts/google-sheets.py spreadsheets get 1abc...xyz

# Delete a sheet
$SKILL_DIR/scripts/google-sheets.py sheets delete 1abc...xyz --sheet-id 123456789

# Output:
# ✓ Sheet deleted successfully

警告： スプレッドシートに残っている最後のシートは削除できません。

例

スプレッドシートの作成とデータ入力

# Create spreadsheet
$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "Employee Data"

# Write headers (use the spreadsheet ID from the output above)
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Name","Department","Salary","Start Date"]]'

# Append employee records
$SKILL_DIR/scripts/google-sheets.py values append $SS_ID \
  --range "Sheet1" \
  --values '[["Alice","Engineering",120000,"2023-01-15"],["Bob","Sales",95000,"2023-03-01"]]'

# Add a summary sheet
$SKILL_DIR/scripts/google-sheets.py sheets create $SS_ID --title "Summary"

# Read the data
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID --range "Sheet1!A1:D10"

数式の操作

# Write data with formulas
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Item","Price","Qty","Total"],["Widget",10,5,"=B2*C2"],["Gadget",20,3,"=B3*C3"]]'

# Read formulas
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID \
  --range "Sheet1!D2:D3" \
  --format FORMULA

# Read calculated values
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID \
  --range "Sheet1!D2:D3" \
  --format FORMATTED_VALUE

バッチ操作

#!/bin/bash
SS_ID="your-spreadsheet-id"

# Clear old data
$SKILL_DIR/scripts/google-sheets.py values clear $SS_ID --range "Sheet1!A1:Z1000"

# Write new data in batches
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Date","Revenue","Expenses","Profit"]]'

for month in Jan Feb Mar; do
  $SKILL_DIR/scripts/google-sheets.py values append $SS_ID \
    --range "Sheet1" \
    --values "[[\"\$month\",10000,7000,\"=B${ROW}-C${ROW}\"]]"
done

エラー処理

認証エラーとスコープエラーは再試行できません。 コマンドが認証エラー、不十分なスコープのエラー、または権限拒否エラー（終了コード 1）で失敗した場合は、処理を停止してユーザーに伝えてください。再試行したり、自律的に問題を修正しようとしたりしないでください。これらのエラーにはユーザーの操作（ブラウザーを使用した OAuth の同意）が必要です。ユーザーにOAuth のトラブルシューティングガイドを案内してください。

再試行可能なエラー： レート制限（HTTP 429）と一時的なサーバーエラー（HTTP 5xx）は、少し待ってから再試行すると解決する場合があります。それ以外のエラーはすべてユーザーに報告してください。

モデルに関するガイダンス

このスキルでは、構造化された入力／出力を必要とする API 呼び出しを行います。標準的な能力を備えたモデルの使用を推奨します。

トラブルシューティング

スプレッドシートが見つからない

URL から正しいスプレッドシート ID を使用していることを確認してください。

• URL：https://docs.google.com/spreadsheets/d/1abc...xyz/edit
• スプレッドシート ID：1abc...xyz

範囲が無効というエラー

• 正しい A1 表記を使用してください：Sheet1!A1:D5
• スペースを含むシート名には引用符が必要です：'My Sheet'!A1:B2
• 詳細はreferences/range-notation.mdを参照してください。

--values の JSON 解析エラー

JSON が正しくエスケープされていることを確認してください。

# Correct
--values '[["Hello","World"]]'
--values "[[\"Name\",\"Age\"]]"

# Incorrect
--values [[Hello,World]]  # Missing quotes

シート ID とシートタイトル

コマンドによって使用する識別子が異なります。

• sheets create - タイトル（文字列）を使用します
• sheets delete - シート ID（数値）を使用します
• spreadsheets get を使用してシート ID を確認してください

API リファレンス

高度な使い方については、以下を参照してください。

• Google Sheets API のドキュメント
• セル値の読み取りと書き込み
• A1 表記のリファレンス
• 数式の例