google-workspace

Google Workspace

概要

OAuth 認証を使用して、Google Drive、Gmail、Calendar、Docs を操作します。ファイルのアップロード、フォルダー管理、メール検索、カレンダー検索、ドキュメント操作に対応しています。

クイック判断ツリー

What do you need?
│
├── Google Drive
│   ├── Search files/folders → references/drive-search.md
│   │   └── Script: scripts/gdrive_search.py
│   │
│   ├── Upload files → references/drive-upload.md
│   │   └── Script: scripts/google_drive_upload.py
│   │
│   ├── Create folder structure → references/folder-structure.md
│   │   └── Script: scripts/gdrive_folder_structure.py
│   │
│   ├── Create client folder → references/create-folder.md
│   │   └── Script: scripts/create_client_folder.py
│   │
│   └── Search transcripts → references/transcript-search.md
│       └── Script: scripts/gdrive_transcript_search.py
│
├── Gmail
│   └── Search emails → references/gmail-search.md
│       └── Script: scripts/gmail_search.py
│
└── Calendar
    └── Search meetings → references/calendar-search.md
        └── Script: scripts/google_calendar_search.py

環境設定

OAuth 認証情報は、初回認証後にローカルに保存されます。

必要なファイル

• client_secrets.json - Google Cloud Console から取得
• settings.yaml - PyDrive2 の設定
• mycreds.txt - 自動生成される OAuth トークン

初回セットアップ

1. Google Cloud Console にアクセスします
2. API を有効にします：Drive、Gmail、Calendar、Docs
3. OAuth 2.0 認証情報を作成します（デスクトップアプリ）
4. client_secrets.json としてダウンロードします
5. 任意のスクリプトを実行します。OAuth の同意画面を表示するためにブラウザーが開きます

一般的な使い方

クライアントフォルダーを検索

python scripts/gdrive_search.py folder "Microsoft"

ファイルをアップロード

python scripts/google_drive_upload.py --files *.png --folder "Clients/Acme/Assets"

メールを検索

python scripts/gmail_search.py --domain "microsoft.com" --days 14

カレンダーを検索

python scripts/google_calendar_search.py "Microsoft" --days-back 30

OAuth スコープ

スコープ	用途
drive	Drive へのフルアクセス
spreadsheets	Sheets へのアクセス
documents	Docs へのアクセス
gmail.readonly	メールの読み取り
calendar.readonly	カレンダーの読み取り

費用

無料です。Google Workspace API には十分な無料利用枠があります。

セキュリティに関する注意事項

認証情報の取り扱い

• client_secrets.json - OAuth アプリの認証情報（git にコミットしないでください）
• mycreds.txt - ユーザーの OAuth トークン（git にコミットせず、.gitignore に追加してください）
• settings.yaml - PyDrive2 の設定（秘密情報は含まれないため、コミットできます）
• トークンは自動更新されます。漏えいした場合は Google アカウントの設定から取り消してください
• OAuth 認証情報をユーザー間やマシン間で共有しないでください

データのプライバシー

• ユーザー個人の Google Drive、Gmail、Calendar へのアクセス
• ファイルに機密性の高い業務情報が含まれている場合があります
• メールの内容は非常に機密性が高いため、保存を最小限にしてください
• カレンダーの予定には非公開の会議情報が含まれている場合があります
• 共有ドライブへのアクセスには、元の権限が適用されます

アクセススコープ

• 必要最小限のスコープをリクエストしてください：
  • drive - Drive へのフルアクセス（読み取り／書き込み）
  • drive.readonly - Drive の読み取り専用アクセス（可能な場合はこちらを優先）
  • spreadsheets - Google Sheets へのアクセス
  • documents - Google Docs へのアクセス
  • gmail.readonly - メールの読み取り専用アクセス
  • calendar.readonly - カレンダーの読み取り専用アクセス
• アクセスの確認／取り消し：https://myaccount.google.com/permissions

コンプライアンスに関する考慮事項

• OAuth の同意：ユーザーはアクセススコープに明示的に同意します
• GDPR：Google Workspace のデータには、EU ユーザーの個人情報が含まれています
• データレジデンシー：Google Workspace にはデータレジデンシー要件が適用される場合があります
• 共有ドライブ：組織の共有ポリシーを遵守してください
• 監査証跡：Google Admin Console で API アクセスが記録されます
• 認証情報のセキュリティ：client_secrets.json はリポジトリではなく、安全な場所に保管してください

トラブルシューティング

よくある問題

問題：OAuth トークンの有効期限切れ

症状：「Invalid credentials」または「Token has been expired or revoked」エラー **原因：**OAuth のリフレッシュトークンの有効期限が切れたか、取り消されています 解決策：

• mycreds.txt ファイルを削除します
• 任意のスクリプトを再実行して、新しい OAuth フローを開始します
• ブラウザーで認証を完了します
• 新しい mycreds.txt が自動的に作成されます

問題：ファイルが見つからない

**症状：**有効なファイル ID を指定しているのに「File not found」エラーが発生する **原因：**ファイルへのアクセス権がない、ファイルが削除されている、またはファイル ID が間違っています 解決策：

• Google Drive の URL からファイル ID を確認します
• ファイルの共有権限を確認します
• OAuth ユーザーがファイルにアクセスできることを確認します
• まずブラウザーでファイルに直接アクセスしてみます

問題：割り当て上限超過

**症状：「User rate limit exceeded」または「Quota exceeded」エラーが発生する **原因：**24 時間以内の API リクエストが多すぎます 解決策：

• 割り当てがリセットされるまで 24 時間待ちます
• 新しい割り当てが設定された Google Cloud プロジェクトを作成します
• スクリプトに指数バックオフを実装します
• API 呼び出しの頻度を減らします

Issue: settings.yaml が見つからない

症状：「settings.yaml not found」または PyDrive2 の設定エラー **原因：**PyDrive2 の設定ファイルがありません 解決方法：

• テンプレートからコピーします：cp settings.yaml.example settings.yaml
• settings 内の client_secrets.json のパスが正しいことを確認します
• save_credentials_backend が「file」に設定されていることを確認します
• settings.yaml がスクリプトの作業ディレクトリにあることを確認します

Issue: client_secrets.json が無効

症状：「Invalid client secrets」または OAuth の設定エラー **原因：**OAuth 認証情報ファイルの形式が正しくないか、内容が誤っています 解決方法：

• Google Cloud Console から再ダウンロードします
• 認証情報の作成時に「デスクトップアプリ」タイプを選択したことを確認します
• JSON 形式が有効であることを確認します
• ローカル認証用にリダイレクト URI が設定されていることを確認します

Issue: スコープへのアクセスが拒否された

症状：「Insufficient permission」エラー **原因：**OAuth の同意に必要なスコープが含まれていません 解決方法：

• OAuth セッションをリセットするために mycreds.txt を削除します
• 再認証して、要求されたすべてのスコープを許可します
• settings.yaml 内のスコープがスクリプトの要件と一致していることを確認します
• Google Cloud Console でスコープの制限を確認します

リソース

• references/drive-search.md - ファイルとフォルダーを検索
• references/drive-upload.md - Drive にファイルをアップロード
• references/folder-structure.md - フォルダー階層を作成
• references/create-folder.md - クライアントフォルダーを作成
• references/transcript-search.md - 文字起こしファイルを検索
• references/gmail-search.md - Gmail を検索
• references/calendar-search.md - カレンダーの会議を検索

統合パターン

Drive から動画制作

スキル： google-workspace → video-production 用途： Drive フォルダーからコース動画を作成 フロー：

1. レッスンファイルがある動画フォルダーを Drive で検索します
2. video-production のスクリプトを使用して動画をダウンロードします
3. タイトルスライドを追加して動画を結合し、最終出力をアップロードします

テンプレートからコンテンツを作成

スキル： google-workspace → content-generation 用途： ブランドテンプレートからドキュメントを生成 フロー：

1. Drive からテンプレート（提案書、レポート形式）を読み込みます
2. content-generation を使用してコンテンツを生成します
3. 書式設定されたコンテンツで新しい Google Doc を作成します

カレンダーから文字起こしを検索

スキル： google-workspace → transcript-search 用途： カレンダーの予定から会議の録画を検索 フロー：

1. 特定のクライアントとの会議をカレンダーで検索します
2. 会議の日付とタイトルを取得します
3. transcript-search で一致する録画を検索します