google-docs

Google Docs

ドキュメントのコンテンツにはGoogle Docs API v1（https://docs.googleapis.com/v1/）を、Docs API では提供されない検索／エクスポート／テンプレートのコピー／フォルダー操作にはGoogle Drive API v3（https://www.googleapis.com/drive/v3/）を使用して、Google Docs を操作するツールです。22 個のツールを備えています。ドキュメントの作成（空のドキュメント、テキスト／Markdown からの作成、テンプレートからの作成）、構造化されたコンテンツとタブの読み取り、テキスト／Markdown としてのエクスポート、ドキュメント名での検索、コンテンツの編集（テキストの追記／挿入／検索と置換／削除、テキスト位置の特定、文字と段落の書式設定、箇条書き／番号付きリストの作成、表の挿入と編集、ヘッダー／フッター／脚注の作成、インライン画像の挿入と置換、ページ／余白／背景のスタイル設定）ができます。

Google Docs 用の独立した非公式コネクターです。Google Docs とは提携、承認、後援関係にありません。「Google Docs」はその所有者の商標であり、このコネクターが連携するサービスを特定する目的でのみ使用しています。

こんなときに使います

• エージェントがドキュメントを作成する必要がある場合。空のドキュメント、初期テキストや Markdown からの作成、または {{placeholder}} テンプレートへの入力ができ、必要に応じて特定の Drive フォルダーに保存できます。
• エージェントがドキュメントを読み取る必要がある場合。構造化されたコンテンツと編集インデックス（getDocument）、整形済みのテキスト／Markdown（exportDocument）、ドキュメント名での検索（findDocuments）、テキストの検索（findText）ができます。
• エージェントがテキストを編集する必要がある場合。追記、位置を指定した挿入、検索と置換、または範囲の削除ができます。
• エージェントが書式設定やスタイル変更を行う必要がある場合。文字の書式を設定したり、箇条書きまたは番号付きリストを作成したり（createList）、段落スタイル（見出し、配置、行間、インデント）を設定したり（formatParagraph）、インライン画像を挿入／置換したり、ページサイズ／余白／背景を設定したりできます。
• エージェントがドキュメントの構成を整える必要がある場合。表を挿入してセルに入力したり（insertTable）、表の行または列を追加／削除したり（modifyTable）、ヘッダーまたはフッターとそのテキストを作成して（createHeader／createFooter）、返された segmentId を formatText に渡してスタイルを設定したり、脚注を追加して（createFootnote）、返された segmentId を対象に insertText で本文を書き込んだりできます。

セットアップ

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

コネクターをまだスキルとしてインストールしていない場合は、まず npx skills add zapier/connectors --skill google-docs（または、お使いのハーネス独自のスキルインストール方法）でインストールしてから、ここに戻ってください。スキルをインストールすると、依存関係ではなく、これらのファイルがコピーされます。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-docs__<tool>）。または、ローカルサーバーを自分で登録する（あるいはユーザーに案内する）こともできます）	references/use-as-mcp.md
ターミナル／サブプロセスへのアクセス（node を実行できます）	references/use-as-cli.md
独自のコードのみ（このパッケージを依存関係としてインポートします）	references/use-as-sdk.md
ツール、ターミナル、このパッケージをインポートする手段がなく、Google Docs API を直接呼び出す独自のコードを記述する場合（例：コード実行サンドボックス）	references/use-as-recipe.md

スクリプト

すべてのスクリプトでは、単一の google-docs 接続を使用します（1 つの OAuth 認証情報で Docs と Drive の両方のホストを認証します）。

スクリプト	スクリプト名	接続先	説明
scripts/createDocument.ts	createDocument	google-docs	初期テキストや Markdown を指定して、フォルダー内に新しいドキュメントを作成します。
scripts/createDocumentFromTemplate.ts	createDocumentFromTemplate	google-docs	テンプレートドキュメントをコピーし、{{placeholder}} トークンに値を入力します。
scripts/getDocument.ts	getDocument	google-docs	ドキュメントの構造化されたコンテンツ、タブ、編集インデックスを読み取ります。
scripts/exportDocument.ts	exportDocument	google-docs	ドキュメントをプレーンテキストまたは Markdown としてエクスポートします。
scripts/findDocuments.ts	findDocuments	google-docs	名前やフォルダーを指定して Google Docs ドキュメントを検索します。
scripts/appendText.ts	appendText	google-docs	ドキュメントの末尾にテキスト（必要に応じて Markdown）を追加します。
scripts/insertText.ts	insertText	google-docs	指定したインデックスにテキストを挿入します。
scripts/replaceAllText.ts	replaceAllText	google-docs	文字列を検索し、一致するすべての箇所を置換します。
scripts/findText.ts	findText	google-docs	フレーズの出現箇所を特定し、そのインデックス範囲を返します。
scripts/deleteContentRange.ts	deleteContentRange	google-docs	インデックス範囲内のコンテンツを削除します。
scripts/formatText.ts	formatText	google-docs	インデックス範囲に文字書式を適用します。
scripts/formatParagraph.ts	formatParagraph	google-docs	範囲内の段落スタイル（見出し、配置、間隔、インデント）を設定します。
scripts/createList.ts	createList	google-docs	範囲を箇条書きまたは番号付きリストにするか、両者を切り替えます。
scripts/removeListFormatting.ts	removeListFormatting	google-docs	テキストを残したまま、範囲の箇条書きや番号付けを解除します。
scripts/insertImage.ts	insertImage	google-docs	公開 URL からインライン画像を挿入します。
scripts/replaceImage.ts	replaceImage	google-docs	既存のインライン画像を新しい画像に置き換えます。
scripts/updateDocumentStyle.ts	updateDocumentStyle	google-docs	ページサイズ、余白、背景色を設定します。
scripts/insertTable.ts	insertTable	google-docs	行×列の表を挿入します。必要に応じてセルの内容も設定できます。
scripts/modifyTable.ts	modifyTable	google-docs	参照セルの位置に表の行または列を追加、あるいは削除します。
scripts/createHeader.ts	createHeader	google-docs	テキストを含む既定のヘッダーを作成します。formatText で書式設定するための segmentId を返します。
scripts/createFooter.ts	createFooter	google-docs	テキストを含む既定のフッターを作成します。formatText で書式設定するための segmentId を返します。
scripts/createFootnote.ts	createFootnote	google-docs	脚注参照を挿入し、insertText で使用する segmentId を返します。

曖昧さの解消と拒否

書き込み前に曖昧さを解消します。 findDocuments で名前を指定して検索したドキュメントを編集する前に、タイトルが大文字と小文字を区別せず完全一致するものの件数を数えます。

• 一致するものがちょうど1件 — そのドキュメントに対して操作します。必要以上に確認を求めないでください。曖昧さのない一致が1件なら、それが対象です。
• 2件以上が同率で一致 — 操作を中止します。各候補を区別できるフィールド（modifiedTime または url）とともに列挙し、どれを指しているのかユーザーに確認します。恣意的に選んだり、すべて編集したりしないでください。

これはインデックス位置にも当てはまります。getDocument／findText のインデックスは、編集を行うと古くなります。次にインデックスを使った呼び出しを行う前に再読み込みしてください。編集をまたいで位置を使い回さないでください。

未対応の操作 — 未対応であることを伝えて中止し、別のツールで実行したふりをしないでください。 このカタログでは、意図的に次の操作に対応していません。

• バイナリファイルをアップロードして Doc に変換すること、または貼り付けた HTML を往復変換すること。 バイナリのアップロードには Drive コネクターを使用してください。ここではコンテンツをネイティブに作成してください。
• コメントの管理、提案の承認／却下。 getDocument は suggestionsViewMode を使って提案された編集を読み取れますが、コメントや提案を書き込むツールはありません。
• PDF、DOCX、HTML をインラインコンテンツとしてエクスポートすること。 exportDocument が返すのはプレーンテキストまたは Markdown のみです。PDF、DOCX、HTML には Drive のダウンロードリンクが必要です（Drive が提供する HTML は ZIP 形式の Web ページバンドルのみで、インラインの text/html ではありません）。

これらを依頼された場合は、未対応であることをユーザーに伝えて中止してください。代替手段として無関係なツールを使わないでください。

認証

すべてのシェイプでは、認証情報そのものではなく、1つの接続 セレクター（[<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-docs-api-gotchas.md	UTF-16 インデックス、インデックス 0 のセクション区切り、編集後に古くなるインデックス、削除できない末尾の改行、includeTabsContent、タブごとのターゲットのデフォルト、Drive を利用した検索・エクスポート・フォルダーへの配置、画像の取得とサイズ制限、PT/RGB 単位。	インデックスベースの編集（挿入・書式設定・削除）、検索と置換、画像の挿入、ドキュメントのエクスポート、またはフォルダーへの配置を行う前。
references/google-docs-batchupdate.md	降順に処理するルール、初期データを含む表への二段階入力、先頭のタブによるリストのネスト、2 つ目のセグメントインデックス空間（空のヘッダー／フッターの終了インデックス 1 → 作成時のテキスト）、最後の行を削除すると表全体が削除される動作、サポート対象の Markdown サブセット。	構造（リスト（createList／removeListFormatting）、表（insertTable／modifyTable）、ヘッダー／フッター／脚注（createHeader／createFooter／createFootnote）、または markdown: true の書き込みパス）を作成する前。