google-sheets

Google Sheets

Google Sheets API v4（https://sheets.googleapis.com/v4/）を使用して Google Sheets を操作するためのツールです。スプレッドシートの検索には Google Drive API を使用します。2 つの相補的な操作面にわたる 26 個のツールを備えています。レコード操作面では、列見出しをキーとするオブジェクトとして行を扱います（「経費を記録する」「ステータスを Done に更新する」「前四半期の合計を調べる」といった操作向け）。セル操作面では、数式、精密な数値・テキスト制御、任意の範囲に対応する、生の A1 形式のアドレス指定値を扱います。さらに、スプレッドシートとワークシートの構造や表示（書式設定、並べ替え、入力規則）も操作できます。

Google Sheets 用の独立した非公式コネクターです。Google Sheets との提携、推奨、スポンサー関係はありません。「Google Sheets」はその所有者の商標であり、このコネクターが対応するサービスを識別する目的でのみ使用しています。

こんなときに使います

• スプレッドシート内のデータを読み取る、または検索する — 列の値で行を検索する（lookupRow）、一致するすべての行を検索する（findRows）、指定範囲の行を一覧表示する（listRows）、または生の範囲を読み取る（getValues）。
• データを書き込む — 1 行または複数行を追加する（createRow／createRows）、他の列に影響を与えずに行の特定の列を更新する（updateRow／updateRows）、または生の範囲／数式を書き込む（updateValues）。
• 消去または削除する — 行を残したまま内容を消去する（clearRows／clearValues）、または行自体を削除する（deleteRows）。
• 構造を管理する — スプレッドシートを作成する（createSpreadsheet）、ワークシートの追加／一覧表示／コピー／名前変更／非表示／削除、列の追加を行う。
• 書式設定と入力規則を管理する — 数値／日付／通貨の書式、テキストのスタイル設定、範囲の並べ替え、範囲のコピー、ドロップダウン、数値／日付の入力規則、条件付き書式に対応しています。

セットアップ

これは agentskills.io のスキルです。

コネクターをまだスキルとしてインストールしていない場合は、まず npx skills add zapier/connectors --skill google-sheets（または、お使いのハーネス独自のスキルインストール方法）でインストールしてから、ここに進んでください。スキルのインストールでコピーされるのはこれらのファイルであり、依存関係ではありません。CLI、ローカル MCP サーバー、または zapier-sdk の認証コマンドを実行する前に、ここで一度 npm install --omit=dev を実行してください。公開済みパッケージを依存関係として独自のプロジェクトにインポートする場合は、npm install ですでにすべての依存関係が解決されています。詳細は references/use-as-sdk.md を参照してください。

実際のリポジトリのソース（references/ の閲覧、このコネクターのテスト実行、または改変など）を確認したい場合は、対象を絞った git clone について README.md を参照してください。

このコネクターの実行には Node.js 22.18+ が必要です。実行方法に合ったリファレンスを選び、ほかのことを始める前に読み込んでください。

該当する環境	読み込むファイル
MCP 対応クライアントを使用している（ツールがすでに読み込まれている場合があります。例：mcp__google-sheets__<tool>。または、ローカルサーバーを自分で登録するか、ユーザーに登録方法を案内できます）	references/use-as-mcp.md
ターミナル／サブプロセスにアクセスできる（node を実行できる）	references/use-as-cli.md
独自のコードのみを使用し、このパッケージを依存関係としてインポートする	references/use-as-sdk.md
ツールにもターミナルにもアクセスできず、このパッケージをインポートできないため、Google Sheets API を直接呼び出す独自のコードを作成する（例：コード実行サンドボックス）	references/use-as-recipe.md

スクリプト

すべてのスクリプトで、単一の google-sheets 接続を使用します。

スクリプト	スクリプト名	接続先	説明
scripts/createSpreadsheet.ts	createSpreadsheet	google-sheets	新しいスプレッドシートを作成します。ワークシートやヘッダー行を任意で追加できます。
scripts/getSpreadsheet.ts	getSpreadsheet	google-sheets	スプレッドシートのメタデータとワークシートの一覧を取得します。
scripts/listSpreadsheets.ts	listSpreadsheets	google-sheets	Drive で名前を指定してスプレッドシートを検索します（Drive へのアクセスが必要です。アクセスできない場合は URL/id を渡してください）。
scripts/addWorksheet.ts	addWorksheet	google-sheets	ワークシート（タブ）を追加します。ヘッダー行も任意で追加できます。
scripts/listWorksheets.ts	listWorksheets	google-sheets	スプレッドシート内のワークシート（タブ）を一覧表示します。
scripts/copyWorksheet.ts	copyWorksheet	google-sheets	ワークシートを別のスプレッドシート（または同じスプレッドシート）にコピーします。
scripts/updateWorksheetProperties.ts	updateWorksheetProperties	google-sheets	ワークシートの名前変更、移動、行／列の固定、非表示、色の変更を行います。
scripts/deleteWorksheet.ts	deleteWorksheet	google-sheets	ワークシートとそのデータを完全に削除します。
scripts/addColumn.ts	addColumn	google-sheets	列を挿入します。ヘッダーラベルも任意で追加できます。
scripts/createRow.ts	createRow	google-sheets	列ヘッダーをキーとした値を指定して、1 行を追加します。
scripts/createRows.ts	createRows	google-sheets	1 回のバッチ呼び出しで複数の行を追加します。
scripts/updateRow.ts	updateRow	google-sheets	行番号で指定した行の列を更新します（他の列は変更されません）。
scripts/updateRows.ts	updateRows	google-sheets	1 回のバッチ呼び出しで、行番号を指定して複数の行を更新します。
scripts/lookupRow.ts	lookupRow	google-sheets	列の値が一致する最初の行を検索します。
scripts/findRows.ts	findRows	google-sheets	列／値のフィルターに一致するすべての行を検索します（件数制限あり）。
scripts/listRows.ts	listRows	google-sheets	行の範囲をレコードとして読み取ります。
scripts/clearRows.ts	clearRows	google-sheets	指定した行の内容を消去します（行は残り、他の行は移動しません）。
scripts/deleteRows.ts	deleteRows	google-sheets	指定した行を削除します。下の行はすべて上に移動します。
scripts/getValues.ts	getValues	google-sheets	A1 表記で指定したセル範囲の生データを読み取ります。
scripts/updateValues.ts	updateValues	google-sheets	セル範囲に値を書き込みます（RAW または USER_ENTERED）。
scripts/clearValues.ts	clearValues	google-sheets	セル範囲の値を消去します（書式は残ります）。
scripts/formatCells.ts	formatCells	google-sheets	範囲に数値／日付／通貨の書式、またはテキストのスタイルを適用します。
scripts/sortRange.ts	sortRange	google-sheets	1 つ以上の列を基準に範囲を並べ替えます。
scripts/copyRange.ts	copyRange	google-sheets	範囲（値＋書式）を別の場所にコピーします。
scripts/setDataValidation.ts	setDataValidation	google-sheets	範囲にプルダウン／数値／日付の入力規則を設定します。
scripts/addConditionalFormatRule.ts	addConditionalFormatRule	google-sheets	範囲に条件付き書式ルールを追加します。

曖昧さの解消と拒否

書き込み前に曖昧さを解消します。 列の値で見つけた行に書き込む前に（例：lookupRow で見つけた行を更新する場合や、listSpreadsheets で見つけたスプレッドシートを操作する場合）、大文字と小文字を区別しない完全一致の件数を数えます。

• 一致がちょうど1件 — その対象を操作します。必要以上に確認を求めないでください。曖昧さのない一致が1件なら、それが答えです。
• 一致が2件以上で同数 — そこで停止します。区別できるフィールド（別の列の値、スプレッドシートの更新日時／URL）とともに、該当する行（またはスプレッドシート）を一覧表示し、どれを選ぶか尋ねます。恣意的に選んだり、すべてに書き込んだりしないでください。

行番号は安定していません — 挿入／削除／並べ替えによって変わります。実行をまたいで同じ論理レコードを対象にするには、記憶した行番号ではなく、lookupRow を使って一意のキー列で照合してください。

破壊的な操作や一括上書き操作の前に確認します。 deleteWorksheet、deleteRows、clearRows、clearValues はデータを削除します。updateValues はデータを上書きする可能性があります。まず、対象をユーザーに確認し、依頼された範囲を超えて削除／消去／上書きしてはいけません。

未対応の操作 — その旨を伝えて停止してください。別のツールでごまかしてはいけません。 このカタログでは、意図的に次の操作に対応していません。

• グラフ、ピボットテーブル、名前付き範囲、保護された範囲、フィルターの作成や管理。 これらに対応するツールはありません。書式設定で代用しないでください。
• 検索と作成を1ステップで行うこと。 lookupRow を実行し、見つからなければ createRow を実行する形で組み合わせてください。
• スプレッドシート全体の完全削除。 構造を削除できるのはワークシートの削除（deleteWorksheet）のみです。

これらの操作を求められた場合は、未対応であることをユーザーに伝えて停止してください。

認証

すべての形式では、シークレットではなく、単一の接続セレクター（[<resolver>:]<value> 形式）を使って認証を渡します。すべてのコネクターで zapier:<connection-id>（Zapier 管理の認証 — Zapier の認証、再試行、ガバナンスレイヤーを経由します）を使用できます。また、一部のコネクターでは、直接トークン用のリゾルバーも1つ以上使用できます（名称と数はコネクターによって異なります）。推測せず、このコネクター独自のリゾルバーを確認してください。<resolver>: プレフィックスは省略可能です。値だけを指定した場合、その値を受け付ける最初のリゾルバーに渡されます。UUID 形式の値のみを指定した場合は、必ず zapier: が受け付けます。各スクリプトでは、必要な接続と、それぞれで受け付けるリゾルバーが宣言されています。接続を渡す正確な構文（およびこのコネクターのリゾルバー一覧の確認方法）は、形式によって異なります — 上で読み込んだリファレンスを参照してください。

すでに設定済みのものを確認する場合：環境変数の値を表示してはいけません — env や env | grep <name> は名前とともに値も出力するため、設定されている場合は有効な認証情報が会話ログに漏れてしまいます。名前だけを確認する（env | cut -d= -f1 | grep -i <name>）か、既知の名前を直接テストしてください（[ -n "$VAR_NAME" ]）。

まだ接続がありませんか？ 次のいずれかを選び、認証情報の取得には各リファレンス独自の手順に従ってください。ユーザーが接続 ID やトークンをすでに覚えているかのように、単に尋ねてはいけません。

	読み込み
認証情報を直接渡す	references/use-without-zapier.md
Zapier 接続を経由して認証情報を渡す	references/use-with-zapier.md

出力形式

すべてのスクリプトは { data, meta } エンベロープを返します。

• data — スクリプトの結果です（outputSchema が宣言する形状です。スクリプトの正確なスキーマを確認する方法については、上で読み込んだリファレンスを参照してください）。
• meta.outputDataValidation — data の検証結果です。
  • { skipped: false, droppedPaths: null } — 検証済みで、何も削除されていません。
  • { skipped: false, droppedPaths: [...], instruction } — 検証済みですが、該当するパスが data から削除されています。これらは、スクリプトが API から返したものの、outputSchema では宣言されていないフィールドです。必要な場合は、出力検証をスキップして再実行してください。
  • { skipped: true } — 検証はバイパスされ、data は未検証のスクリプト出力そのものです。

削除されたフィールドの読み取り／skipOutputDataValidation。 未検証の結果をそのまま受け取るには、出力検証を無効にします（正確な構文は形状によって異なります。上で読み込んだリファレンスを参照してください）。入力検証はスキップされません。

結果の絞り込み／filterOutputData。 大きな結果から必要なフィールドだけに絞り込むには、data に後処理を行う jq 式を渡します（正確な構文は形状ごとに異なります）。jq は { data, meta } エンベロープではなく data のみに対して実行されるため、data を起点に記述してください（スクリプトの --help、または形状に応じた同等のコマンドで出力スキーマを確認できます）。変換後の値が data を置き換え、meta はそのまま保持されます。また、結果は出力スキーマに対して再検証されません。

リファレンス

該当する領域で作業する前に、対応するリファレンスファイルを読み込んでください。

リファレンス	対象	次の場合に読み込んでください
references/google-sheets-api-gotchas.md	エラーからの復旧、レート制限時の再試行、batchUpdate のアトミック性、行の削除と追加のロジック、400/403/404/429 エラー	失敗する可能性のある操作を行う前（エラーからの復旧、レート制限時の再試行、batchUpdate のアトミック性、行の削除または追加のロジックなど）、または 400/403/404/429 エラーが発生した場合
references/google-sheets-a1-and-values.md	RAW と USER_ENTERED の違い、シリアル値の日付、行ごとの長さが不揃いなデータ、シート名の引用符を含む A1 範囲	セルの値を読み書きする前（特に RAW と USER_ENTERED の選択、シリアル値の日付の解釈、行ごとの長さが不揃いなデータの処理、シート名の引用符を含む A1 範囲の構築を行う場合）