Google Sheets API スキル（gws CLI）

1. 概要

gws CLI（@googleworkspace/cli）による Google Sheets API ネイティブ操作スキル。 Playwright UI操作（google-sheets-mcp）で発生するref揮発性・日本語入力問題・ログイン問題・Ctrl+A罠を根本的に解消する。

Playwright操作との使い分け

操作マッピング（Playwright → gws CLI）

2. 前提条件

インストール

# バイナリは手動ダウンロード済み
# 場所: C:/Users/zooyo/.local/bin/gws.exe
# バージョン: 0.3.3
gws --version

認証セットアップ

gcloud CLI がないため、手動OAuth設定が必要:

1. Google Cloud Console でプロジェクト作成（または既存を使用）
2. Google Sheets API を有効化（APIs & Services → Enable APIs）
3. OAuth 2.0 クライアントID（デスクトップアプリ）を作成
4. client_secret.json をダウンロード
5. 配置: %APPDATA%\gws\client_secret.json（= C:\Users\zooyo\AppData\Roaming\gws\client_secret.json）
6. 認証実行:

gws auth login
# ブラウザが開き、Googleアカウントで認証
# 認証後、credentials が保存される

7. 確認:

gws auth status
# auth_method: "oauth2" であればOK

定数

SHEET_ID = "1h1MSOUuH2hx0-Q-FCFjp6ylisY9yc4Y6EAocToFXUFg"
SHEET_NAME = "アプリ"  # シート（タブ）名

3. セル値の読み取り

3.1 ヘルパーコマンド（推奨: シンプルな読み取り）

# 単一セル
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!A5'

# 行データ一括
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!A5:G5'

# 範囲一括（セクションマップ構築用）
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!B1:B200'

# テーブル形式で見やすく出力
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!A1:G10' --format table

3.2 values get（詳細オプションが必要な場合）

# 単一セル
gws sheets spreadsheets values get \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","range":"アプリ!A5"}'

# 複数範囲一括取得
gws sheets spreadsheets values batchGet \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","ranges":["アプリ!A5:G5","アプリ!A10:G10"]}'

レスポンス形式（JSON）

{
  "range": "アプリ!A5:G5",
  "majorDimension": "ROWS",
  "values": [
    ["⬜", "テスト項目名", "手順の説明", "", "", "", ""]
  ]
}

• values は2次元配列。空セルは空文字列 "" または配列から省略される
• 絵文字（✅⬜）はそのままUnicode文字列として返る（Playwright目視と違いパース不要）

4. セル値の書き込み

4.1 単一セル / 小範囲の書き込み

# RAW: 値をそのまま書き込み（数式解釈なし）
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","range":"アプリ!A5","valueInputOption":"RAW"}' \
  --json '{"values":[["✅"]]}'

# USER_ENTERED: ユーザー入力と同じ解釈（数式・日付変換あり）
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","range":"アプリ!D5","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[["NG"]]}'

4.2 絵文字書き込み

APIなのでUnicode問題なし。Playwright execCommand方式のような回避策は不要。

# ⬜ → ✅ に変更
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","range":"アプリ!A5","valueInputOption":"RAW"}' \
  --json '{"values":[["✅"]]}'

# ✅ → ⬜ に戻す
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","range":"アプリ!A5","valueInputOption":"RAW"}' \
  --json '{"values":[["⬜"]]}'

4.3 複数セル一括書き込み（batchUpdate）

gws sheets spreadsheets values batchUpdate \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","valueInputOption":"RAW"}' \
  --json '{
    "data": [
      {"range": "アプリ!A5", "values": [["✅"]]},
      {"range": "アプリ!D5", "values": [["NG"]]},
      {"range": "アプリ!E5", "values": [["ログイン画面でエラー発生"]]},
      {"range": "アプリ!G5", "values": [["竹下"]]}
    ]
  }'

4.4 行の追加（末尾追記）

# シンプルな追記
gws sheets +append --spreadsheet "$SHEET_ID" --values '⬜,新テスト項目,手順説明,,,,未割当'

# JSON形式（複数行）
gws sheets +append --spreadsheet "$SHEET_ID" \
  --json-values '[["⬜","項目1","手順1","","","",""],["⬜","項目2","手順2","","","",""]]'

4.5 セルのクリア

# 単一セル
gws sheets spreadsheets values clear \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","range":"アプリ!D5"}'

# 複数範囲
gws sheets spreadsheets values batchClear \
  --params '{"spreadsheetId":"'"$SHEET_ID"'"}' \
  --json '{"ranges":["アプリ!D5","アプリ!E5"]}'

5. チェックリスト固有パターン

5.1 セクションマップ構築

B列を一括取得し、正規表現でセクション見出しの行番号をパースする。

# B列全体を取得
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!B1:B200' --format json

# レスポンスの values 配列のインデックス + 1 = 行番号
# セクション見出しは「■」「●」「▶」などの記号で始まる

パース例（Bashで処理する場合）:

gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!B1:B200' --format json \
  | python3 -c "
import json, sys, re
data = json.load(sys.stdin)
for i, row in enumerate(data.get('values', []), 1):
    if row and re.match(r'^[■●▶]', row[0]):
        print(f'Row {i}: {row[0]}')
"

5.2 テスト項目の読み取り（1行分）

ROW=5
gws sheets +read --spreadsheet "$SHEET_ID" --range "アプリ!A${ROW}:G${ROW}" --format json

列マッピング:

5.3 テスト結果の記入（典型パターン）

ROW=5

# パターン1: テスト合格
gws sheets spreadsheets values batchUpdate \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","valueInputOption":"RAW"}' \
  --json '{
    "data": [
      {"range": "アプリ!A'"$ROW"'", "values": [["✅"]]},
      {"range": "アプリ!D'"$ROW"'", "values": [["OK"]]},
      {"range": "アプリ!G'"$ROW"'", "values": [["竹下"]]}
    ]
  }'

# パターン2: テスト不合格
gws sheets spreadsheets values batchUpdate \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","valueInputOption":"RAW"}' \
  --json '{
    "data": [
      {"range": "アプリ!A'"$ROW"'", "values": [["✅"]]},
      {"range": "アプリ!D'"$ROW"'", "values": [["NG"]]},
      {"range": "アプリ!E'"$ROW"'", "values": [["ログイン画面でエラーメッセージが表示されない"]]},
      {"range": "アプリ!G'"$ROW"'", "values": [["竹下"]]}
    ]
  }'

5.4 担当者ドロップダウン（G列）

API経由でデータ入力規則のあるセルに値を書き込む場合:

# データ入力規則の値をそのまま書き込めばOK
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","range":"アプリ!G5","valueInputOption":"RAW"}' \
  --json '{"values":[["竹下"]]}'

注意: APIはデータ入力規則のバリデーションをバイパスしない。規則が「拒否」モードの場合、選択肢に含まれない値は書き込みエラーになる可能性がある。選択肢に含まれる正確な文字列を使用すること。

6. エラーハンドリング

リトライパターン

# 簡易リトライ（3回まで）
for i in 1 2 3; do
  result=$(gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!A1' 2>&1)
  if echo "$result" | grep -q '"values"'; then
    echo "$result"
    break
  fi
  echo "Retry $i..."
  sleep $((i * 2))
done

7. 出力フォーマット

# JSON（デフォルト、プログラム処理向き）
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!A1:G5' --format json

# テーブル（人間が読む用途）
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!A1:G5' --format table

# CSV（エクスポート用途）
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!A1:G5' --format csv

# YAML
gws sheets +read --spreadsheet "$SHEET_ID" --range 'アプリ!A1:G5' --format yaml

8. シェル変数テンプレート

スキル利用時にコピペで使えるテンプレート:

# 定数定義
SHEET_ID="1h1MSOUuH2hx0-Q-FCFjp6ylisY9yc4Y6EAocToFXUFg"
SHEET_NAME="アプリ"
GWS="C:/Users/zooyo/.local/bin/gws.exe"

# 読み取り
$GWS sheets +read --spreadsheet "$SHEET_ID" --range "${SHEET_NAME}!A${ROW}:G${ROW}"

# 書き込み（単一セル）
$GWS sheets spreadsheets values update \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","range":"'"${SHEET_NAME}"'!A'"${ROW}"'","valueInputOption":"RAW"}' \
  --json '{"values":[["✅"]]}'

# 書き込み（一括）
$GWS sheets spreadsheets values batchUpdate \
  --params '{"spreadsheetId":"'"$SHEET_ID"'","valueInputOption":"RAW"}' \
  --json '{"data":[{"range":"'"${SHEET_NAME}"'!A'"${ROW}"'","values":[["✅"]]},{"range":"'"${SHEET_NAME}"'!D'"${ROW}"'","values":[["OK"]]}]}'

関連スキル

改訂履歴