# 既存の業務スプレッドシートに「成果物シート」を自動追加する（Drive コネクタでは不可・Sheets API 直叩き） 調べ物やリスト作成の成果を、新しいファイルではなく**案件の正本スプレッドシートの中に新しいタブとして足す**ための手順。依頼者がそのタブに直接書き込んで運用を続けられる形にする。 ## なぜ新規ファイルを作らないのか - 正本が1ファイルに集約され、関係者が同じ場所だけ見れば済む - 案件ごとに成果物ファイルが増えないので、検索と共有権限の管理コストが案件数に比例して増えない - 次に同種の案件が来たとき、その1ファイルを読むだけで過去の候補・単価・断られた理由まで再利用でき、外部調査のやり直しが不要になる ## 前提の落とし穴（ここで時間を失う） 1. **Drive の MCP コネクタ／汎用 Drive API ではシートタブを追加できない。** ファイルの作成・読み書きはできても `addSheet` が無い。Sheets API を直接叩く必要がある。 2. **Drive コネクタの `create_file` 系は本文を base64 で要求することがある。** プレーンテキストを渡すと `The file content is not a valid base64 string.` で落ちる。パラメータ名も `name` ではなく `title` 等、実装ごとに違う。エラー文のフィールド名をそのまま読んで直す。 3. **大きなスプレッドシートの読み取りは応答上限を超える。** 100万字級になるとツールの戻り値がファイルに退避される。親の文脈を守るため、退避ファイルは別プロセス（スクリプト）かサブエージェントに解析させ、要点だけ受け取る。 4. **Windows の Node で絶対パスを `import` するときは `file:///` が必要。** `import x from 'C:/path/mod.mjs'` は `ERR_UNSUPPORTED_ESM_URL_SCHEME`（`Received protocol 'c:'`）になる。`file:///C:/path/mod.mjs` と書く。 ## 手順 ### 1. 書き込みスコープのアクセストークンを得る 既存の Drive 連携があるなら、その認証モジュールに**スプレッドシート用のスコープ**を要求する。 ```js import { getDriveToken } from 'file:///<絶対パス>/drive-auth.mjs'; const token = await getDriveToken({ scope: 'https://www.googleapis.com/auth/spreadsheets' }); ``` 読み取り専用スコープのトークンを使い回すと `addSheet` で 403 になる。スコープは明示する。 ### 2. タブを足して値を流し込む（冪等に） ```js const API = 'https://sheets.googleapis.com/v4/spreadsheets'; const auth = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }; const SHEET_ID = '<スプレッドシートID>'; const TITLE = '<タブ名>'; // 既存タブを調べ、同名があれば addSheet を飛ばす（再実行しても壊れない） const meta = await fetch(`${API}/${SHEET_ID}?fields=sheets.properties`, { headers: auth }); const exists = (await meta.json()).sheets.some((s) => s.properties.title === TITLE); if (!exists) { await fetch(`${API}/${SHEET_ID}:batchUpdate`, { method: 'POST', headers: auth, body: JSON.stringify({ requests: [{ addSheet: { properties: { title: TITLE, gridProperties: { rowCount: 60, columnCount: 13, frozenRowCount: 1 }, } } }] }), }); } // rows は配列の配列。長さが揃っていなくてよい（短い行はそのまま左詰め） await fetch(`${API}/${SHEET_ID}/values/${encodeURIComponent(`'${TITLE}'!A1`)}?valueInputOption=USER_ENTERED`, { method: 'PUT', headers: auth, body: JSON.stringify({ values: rows }), }); ``` タブ名を range に入れるときは**シングルクォートで囲んでから URL エンコード**する（日本語・空白・記号を含むタブ名で必須）。 ### 3. read-back verify する（省略しない） 書き込み API が 200 を返しても、range 指定ミスで別タブに入っていることがある。**書いた場所を読み返してから完了と言う。** ```js const back = await fetch(`${API}/${SHEET_ID}/values/${encodeURIComponent(`'${TITLE}'!A1:B3`)}`, { headers: auth }); console.log('READBACK', JSON.stringify((await back.json()).values)); ``` ### 4. タブへ直接飛ぶ URL を渡す ```js const meta2 = await fetch(`${API}/${SHEET_ID}?fields=sheets.properties`, { headers: auth }); const gid = (await meta2.json()).sheets.find((s) => s.properties.title === TITLE).properties.sheetId; // https://docs.google.com/spreadsheets/d//edit#gid= ``` `gid` を付けないと先頭タブが開き、受け取った人が自分で探すことになる。**gid まで含めて渡す。** ## 中身の作り方（運用に効く部分） - **記入用の空列を用意する。** 候補リストなら「ステータス」「金額」「備考」を空欄で並べておく。読む人がその場で書き込めることが、別ファイルにしないことの価値そのもの。 - **不明は「不明」と書く。** 推測で埋めない。後から埋める人が、未調査なのか調査済みで無いのかを区別できる。 - **末尾に前提条件を併記する。** 日時・場所・規模・予算・先方担当など、そのタブ単体で判断できる情報を数行置く。元のファイルの別タブを探させない。 - **優先度を1列目に置いて並べ替え済みで渡す。** 並べ替えを読む人にさせない。 ## 実行環境での注意 - 使い捨てスクリプトは一時ディレクトリにファイルとして置き、`node ` で実行する。長いコードをシェルの引数に埋め込むと、クォート崩れと安全機構の誤検知の両方を踏む。 - 同じスクリプトを2回実行しても安全になっているか（`addSheet` のスキップ、`PUT` の上書き）を必ず確認してから走らせる。 ## 効果 - 成果物ファイルの増殖と、そのたびの共有設定が消える - 過去案件の再利用が「1ファイルを開く」だけになり、同種案件での外部調査をやり直さずに済む - 受け取った人の操作が「リンクを開いて書き込む」だけになる ---