google-workspace

Google Workspace

コードを記述したり、API スニペットを貼り付けたりする前に、Google Workspace の作業を適切な方法に振り分けるには、このスキルを使用します。重要な判断は通常、どの Workspace の実行環境に処理を任せるかです。

• Apps Script：Sheets／Docs／Forms／トリガー／メニューに密接に関係する、Workspace ネイティブの自動化
• 直接の REST API とクライアントライブラリ：バックエンドサービス、複数システム間の連携、より強力なデプロイ制御、または言語の柔軟性が必要な場合
• Admin SDK／管理者専用 API：ユーザー、グループ、組織部門、ディレクトリデータ、またはドメイン全体のガバナンスに関する作業

このスキルを使う場面

• Docs、Sheets、Slides、Drive のファイルやフォルダー、Gmail のメッセージ、Calendar の予定、Forms、Chat のメッセージを作成または更新する
• Form → Sheet → Gmail／Calendar／Drive などの Workspace 自動化フローを設計する
• Apps Script と直接の REST API のどちらを使うか判断する
• 適切な認証方式を選ぶ：OAuth ユーザーフロー、サービスアカウント、またはドメイン全体の委任
• 実装前にスコープ、共有モデル、クォータ／実行時のリスク、安全上の境界を確認する
• 通常の Docs／Sheets／Gmail のコードに担わせるべきではない Workspace 管理タスクを処理する

手順

Step 1：リクエストを分類する

API に触れる前に、次の 5 項目を把握します。

1. 主要なプロダクト環境 — Docs、Sheets、Slides、Drive、Gmail、Calendar、Forms、Chat、または Admin SDK
2. 操作 — 作成、読み取り、更新、検索、共有、送信、スケジュール設定、エクスポート、一括更新、管理
3. 実行者／ID — エンドユーザー、サービスアカウント、委任された管理者、または Apps Script の所有者
4. 実行場所 — Workspace の UI／ランタイム内、バックエンドサービス、cron／バッチワーカー、または複合ワークフロー
5. トリガー／実行頻度 — 手動、フォーム送信、スケジュール実行、Web リクエスト、一括移行、管理イベント

ユーザーが複数の Workspace アプリについて説明している場合は、単一 API の問題ではなく、まずワークフローの問題として扱います。

Step 2：実行環境を選択する

次の場合は Apps Script を使用する

• ワークフローが Sheets／Docs／Forms／Gmail を中心としており、Workspace 内で完結させる必要がある
• トリガー、カスタムメニュー、サイドバー、その他の Workspace ネイティブなスクリプト機能が必要である
• 別のバックエンドを用意するより、バインドされたスクリプトのほうが簡潔である
• バックエンドのデプロイ制御より、Workspace 内での JavaScript の使いやすさが重要である

次の場合は直接の REST API を使用する

• ワークフローがバックエンド、連携サービス、CLI、またはバッチジョブで実行される
• デプロイ、テスト、再試行、または JavaScript 以外のスタックをより強力に制御する必要がある
• タスクが Workspace と外部システムにまたがっており、バインドされたスクリプトのランタイムに依存すべきではない
• Apps Script のクォータやランタイム制限がボトルネックになる可能性が高い

次の場合は Admin SDK／管理 API を使用する

• ユーザー、グループ、組織部門、ロール、またはドメイン管理に関する作業である
• タスクにドメイン全体の委任アクセスが含まれる
• Docs／Sheets の編集など、通常のコンテンツ操作の範囲を明らかに超えるリクエストである

外部自動化レイヤーは別の手段としてのみ案内する

• ユーザーがノーコード／複数アプリのオーケストレーターを本当に必要としている場合は、代替手段として Zapier／Make／n8n などのツールを案内します。
• このスキルを、汎用的なノーコードプラットフォームのチュートリアルにしないでください。

Step 3: 認証モデルを選択する

認証モデル	使用する場面	主な対象	備考
OAuth ユーザーフロー	実際のユーザーのメールボックス、カレンダー、Drive、ドキュメント、または個人コンテンツを操作する場合	Gmail、Calendar、Drive、Docs、Sheets、Slides、Forms、Chat	ユーザー所有データには最適なデフォルトです
サービスアカウント	バックエンドの自動化でデータを所有する、または共有リソースを操作する場合	Drive、バックエンドで生成するドキュメント／スプレッドシート、サービスワークフロー	共有ドライブ／ファイルへのアクセス設計が必要になる場合があります
サービスアカウント＋ドメイン全体の委任	管理者または組織全体の操作で、ユーザーになりすます必要がある場合	Admin SDK、組織全体の Gmail／Calendar／Drive ワークフロー	セキュリティ上の負担が大きいため、スコープを絞ってください
Apps Script バインド認証	ワークフローが意図的に Workspace 内で実行され、スクリプト所有者／インストールモデルに紐づく場合	Sheets、Docs、Forms、Gmail、Calendar、Drive	手早く始められますが、実行時の制約や割り当てには引き続き注意が必要です

ルール：

• タスクを満たす範囲で最も限定的なスコープを選択してください。
• 認証情報やトークンをリポジトリに含めないでください。
• タスクでユーザーのメールボックス／カレンダー／ファイルを操作する場合、どのユーザーの ID で操作するのかを明記してください。
• 管理者権限が必要な場合は、その一連の処理を通常のコンテンツ編集ロジックから分離してください。

Step 4: 適切な Workspace プロダクトに振り分ける

プロダクト	適した用途	一般的な操作	次の場合は別の方法を検討
Docs	書式設定されたテキスト文書	ドキュメントの作成、プレースホルダーの置換、テキスト／表／画像の挿入、エクスポート	成果物が実際にはスライドデッキまたはスプレッドシートの場合
Sheets	表形式のワークフローや軽量な運用データベース	行の追加／更新、書式設定、数式、フィルター、承認、ダッシュボード	ユーザーが堅牢なデータベース設計や BI モデリングを必要としている場合
Slides	プレゼンテーションの生成や更新可能なデッキ	スライドの作成、プレースホルダーの置換、サムネイル、一括更新	実際の作業が API の実行ではなく、デッキの戦略／コンテンツ設計である場合
Drive	ストレージ、共有、フォルダー階層、エクスポート／インポート	ファイルのアップロード、フォルダーの作成、ファイルの検索、権限、共有ドライブ	主な課題が Drive API の呼び出しではなく、情報アーキテクチャである場合
Gmail	メールボックスの自動化や送信メッセージ	下書き、送信、ラベル、検索、スレッド操作	主な作業がメールボックスの運用ではなく、メール作成戦略である場合
Calendar	スケジュール設定やイベントの自動化	イベントの作成、参加者の招待、時刻の同期、Meet リンク	中心的な課題が会議のポリシーやロードマップの計画である場合
Forms	受付、アンケート、クイズ、回答処理パイプライン	フォームの作成／更新、回答の収集、Form → Sheet ワークフロー	作業が実装ではなく、アンケート設計の方法論である場合
Chat	Workspace のメッセージング自動化	メッセージの投稿、ボットフロー、通知	ユーザーがより広範なチャットオプスプラットフォームの設計を必要としている場合
Admin SDK	ディレクトリおよびドメインの管理	ユーザー、グループ、組織部門、ライセンス、設定	通常のコンテンツワークフローに過剰な管理者権限が適用されている場合

Step 5: サービス横断の一般的な作業にはワークフローパケットを使用する

フォーム受付パケット

• Forms が送信内容を受け取ります
• Sheets が回答を保存／確認します
• Gmail または Chat がフォローアップ通知を送信します
• 必要に応じて Calendar が面接、会議、またはリマインダーを予定します

承認／運用パケット

• Sheet がキュー／状態を保存します
• Apps Script またはバックエンドワーカーが行／ステータスを評価します
• Gmail または Chat が承認プロンプト／更新情報を送信します
• Drive が生成された成果物または添付ファイルを保存します

レポートパケット

• Sheets が指標または抽出データを保持します
• Docs／Slides が説明を含む出力を公開します
• Drive が共有アクセスとエクスポートを管理します
• Calendar／Gmail がスケジュールに沿った配信を処理します

複数段階のフローでは、次を定義します：

• 信頼できる唯一の情報源
• トリガー元
• 実行者の ID
• 冪等性／重複送信のルール
• 障害通知の経路

Step 6: クォータと実行時のリスクを確認する

計画を確定する前に、ワークフローが次のいずれかに該当するか確認します。

• 大量処理、または一括編集が多い
• 頻繁にトリガーされるスケジュール駆動型である
• Apps Script の実行時間やランタイムの制限に達する可能性が高い
• 大規模な Drive の走査、Gmail の送信、またはスプレッドシートへの大量書き込みに依存している

該当する場合：

• 対応している場合はバッチ操作を優先します
• 1 回のバッチ呼び出しで済む場合は、行ごとの細かなループを避けます
• 実行時間の上限が実際の制約になる場合は、Apps Script からバックエンドワーカーへの移行を検討します

Step 7: 具体的な実行パケットを作成する

次の内容を含む簡潔な計画を返します。

• 選択した Workspace の操作対象
• 選択した認証モデル
• 必要なスコープ／管理者の境界
• 必要な主要オブジェクト ID（docId、spreadsheetId、folderId、ユーザーのメールアドレス、calendarId、formId）
• 実装の手順
• 検証手順
• 別の方法への切り替え／リスク

例

例 1: フォーム → シート → メールのワークフロー

プロンプト: 「従業員フィードバックフォームを作成し、回答を Sheets に収集して、確認メールを送信してください。」

このスキルを使用して、次のことを行います。

• 複数サービスにまたがるワークフローとして分類する
• 自動化をどこで実行するかに応じて、Apps Script または軽量なバックエンドを選択する
• Forms + Sheets + Gmail をサービスの組み合わせとして特定する
• 実装前に認証／スコープとトリガーの動作を指定する

例 2: 共有 Drive のオンボーディングパケット

プロンプト: 「新しいクライアント用に共有 Drive のフォルダー構造を作成し、3 人のユーザーと共有して、キックオフ用ドキュメントを作成してください。」

このスキルを使用して、次のことを行います。

• Drive を主要な操作対象、Docs を二次的な成果物レイヤーとして選択する
• 所有モデルに基づいて OAuth またはサービスアカウントによるアクセスを選択する
• コーディング前にフォルダー ID、ユーザーのメールアドレス、共有ルールを列挙する

例 3: Workspace 管理者へのリクエスト

プロンプト: 「退職するユーザーを停止し、別の組織部門に移動して、グループへの所属状況を監査してください。」

このスキルを使用して、次のことを行います。

• 直ちに Admin SDK に切り替える
• 実行パケットで、管理者／委任された ID に関する確認を必須にする
• 管理者操作を通常の Docs／Drive 編集ロジックから分離する

例 4: Sheets 中心の承認自動化

プロンプト: 「このスプレッドシートを、リマインダーメールとステータス更新を備えた承認キューにしてください。」

このスキルを使用して、次のことを行います。

• バインドされた Apps Script で十分かどうかを判断する
• ステータス列、リマインダーの頻度、Gmail との連携を定義する
• トリガーが多いソリューションを約束する前に、クォータと実行時のリスクを確認する

ベストプラクティス

1. コード例ではなく、まず操作対象の選択から始めます。
2. コンテンツ操作と管理者操作を分離します。
3. Workspace に適した使いやすさには Apps Script を使い、バックエンドの制御や規模が重要な場合は直接 API を使います。
4. スコープを必要最小限にし、誰の ID で操作するのかを明確にします。
5. 複数アプリにまたがるワークフローでは、まず信頼できる情報源とトリガーの発生元を定義します。
6. API がバッチ処理に対応している場合は、行ごと／セルごとの細かなループではなく、一括更新を優先します。
7. 実際の課題がメール、ドキュメント、アンケート、ダッシュボード、またはプレゼンテーションの作成である場合は、Workspace の実行パケットを明確にしてから、該当するコンテンツスキルに切り替えます。

参考資料

• references/auth-and-scope-routing.md — OAuth、サービスアカウント、ドメイン全体の委任の使い分け
• references/service-selection-matrix.md — Docs／Sheets／Drive／Gmail／Calendar／Forms／Admin SDK の各プロダクトの使い分け
• references/workflow-patterns-and-quotas.md — サービス横断型の一般的なパケットと、クォータ／実行時間に関する注意点
• Google Workspace の開発者向けドキュメント: https://developers.google.com/workspace
• 認証の概要: https://developers.google.com/workspace/guides/auth-overview
• Apps Script のサンプル: https://developers.google.com/apps-script/samples
• Apps Script のクォータ: https://developers.google.com/apps-script/guides/services/quotas
• Forms の REST API と Apps Script の比較: https://developers.google.com/workspace/forms/api/guides/compare-rest-apps-script